企业官网建设流程全解析

• 跨平台
• 移动开发
• 前端

本文以 Hippy 3.x 在 Android 平台上的 SDK 集成为主线，完整覆盖 Android Studio 环境配置（NDK / CMake / Gradle / AGP / JDK 版本约束）、Maven 与本地 AAR 两种集成方式、以及引擎初始化与hippyRootView挂载的核心代码流程。读完本文，你可以将 Hippy 3.x SDK 接入现有 Android 工程，理解各构建参数的来源（可对照仓库内 gradle.properties 与 framework/android/gradle.properties），并掌握 3.0 版本引擎初始化的调用链与销毁时序等关键约定。

一、Android Studio 环境配置

以下文档都假设开发者已经具备一定的 Android 开发经验。在集成 Hippy 3.x SDK 之前，需要按仓库工程配置锁定一组工具链版本。这些版本已在工程配置文件中指定，其中 NDK 会在第一次 Sync project 时自动安装，CMake 需要开发者在Settings > Android SDK中手动下载并设置：

这些版本号的来源可以在仓库中直接确认：根目录 gradle.properties 指定了MIN_VERSION=21、COMPILE_VERSION=33、TARGET_VERSION=30等 SDK 侧参数；而 framework/android/gradle.properties 中显式定义了NDK_VERSION=25.0.8775105与CMAKE_VERSION=3.22.1，framework/android/build.gradle 则通过ndkVersion = NDK_VERSION、cmake { version CMAKE_VERSION ... }将其应用到构建流程。

注意：由于暂未对 8.x AGP 及 Gradle 版本作适配，请忽略 Android Studio 中弹出的 AGP 升级提示。

此外，在Settings > Build, Execution, Deployment > Build Tools > Gradle中下载并设置 Version 17 的 JDK 版本：

完成配置后执行 Sync project 即可完成 Gradle 构建。

从源码结构看，本仓库采用 CMake 统一驱动 C++ 模块编译：framework/android/build.gradle 中通过-DMODULES=${getAllModules().join(';')}将REQUIRED_MODULES=support, dom与OPTIONAL_MODULES=driver/js, renderer/native（见根 gradle.properties）拼接成 CMake 参数传入src/main/cpp/CMakeLists.txt，因此 CMake 版本锁定是构建成功的必要前提。

二、Demo 体验

若想快速体验，可以直接基于仓库自带的 Android Demo 工程来开发。该 Demo 的源码位于framework/examples/android-demo/src/main/java/com/openhippy/example/下，其中HippyEngineWrapper.kt完整演示了从引擎创建、初始化、加载 JS 模块到挂载根视图的全流程，是后续章节讲解的参照实现。

三、快速接入

3.1 创建 Android 工程

创建一个 Android 工程（SDK 工程支持的minSdkVersion=21，宿主工程支持的minSdkVersion不能低于该版本）。这一约束与根 gradle.properties 中MIN_VERSION=21的取值一致。

3.2 Maven 集成

在 Maven Central 上查询com.tencent.hippy组下的 Hippy 版本后，配置build.gradle（下面引用 Hippy 的版本号可在 Maven Central 查询，此处为文档给出的示例版本）：

implementation 'com.tencent.hippy:release:3.3.3' implementation 'androidx.legacy:legacy-support-v4:1.0.0' implementation 'androidx.recyclerview:recyclerview:1.1.0' implementation 'androidx.viewpager:viewpager:1.0.0'

关于坐标com.tencent.hippy:release的构成，可以从仓库的发布配置中得到印证：framework/android/gradle.properties 中定义了PUBLISH_GROUP_ID=com.tencent.hippy，并注明PUBLISH_ARTIFACT_ID=release对应 release 构建（另有hippy-release/hippy-debug两种可选 artifact 命名），framework/android/publish.gradle 负责实际的发布逻辑。另外，由于 AAR 中通过consumerProguardFiles 'proguard-rules.pro'（见 framework/android/build.gradle）自动附加混淆规则，宿主工程一般无需额外处理 Hippy 的 ProGuard 配置。

3.3 本地集成（可选）

如果对 SDK 有二次开发或源码调试需求，可以选择本地集成：

1. 在 hippy-framework 工程运行 Gradle Taskother => assembleRelease或者other => assembleDebug，会在framework/android/build/outputs/aar目录下生成release或者debug模式的android-sdk.aar，将android-sdk.aar拷贝到你项目的libs目录下。

   AAR 产物名android-sdk来源于 framework/android/gradle.properties 中的ARCHIVES_BASE_NAME=android-sdk；framework/android/build.gradle 的dealAfterAssemble任务在assembleRelease/assembleDebug完成后会统一重命名产物，并将 release 产物同步拷贝到 android-demo/libs 供 Demo 使用。

   注意：通过assembleReleasetask 生成的 AAR 默认不携带inspector模块，不能在前端通过 Devtools 对代码进行调试。若需要集成inspector，请执行assembleDebugtask。这一点与构建脚本一致：仅 debug 构建类型的 CMake 参数中包含-DENABLE_INSPECTOR=$ENABLE_INSPECTOR，而 release 构建没有该项。

2. 配置build.gradle：

api (name:'android-sdk', ext:'aar') implementation 'androidx.legacy:legacy-support-v4:1.0.0' implementation 'androidx.recyclerview:recyclerview:1.1.0' implementation 'androidx.viewpager:viewpager:1.0.0'

需要留意的是，本地 AAR 是 fat-aar 产物：framework/android/build.gradle 中embed了:serialization、:hippy-support、:vfs、:pool、:devtools-integration以及各 connector 模块（framework/android/connector下的 dom、driver、renderer 子模块由根 settings.gradle 动态 include），因此本地集成时不要再重复引入这些子模块。

3.4 引擎初始化与 hippyRootView 挂载

最后一步是在宿主 APP 工程中增加引擎初始化与hippyRootView挂载逻辑。参照 Android Demo 工程中HippyEngineWrapper的实现（HippyEngineWrapper.kt），完整流程分为四步：

（1）构造 EngineInitParams 并创建引擎

val initParams = EngineInitParams() initParams.context = context initParams.debugServerHost = debugServerHost // 调试服务器地址，调试模式下使用 initParams.debugMode = isDebug initParams.enableLog = true initParams.logAdapter = DefaultLogAdapter() initParams.groupId = 1 // 根据前端框架选择核心 JS 资源 initParams.coreJSAssetsPath = "react/vendor.android.js" // 或 "vue2/..."、"vue3/..." initParams.codeCacheTag = "common_1.0" // 建议 tag 拼接 js version，tag 会用来拼接 v8 code cache 文件的路径 initParams.exceptionHandler = object : HippyExceptionHandlerAdapter { override fun handleJsException(e: HippyJsException) { LogUtils.e("hippy", e.message) } override fun handleNativeException(e: Exception, haveCaught: Boolean) { LogUtils.e("hippy", e.message) } override fun handleBackgroundTracing(details: String) { LogUtils.e("hippy", details) } } val providers: MutableList<HippyAPIProvider> = ArrayList() providers.add(ExampleAPIProvider()) initParams.providers = providers initParams.enableTurbo = true val hippyEngine = HippyEngine.create(initParams)

引擎入口为 HippyEngine.java 中的public static HippyEngine create(EngineInitParams params)。

（2）初始化引擎

hippyEngine.initEngine(object : EngineListener { override fun onInitialized(statusCode: EngineInitStatus, msg: String?) { if (statusCode != EngineInitStatus.STATUS_OK) return // 初始化成功后继续 loadModule } })

（3）加载 JS 模块并获取 rootView

val loadParams = ModuleLoadParams() loadParams.context = context loadParams.componentName = "Demo" loadParams.codeCacheTag = "Demo_1.0" // 建议 tag 拼接 js version loadParams.jsAssetsPath = "react/index.android.js" // 业务 bundle 路径 loadParams.jsFilePath = null loadParams.jsParams = HippyMap() loadParams.jsParams.pushString("msgFromNative", "Hi js developer, I come from native code!") hippyRootView = hippyEngine.loadModule(loadParams, object : ModuleListener { override fun onLoadCompleted(statusCode: ModuleLoadStatus, msg: String?) { /* ... */ } override fun onJsException(exception: HippyJsException): Boolean = true override fun onFirstViewAdded() { /* 第一个 view 挂载到 Hippy root view 的时机 */ } override fun onFirstContentfulPaint() { /* ... */ } })

从 HippyEngineManagerImpl.java 的抽象声明可以看到，3.0 中loadModule直接返回ViewGroup类型，宿主拿到hippyRootView后即可将其添加到自己的容器视图中。

（4）页面销毁

fun destroy() { hippyEngine.destroyModule(hippyRootView) { result, e -> hippyEngine.destroyEngine() } hippyRootView = null }

destroyModule的接口签名为void destroyModule(@Nullable ViewGroup rootView, @NonNull Callback<Boolean> callback)，必须等待销毁完成回调后才能调用destroyEngine()。

四、3.0 版本集成的关键约定

结合 3.0 架构升级指引 中的 Android 章节，接入 3.0 SDK 时还有以下约定需要注意：

1. 初始化回调线程变更：3.0 中onInitialized回调直接在子线程执行并继续执行loadModule，效率更高。此前 2.0 在 callback 中对hippyRootView相关的 UI 操作，开发者需要自己切到 UI 线程保证——Demo 中的loadCallbackTask正是通过UIThreadUtils.isOnUiThread()判断后决定是否runOnUiThread的典型处理。
2. 引擎销毁时序：destroyEngine需要等destroyModule执行完成回调以后才能调用，否则可能存在 CRASH 风险，上文的销毁示例即标准写法。
3. 接口解耦：destroyModule参数以及loadModule返回值均使用系统ViewGroup类型替代 SDK 内部视图类型，减少宿主对 SDK 的耦合。
4. onFirstViewAdded回调：loadModule的ModuleListener简化了onLoadCompleted（不再返回 root view 参数），并新增onFirstViewAdded回调，返回第一个 view 挂载到 Hippy root view 的时机，可用于撤除占位视图等场景。
5. 图片加载体系重构：2.0 中的HippyImageLoader必设项已被移除，图片数据的网络拉取与解码解耦，统一走 vfs 模块分发（网络请求最终由 HttpAdapter 处理）；新增可选的ImageDecoderAdapter（引擎初始化时通过imageDecoderAdapter参数设置），提供preDecode/afterDecode/destroyIfNeeded接口以支持自定义格式图片解码。
6. 资源请求 Processor：引擎初始化参数新增public List<Processor> processors;，可用于自定义资源请求处理链，详见 VFS 特性文档。
7. 组件事件发送：全局事件仍使用HippyEngine暴露的sendEvent接口；UI Component 事件则使用 3.0 新增工具类EventUtils封装的sendComponentEvent(@Nullable View view, @NonNull String eventName, @Nullable Object params)接口（标注@MainThread）。
8. Render node 缓存特性：3.0 重新实现了性能更好的 render node 缓存（接口如recordSnapshot/replaySnapshot，见 HippyEngine.java 及 RenderNode Snapshot 文档），Demo 的recordRenderNodeSnapshot/replaySnapshot用法可作为参考。

五、小结与延伸阅读

按本文流程完成接入后，宿主工程即可跑通「创建引擎 → 初始化 → 加载模块 → 挂载 rootView → 按回调时序销毁」的完整链路。建议进一步阅读以下仓库文档以深入各专题：

• Hippy 3.0 架构升级指引：2.0 到 3.0 的差异与升级验证关注点；
• Native 集成文档 与 原生适配文档：自定义模块 / 组件接入；
• VFS 特性 与 RenderNode Snapshot：资源分发与快照缓存特性；
• 调试文档：基于 inspector 的 Devtools 调试方式。

• 跨平台
• 移动开发
• 前端