Hippy：腾讯跨端开发框架编译与示例运行指南

Hippy 是腾讯开源的跨端开发框架，目标是让开发者"写一次代码，运行在多个平台"，目前支持 iOS、Android、Web 等平台。它对 Web 前端开发者非常友好，尤其是熟悉 React 或 Vue 的工程师，因为 Hippy 官方直接提供了 React 与 Vue 两套前端 SDK，前端团队可以用熟悉的组件模型、样式语法和路由方式来开发原生 App，而不需要学习 iOS/Android 原生开发。

在跨端技术的演进历程中，React Native、Weex 等方案都曾试图解决"前端代码跑在原生上"的问题，但它们在性能、包体积、学习曲线和企业级支持上各有取舍。Hippy 是腾讯内部经过多年打磨后开源的方案，它的定位是"用前端的方式做原生 App"：JS 层负责业务逻辑与组件描述，原生层负责渲染与系统能力，两者通过 JS 引擎绑定通信。这种架构的好处是，前端开发者不需要学习 Objective-C 或 Kotlin，就能写出在 iOS 和 Android 上表现一致的页面；原生开发者则只需要维护一套稳定的渲染引擎，而不需要为每个业务页面单独开发。业务迭代速度因此大幅提升，原生团队也能从重复的页面开发中解放出来。

Hippy 目前已经在腾讯多款主力 App 中落地，例如手机 QQ、手机 QQ 浏览器、腾讯视频 App、QQ 音乐 App、腾讯新闻等，覆盖数亿普通用户，是国内大规模生产环境验证过的跨端框架之一。它同时提供 React 与 Vue 两套前端 SDK，团队可以按现有技术栈选择；并支持平滑迁移到 Web 浏览器，也就是说同一份业务代码可以同时跑在 App、小程序容器和 Web 上。这种"一套代码多端运行"的能力，是 Hippy 区别于单纯原生开发的核心价值，也是它被腾讯内部众多业务线采用的原因。本文基于仓库 README 逐节完整翻译整理，从项目背景、核心优势、环境准备、iOS/Android 示例编译、调试与生产打包到项目结构做全面说明。

一、项目官方信息

项目	信息
项目名称	Hippy（跨端框架）
GitHub 仓库	Tencent/Hippy
出品方	腾讯
官方主页	framework.tds.qq.com
开源协议	Apache-2.0（见 LICENSE）
Node 要求	Node.js >= 10.0.0
布局引擎	Taitank
生态	Hippy Eco-System

二、官方图片与架构

Hippy 的整体架构可以理解为"前端 SDK + 原生渲染引擎"：前端用 React 或 Vue 写页面，Hippy 的 JS Driver 把组件树翻译成原生视图操作，再由原生渲染层在 iOS/Android 上渲染成真正的原生控件，而不是 WebView。这样既保留了前端的开发效率，又获得了接近原生的流畅度，而不是 WebView 那种"套壳网页"的体验。

布局引擎采用腾讯自研的 Taitank，完整支持 Flexbox 布局，前端写的 display: flex 样式会被翻译成原生布局计算，而不是浏览器的布局引擎。这意味着前端开发者熟悉的 Flexbox 布局在原生 App 中行为一致，不会出现"浏览器上正常、原生上错位"的问题。JS 引擎在 Android 端使用腾讯 X5 内核，因此不支持 x86 模拟器，ARM 模拟器性能也较差，官方建议 Android 调试直接使用真机。X5 内核是腾讯为移动端浏览器优化的内核，在国内机型上兼容性更好、启动更快。Hippy 还提供了独立的 DevTools（仓库根目录 devtools），用于调试 JS 代码与页面结构；DOM 层（dom）负责维护组件树；渲染层（renderer）则同时提供 native 与 flutter 两种实现，未来可以向 Flutter 渲染扩展。这种分层设计让 Hippy 既能在现有 native 渲染上跑，也能逐步迁移到 Flutter 渲染，而业务代码不需要重写。modules 目录下的 footstone 是 Hippy 的基础库，提供日志、工具类、跨端通信等能力；static 目录存放静态资源。framework/examples 下的 android-demo 与 ios-demo 是官方示例工程，用于快速验证 Hippy 能力。封面沿用本文既有官方仓库图，不再改动。

三、环境要求

根据 README 的说明，本地开发需要先准备好 git 和 npm。Node.js 版本要求 >= 10.0.0，建议使用 LTS 版本。克隆仓库后在根目录执行 npm install。需要特别注意：Hippy 仓库使用 git-lfs 管理 .so、.gz、.otf 等大文件，必须先安装 git-lfs 才能正确拉取这些资源，否则会导致 native 库缺失、编译失败。git-lfs 安装后需要执行 git lfs install 初始化。

macOS 开发者：需要安装带 iOS SDK 的 Xcode（用于编译 iOS App）、带 NDK 的 Android Studio（用于编译 Android App）、以及 Node.js（用于跑构建脚本）。推荐使用 homebrew 安装依赖。CocoaPods 与 cmake 也可以通过 homebrew 一键安装，无需手动配置。
Windows 开发者：需要带 NDK 的 Android Studio 与 Node.js；Windows 目前无法运行 iOS 开发环境，只能做 Android 端开发。Windows 上也需要先安装 git-lfs，否则拉取仓库时 native 库文件会缺失。
依赖管理：Hippy 使用 Lerna 管理多个 npm 包，如果 lerna 命令找不到，先执行 npm install lerna -g。Lerna 的作用是把 driver/js/packages 下的多个子包（hippy-react、hippy-vue、hippy-vue-next 等）统一安装依赖、统一构建，避免每个子包单独处理版本与依赖关系。

四、部署步骤

1. 编译 iOS 模拟器示例

官方建议第一次尝试用 iOS 模拟器跑通流程：

cd 到 driver/js/ 目录；
执行 npm run init。这个命令等价于 npm install && npx lerna bootstrap && npm run build：npm install 安装项目构建脚本依赖，npx lerna bootstrap 安装每个 npm 包的依赖，npm run build 构建各前端 SDK 包。首次执行耗时较长。
用 npm run buildexample [hippy-react-demo|hippy-vue-demo|hippy-vue-next-demo] 选择一个示例编译；示例名对应 React、Vue 2、Vue 3 三套前端栈。
用 brew install cocoapods 安装 CocoaPods，用 brew install cmake 安装 cmake，然后在 framework/examples/ios-demo 目录执行 pod install，生成 HippyDemo.xcworkspace 并安装依赖。cmake 是 Hippy iOS 原生工程依赖的构建工具，用于编译 C++ 层代码。
打开 framework/examples/ios-demo/HippyDemo.xcworkspace，用 Xcode 编译并运行 iOS App。选择模拟器后直接 Run 即可，首次运行会较慢。

如果第 2 步报错，可以 cd 到 driver/js/examples/ 下对应的 hippy-react-demo 或 hippy-vue-demo 目录，先单独执行 npm install 安装示例依赖。更详细的集成说明见 iOS SDK 集成指南。首次编译时 Xcode 会下载依赖并编译原生工程，耗时较长，后续增量编译会快很多。如果是 iOS 开发熟手，也可以修改 Xcode 配置，把 App 直接安装到真机上调试，而不是用模拟器。

2. 编译 Android 示例

Android 端官方强烈建议使用真机调试，因为 Hippy 使用 X5 JS 引擎，不支持 x86 模拟器，ARM 模拟器性能也较差。编译前请确认 SDK 与 NDK 已安装，并且不要升级构建工具链，否则可能遇到 NDK 版本不兼容问题。官方特别提醒"不要升级 build toolchain"，是因为 Hippy 工程对 NDK 版本有固定要求。

cd 到 driver/js/ 目录；
执行 npm run init，这个命令会依次完成依赖安装、lerna bootstrap 和前端包构建。
用 npm run buildexample [hippy-react-demo|hippy-vue-demo|hippy-vue-next-demo] 选择示例；
在根目录用 Android Studio 打开 Hippy Project；
用 USB 连接 Android 手机并开启 USB 调试（在电脑终端执行 adb devices 确认连接）；
在 Android Studio 中运行并安装 apk。

如果遇到 No toolchains found in the NDK toolchains folder for ABI with prefix: mips64el-linux-android 错误，参考这个解决方案。更详细的集成说明见 Android SDK 集成指南。连接真机后，建议在手机上开启"开发者选项"与"USB 调试"，并允许电脑调试授权。Android Studio 打开工程后会自动同步 Gradle，首次同步时间较长，需要等待依赖下载完成。

3. 调试 JS 示例

先按上文编译好 App；
cd 到 driver/js/；
执行 npm run init:example [hippy-react-demo|hippy-vue-demo|hippy-vue-next-demo]；
执行 npm run debugexample [hippy-react-demo|hippy-vue-demo|hippy-vue-next-demo] dev。

也可以直接 cd 到对应示例目录执行 npm run hippy:dev。调试模式下 @hippy/react、@hippy/vue、@hippy/vue-next 等包会链接到本地 driver/js/packages 下的 dist 目录（而不是 node_modules），因此如果你改了 JS 包源码，需要重新执行 npm run build 才能在示例中生效。调试模式还支持热更新，修改 JS 代码后页面会自动刷新，便于快速迭代。Hippy DevTools 可以查看组件树、网络请求、日志等。更多调试细节见 Hippy 调试文档。

4. 生产打包

先按上文编译好 App；
cd 到对应示例目录（driver/js/examples/hippy-react-demo 等）；
执行 npm install 安装示例 JS 依赖；
依次执行 npm run hippy:vendor 与 npm run hippy:build，生成生产环境的 vendor.[android|ios].js 与 index.[android|ios].js。

Hippy 示例使用 DllPlugin 把公共 chunk 与业务 chunk 分离，从而优化加载速度：vendor.js 包含 React/Vue 等公共依赖，变化频率低；index.js 是业务代码，发版频繁。这样可以实现增量更新，减少用户每次升级需要下载的 JS 体积。生产环境的 JS 文件会被压缩与混淆，体积远小于调试版本，适合直接打包进 App 或下发到 CDN。Hippy 的 JS 包更新机制让业务可以不发版就修复线上问题，这对快速迭代非常重要。

五、核心优势

README 列出的核心优势包括：为 Web 开发者设计，官方支持 React 与 Vue 两套框架；不同平台 API 一致；通过 JS 引擎绑定通信实现出色性能；内置可回收组件提升性能；可以平滑优雅地迁移到 Web 浏览器；完整支持 Flex 布局引擎 Taitank。

这些特性让前端团队几乎零成本迁移，同时获得原生级别的渲染性能。"可回收组件"指的是类似于 Android RecyclerView 的回收机制，列表项滑出屏幕后会被复用，而不是频繁创建销毁，从而降低内存占用、提升滚动流畅度。"不同平台 API 一致"意味着同一份业务代码在 iOS 和 Android 上调用同一套 JS 接口，不需要为平台写分支逻辑，官方通过原生层抹平了差异。"平滑迁移到 Web"则让 Hippy 业务可以复用在 Web 页面上，实现一套代码多端运行。"通过 JS 引擎绑定通信"指的是前端 JS 与原生渲染层之间通过高效的序列化通道通信，避免了 WebView 方案的性能损耗。官方生态中还有 Hippy Eco-System 维护的周边组件与工具，覆盖常见 UI 组件、状态管理、路由等需求。

六、项目结构

Hippy
├── devtools          # Hippy 调试工具
├── dom              # Hippy DOM 层
├── driver           # 不同 UI Driver 层
│   └── js           # JS Driver 层
│       ├── examples # JS Driver 相关示例
│       ├── packages # 相关 JS 包（hippy-react、hippy-vue 等）
│       └── src
├── framework        # 原生框架
│   ├── android
│   ├── examples     # android-demo、ios-demo
│   └── ios
├── layout           # 布局引擎
├── modules          # 原生模块（android、footstone）
├── renderer         # 渲染器（flutter、native/android、native/ios）
└── static

从目录结构可以看出，Hippy 采用分层架构：driver/js 是前端层，framework 是原生壳工程，renderer 是渲染层，layout 是布局引擎，modules 是原生能力模块。这种分层让前端开发者只需要关心 driver/js，原生开发者只需要关心 framework 与 renderer，职责清晰。driver/js/packages 下包含 hippy-react、hippy-react-web、hippy-vue、hippy-vue-css-loader、hippy-vue-loader、hippy-vue-native-components、hippy-vue-router 等子包，分别对应 React 绑定、React Web 版、Vue 绑定、CSS 处理、Vue 加载器、原生组件、路由等能力。

七、常见问题（FAQ）

Windows 能跑 iOS 示例吗？ 不能，iOS 开发必须在 macOS 上用 Xcode。
Android 模拟器能用吗？ 官方不建议，X5 引擎不支持 x86，ARM 模拟器性能差，建议真机。
改了 JS 包源码不生效？ 调试模式下包链接到本地 dist，需要重新 npm run build。
NDK 报错 mips64el-linux-android？ 参考解决方案。
如何参与贡献？ 提交 PR 前先读 Contributing Guide，贡献者名单见 Contributors 与 Authors File。腾讯项目管理委员会会定期向合格贡献者发放奖励。
如何与 React Native 选型？ Hippy 在腾讯系 App 中经过大规模验证，对 React/Vue 双栈支持更友好，且提供 Taitank 布局引擎；具体选型建议参考官方文档与团队技术栈。
生产环境如何更新 JS？ Hippy 支持 JS 包离线化与热更新，业务代码打包为 vendor.js 与 index.js 后随 App 发布，也可通过更新 JS 包实现不发版修复。
示例跑不起来怎么办？ 确认 git-lfs 已安装、Node 版本 >= 10、Lerna 已全局安装，然后按 README 顺序执行 npm run init、buildexample、pod install。
如何升级 Hippy 版本？ 关注 Releases 中的变更记录，按官方迁移指南升级前端 SDK 与原生依赖。
Hippy 与 Weex 的关系？ Hippy 是腾讯自研的跨端框架，与 Weex 是平行方案，均经过大规模生产验证，但 Hippy 提供 React/Vue 双栈与 Taitank 布局引擎，且仍在活跃维护。
如何查看版本变更？ 见 Releases，每个版本都有详细 changelog。
Hippy 支持哪些前端框架？ React 与 Vue 都有官方 SDK，Vue 3 对应 hippy-vue-next。
Hippy 如何学习？ 官方文档在 doc.openhippy.com，包含集成指南、调试文档等；GitHub 上也有示例工程。
Hippy 与 Taitank 是什么关系？ Taitank 是 Hippy 使用的 Flex 布局引擎，独立开源，可被其他项目复用。
Hippy 商业使用需要授权吗？ Hippy 采用 Apache-2.0 协议，商用友好，无需额外授权，可放心用于商业项目。
Hippy 与 Flutter 的关系？ Hippy 渲染层已预留 Flutter renderer，未来可在 Flutter 渲染上复用业务代码。
Hippy 示例有哪些？ 官方提供 hippy-react-demo、hippy-vue-demo、hippy-vue-next-demo 三个示例，分别对应 React、Vue 2、Vue 3。

八、跳转链接

项目主页：https://github.com/Tencent/Hippy
官方文档：framework.tds.qq.com
Release 说明：Releases
生态项目：Hippy Eco-System
布局引擎：Taitank
贡献者名单：Contributors