企业官网建设流程全解析

如果你在一个小团队里同时维护三端应用，最近又接到了“把 App 搬到 OpenHarmony 上”的需求，大概率会和我一样，先盯着 React Native 的版本号发呆好一阵。我在 AnimeHub 这个追番社区项目里负责随机推荐页面的开发，表面上看，这就是“一个卡片区加一个换一批按钮”的事，真正做起来，从数据接口、随机算法、卡片动效到图片内存，每层都藏着坑，而且只要叠加 OpenHarmony 的适配问题，坑就连成片了。下面就是我从立项到上线的完整过程，适合准备在 OpenHarmony 上接入 React Native 的团队，也适合想看看一个推荐页能挖出多少细节的开发者。

1. 为什么我会用 React Native 去啃 OpenHarmony 这块硬骨头

1.1 AnimeHub 要面对的设备碎片化

AnimeHub 本身不是一个全新项目。在决定支持 OpenHarmony 之前，我们已经有了一套成熟的 React Native 代码库，Android 和 iOS 两端共用同一套 JS 业务逻辑，包括首页信息流、番剧详情、追番列表和社区动态。新增一个平台，最怕的不是多写代码，而是把一套已经验证过的业务逻辑用另一套技术栈重写一遍，那犯错的概率是呈指数级上升的。

OpenHarmony 的设备形态这两年铺开得比预期快，从手机到平板，再到各种带屏设备，对 AnimeHub 这种内容型应用来说，新增渠道的价值非常明显。但对应的问题是，前端团队没有冗余人力去维护一套 ArkUI 原生代码。这时候“RN for OpenHarmony”就进入了选型视野，它做的正是我在 Android 和 iOS 上一直在做的事：让 JS 写业务，让原生层负责渲染和系统能力。

1.2 RN for OpenHarmony 到底是怎么跑起来的

很多人以为“RN for OpenHarmony”是把 RN 塞进一个 WebView 里跑，这是最大的误解。它的实际架构是社区基于 OpenHarmony 的 ArkUI 能力，重新实现了一套 React Native 的原生渲染链路。

简单说，JS 业务代码依然运行在 JavaScript 引擎里，组件树通过 JSI 或者 Bridge 与原生侧通信，原生侧再把每一个 React 组件映射成 ArkUI 的组件进行渲染。你可以把它理解成一个“翻译官”：React 的 View 对应到 ArkUI 的 Column 或 Stack，React 的 Text 对应到 ArkUI 的 Text，React 的 Image 对应到 ArkUI 的 Image。这套机制在 Android 和 iOS 上已经跑了快十年，在 OpenHarmony 上只是换了一个“翻译目标”而已。

这一点想清楚之后，我对项目的信心大了很多，因为大量的业务逻辑代码可以原封不动地复用，真正要处理的只是平台差异层。换句话说，你在 RN 里写习惯了的东西，在这里大部分还能用，只是需要用“OpenHarmony 会不会在这个点上有差异”的心态重新审视一遍。

1.3 为什么不直接用 ArkUI 重写

我们内部也讨论过直接用 ArkUI 重写随机推荐页面，毕竟 OpenHarmony 官方的开发范式是 ArkTS 声明式开发，生态支持和性能预期都更稳妥。当时放弃重写的原因很实际。

第一，团队的 RN 代码库沉淀了很多和推荐系统相关的逻辑，包括埋点、缓存策略和推荐反馈接口，用 ArkUI 重写意味着这些逻辑全部要换成另一种写法，风险不可控。第二，社区里 RN 的第三方库生态更丰富，动画方案、图片加载方案在 ArkUI 里要么需要自己造轮子，要么需要额外适配，时间成本摆在那里。第三，后续规划是让 AnimeHub 的内容运营逻辑同时覆盖所有平台，共用一套 JS 逻辑能做到“改一处、处处生效”，这是双端维护给不了的效率。

所以最终方案定了：RN 为主，需要调用 OpenHarmony 特有系统能力时，用自定义原生模块补位。

2. 环境准备与项目骨架搭建

2.1 开发环境清单

先列一份我在实际搭建时用到的环境清单，版本号是这次项目当时的稳定组合，建议动手前先核对一遍官方文档。

这里有一个非常重要的原则：RN 版本和 react-native-harmony 适配版本必须严格对应，不是随便装一个最新版就能跑。社区适配 OpenHarmony 的速度往往落后于 RN 官方版本发布速度，我当时就见过有人直接升级 RN 到 0.74，结果原生侧缺了一堆映射文件，构建直接失败。

提示：RN 版本和 react-native-harmony 适配版本必须严格对应，不要直接装最新版。

2.2 初始化 AnimeHub 的 RN 工程

初始化过程本身不复杂，核心是在传统 RN 工程基础上增加 OpenHarmony 的原生工程壳。我习惯把目录分成两层：上层是纯 JS 的 RN 工程，下层是 OpenHarmony 的 hvigor 工程。

初始化时先按标准 react-native init 生成 RN 工程，再通过 react-native-harmony 提供的初始化脚本，在工程里生成一个 harmony 目录，里面就是完整的 DevEco Studio 工程结构。目录大概长这样：

AnimeHub/ ├── src/ # JS 业务代码 ├── harmony/ # OpenHarmony 原生工程壳 │ ├── entry/ │ └── oh-package.json5 ├── app.json ├── index.js └── package.json

然后需要把 React Native 的 bundle 配置指向 harmony 工程。这个过程中最容易忽略的是包名的统一，Application ID 不一致会导致设备安装时签名校验失败。我当时在 app.json 里写好包名后，又在 harmony 的 module.json5 里同步改了一遍，才避免了这个低级问题。

2.3 跑通 Hello World 遇到的第一个拦路虎

搭建环境这种工作，顺利的话半小时就能跑通，不顺的话能卡一整天。我这次卡在了一个非常隐蔽的地方：ArkUI 的容器组件加载 RN 根组件时，页面一直白屏。

当时把 JS 侧代码检查了无数遍，console.log 明明在打印，说明 JS 已经执行了，但屏幕上什么都看不到。后来打开 DevEco Studio 的日志面板，才发现是原生侧的组件名称映射出了问题。原因是我在 harmony/entry 里配置的组件名，和 RN 侧 app.json 里的注册名对不上。RN 侧的根组件通过 AppRegistry.registerComponent 注册，原生侧则需要用完全一样的字符串去加载它。我因为重构目录时改过一次 app.json，导致两侧的注册名不一致，白屏了将近两个小时。

这个经验让我后面养成了一个习惯：凡是涉及双端桥接的地方，先保证配置文件里的命名完全一致，再去排查逻辑问题。

3. 随机推荐页面的数据流与核心逻辑

3.1 需求拆解：不只是一个“换一个”按钮

产品最初给我的需求非常简单：“首页加一个随机推荐模块，点一下换个番剧。”但真正把需求落到随机推荐页面的时候，你会发现有很多边界情况需要定义清楚：用户点击“换一批”时，已经看过的不应该原样出现在下一批里；同一个会话里连续随机多次，不能出现反复推荐同一部番的情况；推荐内容加载失败时，要保留上一次展示的卡片，而不是直接白屏；以及用户对某部番点了“不喜欢”之后，后续随机结果里要避开它。

这些需求单独看都很小，但它们直接影响随机算法的设计和状态管理的结构。如果只是写个 Math.random() 然后从数组里取一个，初期没问题，用户量上来之后，各种“怎么又推荐这个”的反馈会让你改到怀疑人生。

3.2 推荐算法与服务端接口设计

我先和后端同事确定了数据接口的设计。服务端只做一件事：根据用户的浏览历史、收藏偏好和简单的热度加权，返回一批候选番剧列表。这个列表不需要是绝对随机的，反而应该是“在用户可能感兴趣的范围里做随机”，这样体验远好于全库随机。

客户端拿到候选列表之后，再本地做一次洗牌，决定展示顺序。为什么不直接把最终结果交给服务端？因为客户端的交互状态变化非常快，比如这一批已经展示了哪些、用户划掉了哪些，每次都请求服务端既增加延迟，又浪费流量。本地洗牌加缓存能带来更快的响应，离线时也能继续展示上一次的候选列表。

洗牌算法我选了经典的 Fisher-Yates，保证每个元素出现在任意位置的概率是均等的：

function shuffle(list) { const arr = [...list]; for (let i = arr.length - 1; i > 0; i--) { const j = Math.floor(Math.random() * (i + 1)); [arr[i], arr[j]] = [arr[j], arr[i]]; } return arr; }

这里要注意，Math.random() 的随机性已经够用，没有必要为了“更随机”去引入复杂的加密级随机数，反而会增加无谓的开销。

3.3 状态管理：从 useState 到 useReducer

随机推荐页面的状态其实比看起来多：当前展示的卡片队列、已看过的番剧 ID 集合、用户划走的卡片索引、加载状态和错误状态。如果散落着写四五个 useState，很快就会出现状态同步问题。

我最后用 useReducer 把核心状态收敛成一个 reducer，看起来更啰嗦，但每个状态转移都有明确的 action 描述，排查问题时非常清楚：

const initialState = { candidates: [], // 候选列表 queue: [], // 洗牌后的展示队列 seenIds: new Set(), // 本会话已展示的 ID history: [], // 展示过的完整记录，用于埋点 loading: false, error: null, }; function reducer(state, action) { switch (action.type) { case 'FETCH_SUCCESS': return { ...state, candidates: action.payload, queue: [], loading: false, }; case 'NEXT_BATCH': { const fresh = state.candidates.filter( (item) => !state.seenIds.has(item.id) ); const pool = fresh.length ? fresh : action.payload.pool; const shuffled = shuffle(pool); const batch = shuffled.slice(0, action.payload.size); return { ...state, queue: batch, seenIds: new Set([...state.seenIds, ...batch.map((i) => i.id)]), }; } case 'SET_ERROR': return { ...state, error: action.payload }; default: return state; } }

这个结构的核心思路是：把“候选池”和“展示队列”分开管理。候选池是数据源，展示队列只负责当前屏幕上的几张卡片。每次点击换一批，都是先基于 seenIds 过滤，再做一次洗牌，这样连续推荐重复的概率已经很低了。

4. 卡片式推荐页面的 UI 实现细节

4.1 堆叠卡片布局的实现

随机推荐页面我选择了卡片堆叠式交互，就是类似音乐软件里“每日推荐卡片”滑动的效果：当前卡片在最上层，下面隐约能看到下一张，滑动卡片后，下一张自然浮上来。

在 React Native 里做堆叠卡片，最直接的方式是用绝对定位把卡片叠在一起：

<View style={styles.stack}> {queue.map((item, index) => { const isTop = index === queue.length - 1; return ( <Animated.View key={item.id} style={[ styles.card, { position: 'absolute', top: index * 8, left: index * 8, transform: [ { scale: isTop ? 1 : 0.94 - (queue.length - 1 - index) * 0.02, }, ], }, ]} > <AnimeCard data={item} /> </Animated.View> ); })} </View>

这里有几个细节值得说。第一，绝对定位的层级关系取决于数组顺序，越排在后面的数组元素越靠近屏幕上层，所以顶层的卡片应该放在队列末尾。第二，层级卡片的位移和缩放要跟着索引动态计算，否则堆叠效果会显得僵硬。第三，这样的布局在 OpenHarmony 的 ArkUI 上是通过 Stack 容器实现的，RNOH 的适配层对 Stack 的 z-index 处理还算稳定，但测试下来，层数超过 3 层时重叠带来的视觉噪音就开始变大了，所以展示队列保持 2 到 3 张卡片是最舒服的。

4.2 手势滑动与回弹动画

卡片滑动是这个页面的灵魂。我用 PanResponder 加 Animated 实现了一套基本的拖拽逻辑：

const pan = useRef(new Animated.ValueXY()).current; const panResponder = useRef( PanResponder.create({ onMoveShouldSetPanResponder: (_, gesture) => Math.abs(gesture.dx) > 6, onPanResponderMove: (_, gesture) => { pan.setValue({ x: gesture.dx, y: gesture.dy }); }, onPanResponderRelease: (_, gesture) => { if (Math.abs(gesture.dx) > 120) { // 滑出屏幕 Animated.timing(pan, { toValue: { x: gesture.dx > 0 ? SCREEN_WIDTH + 60 : -SCREEN_WIDTH - 60, y: gesture.dy, }, duration: 220, useNativeDriver: true, }).start(() => { dispatch({ type: 'POP_CARD' }); pan.setValue({ x: 0, y: 0 }); }); } else { // 回到原位 Animated.spring(pan, { toValue: { x: 0, y: 0 }, useNativeDriver: true, }).start(); } }, }) ).current;

上面这段代码在普通 React Native 上是标准写法，但在 OpenHarmony 上我遇到一个情况：useNativeDriver 在 RNOH 的适配层里支持并不像双端那么完整，某些动画属性如果开了 nativeDriver，反而会不生效。排查了半天，最后定位到是 RNOH 的动画驱动实现问题。

注意：在 OpenHarmony 上遇到“动画值变了但画面没动”的情况，优先检查 useNativeDriver 的配置。

我的解决方案是对页面里所有使用 Animated 的地方做了一层封装，按动画属性选择是否开启 nativeDriver：位移类的用 nativeDriver 没问题，但涉及颜色、阴影这类属性的必须关掉 nativeDriver，交给 JS 驱动。

4.3 图片加载：占位、缓存与裁剪

推荐卡片的核心是封面图。动漫番剧封面通常比例固定，但来源渠道很多，有些是运营手工上传的，有些是从第三方站点同步的，尺寸不统一。我的方案是：服务端在上传时就把封面图裁剪成统一比例，比如 2:3 的竖版封面，同时提供多档分辨率的地址，客户端按屏幕尺寸选择对应档位。这样从源头规避了图片裁剪的问题，不需要在客户端引入图片裁剪库。

但用户在社区里上传头像、上传同人图时，还是绕不开裁剪需求。我调研过 react-native-image-crop-picker 的 OpenHarmony 适配情况，结论是官方还没有完整支持，社区里有单独的 ohos 版本，但 API 行为略有差异。我们的做法是封装一个 cropper 模块，底层在 OpenHarmony 上用系统的图片处理能力实现，对外暴露和原库一致的接口，这样业务代码不需要感知平台差异。

4.4 空状态与异常兜底

随机推荐页面看着花哨，但异常处理不够，用户感受会非常差。我做了三层的兜底。

第一层是网络请求失败。此时如果本地缓存里还有候选数据，就继续用缓存数据展示，只在顶部提示“当前内容可能不是最新”。第二层是候选列表为空。比如用户把所有番剧都划掉了，或者不喜欢的标记太多，就会让服务端返回一个全量热门的兜底列表，并且页面上展示一个明确的空状态文案。第三层是单张图片加载失败。封面图挂在卡片上的占比非常大，如果某一张图挂了，我会用一张内置的渐变占位图顶上，同时把图片地址上报到监控平台。

这三层的代码都不复杂，但缺一层，项目在真实网络环境下的反馈就会有明显差距。

5. 适配 OpenHarmony 时不能绕过的兼容性检查

5.1 我的兼容性检查清单

RNOH 的适配程度不是你装上一个包就能知道的，必须用真实功能逐一验证。我整理了一份检查清单，凡是涉及以下能力的地方，都建议在真机上测一遍。

这份清单的价值在于：它把“RN 代码在双端没问题”的假设打破了，让你提前知道哪些地方需要预留适配时间。

5.2 新架构带来的变化：从 Bridge 到 Fabric

聊 OpenHarmony 上跑 RN，绕不开新老架构的话题。老架构里 JS 和原生通过异步 Bridge 通信，每次调用都有序列化和线程切换的开销，动画性能到后期会明显受限。新架构以 Fabric 渲染器加 TurboModules 为核心，通信走 JSI 的同步调用，渲染任务可以直接调度到 UI 线程，性能上限高得多。

但新架构在 OpenHarmony 上的适配进度比双端慢。我测试时发现，RNOH 的新架构分支已经能跑起 Demo，但在复杂页面上，部分第三方库仍然依赖老架构的 NativeModule 注册方式，直接切换会导致一堆库失效。所以我的建议是分两步走：当前版本继续用老架构保证稳定上线，同时把项目中依赖原生能力的模块做一层抽象，等新架构成熟后再替换底层实现，业务代码不需要动。

5.3 我实际测试的结论

我在不同配置的设备上做了对比测试：老架构在低端设备上卡片滑动动画偶尔掉帧，但整体可接受；新架构在小体积页面上的表现明显更流畅，交互响应也更快，但第三方库的兼容性风险不允许我用在正式版本里。最后上线版本用的是老架构，再加一个计划：把核心推荐流程里的手势动画迁移到新架构分支做灰度验证。

如果你的项目不是迫不得已，不要为了新架构的新鲜感去冒险，稳定优先。

6. 上线前我踩过的坑和修复记录

6.1 图片缓存导致的内存峰值

上线前的测试中，我发现连续滑动 30 张卡片之后，应用内存涨得非常快。RN 的 Image 组件本身在双端会依赖各自的图片缓存策略，但在 OpenHarmony 上，RNOH 对图片解码后的 Bitmap 回收处理不如双端成熟。我的应急方案是两个：第一，把封面图静态资源改为带尺寸的 CDN 图并限制最大分辨率，减少单张图片的解码内存；第二，在滑动过程中对已经离开屏幕超过 5 张的卡片做卸载处理，而不是继续保留在视图树上。这个优化做下来，内存峰值下降非常明显。

6.2 随机算法导致的“连续推荐相同”

上线后有不少用户反馈“换了一批结果里又有刚才那部番”。我当时觉得很奇怪，因为 seenIds 过滤逻辑确实生效了。后来排查发现，问题出在服务端返回的候选列表：同一部番剧因为有多季或剧场版，会有多个条目 ID，但封面图一模一样。用户视角看就是“同一部番又被推荐了”，而 seenIds 只记录了条目的唯一 ID，没有记录作品的主键。

修复方案是给接口加了一个作品级 ID 字段，seenIds 改为存作品级 ID 的集合，同时后端的候选项里也做了作品去重。这个问题非常典型，做内容推荐的同学一定要提前想清楚“去重到底去的是内容还是条目”。

6.3 低端设备上动画掉帧

最开始我把卡片旋转、位移、缩放全部交给一个 Animated.Value 驱动，在高端机上没有问题，但在低端设备上能明显感觉到卡顿。优化思路是把动画拆分：核心的位移动画用 nativeDriver 保持流畅，旋转和缩放改为静态预设的 style 计算，每次手势过程中只更新位移值，减少同时驱动的动画节点数量。此外，对 PanResponder 的 onMoveShouldSetPanResponder 增加阈值判断，避免手指只是轻微触摸就触发手势追踪。

6.4 打包体积与启动时间

AnimeHub 的 HAP 包体积在集成 RN 后涨了非常多，其中 JS bundle 和未压缩的原生库占据了大头。我们启用了 Hermes 引擎来预编译 JS，启动时间缩短很明显。不过要确认你用的 RNOH 版本是否默认支持 Hermes，我一开始以为默认开启，结果构建日志显示还在走 JSC，手动配置后才生效。如果对启动时间有硬要求，还可以把随机推荐页做成懒加载模块，进入首页时不加载，点击模块后再动态请求业务包。但这个方案会牺牲功能加载速度换取首屏速度，需要根据产品的实际场景权衡。

这几个坑修完之后，随机推荐页面才真正达到了可以对外发布的状态。如果要我说这次实战最深的感受，那就是页面越小，越容易被低估：你以为一个随机推荐就是随机抽一个，实际做下来，随机策略、状态管理、手势动画、图片内存、平台适配每一项都能写出几百行代码和一堆测试用例。

代码里其实还留着几个可以继续扩展的口子：比如给每张卡片加上推荐理由，在滑动结束后把用户行为反馈到服务端，让随机结果越来越贴近个人兴趣；再比如像处理图片裁剪模块一样，把调用系统电话功能的原生能力封装成统一的 JS 接口，未来用在番剧详情的“联系组织”入口上。回头等这些功能都落地了，我再来分享下一轮踩坑记录。