企业官网建设流程全解析

把 React Native 搬到鸿蒙上跑，已经从“能不能跑”升级成了“跑得顺不顺”。我最近在做一款资讯类 App 的首页信息流，核心交互就是无限滚动列表，正好把 React Native 鸿蒙跨平台开发这条链路完整走了一遍。从环境搭建、模拟器调试，到 FlatList 的 onEndReached 陷阱、ScrollView 手写方案，再到 NAPI 原生模块对接，整个过程踩了不少坑，也沉淀了一套可以直接抄作业的代码指南。

这篇文章不打算讲大道理，就按我实际动手的顺序来：先聊清楚当前 React Native 上鸿蒙的技术路线，再把无限滚动效果从选型、实现到调优逐层拆开。无论你只是想快速实现一个“滑到底加载更多”的列表，还是打算把已有 RN 工程迁移到鸿蒙设备上，这篇都能给你一个可落地的参考。

1. 先摸清现状：React Native 鸿蒙生态到底走到哪一步了

1.1 从“能不能跑”到“跑得顺不顺”

很多同学对这个组合的第一反应是：React Native 不是安卓/iOS 的跨端方案吗，跟鸿蒙有什么关系？其实鸿蒙生态早就把 React Native 纳入了一等公民的适配范围。OpenHarmony 社区维护着 react-native-harmony 分支，核心思路是把 RN 的 JS 侧逻辑跑在鸿蒙的 JSVM 上，UI 层则通过鸿蒙的 ArkUI 原生组件来承载。换句话说，你写的 React 组件逻辑、状态管理、业务代码几乎不用动，真正要适配的是底层渲染和原生模块调用。

我这次项目的真实体验是：社区版 RN 在鸿蒙上已经能跑通大多数业务场景，信息流、弹窗、表单、网络请求都没问题。但和安卓/iOS 相比，有几个地方务必提前知道。第一是第三方原生库没法直接复用，凡是依赖 react-native link 或者原生 SDK 的库，都要找鸿蒙替代品或者自己封装 NAPI。第二是模拟器只支持 arm64 平台，x86 的 Windows 电脑跑模拟器基本无解，最稳的方式是真机调试。第三是性能调优要更主动，RN 在鸿蒙上的 JS 与原生通信路径跟安卓不完全一致，列表类的场景必须显式做渲染优化。

这些不是劝退，而是让你心里有数。掌握了 RN 在鸿蒙上的边界，再实现无限滚动这种高频交互，就能少走弯路。

1.2 现在做鸿蒙 RN 开发，主流是哪几条路线

目前实际可用的路线基本有三条。

第一条是直接用社区维护的 React Native 鸿蒙分支，基于 OpenHarmony 的脚手架自行搭建工程。优点是可控性最强，能和官方 RN 主版本保持同步；缺点是你需要手动处理鸿蒙工程和 RN 工程的构建关系，入门成本略高。

第二条是用 Taro 这类跨端框架，它们已经支持将产物输出到鸿蒙。如果你原本就是 Taro 的重度用户，这条路线最顺。但要注意，Taro 跑鸿蒙本质上也是把 React/Vue 语法映射到鸿蒙原生组件，和直接写 RN 的运行时还是有差异，部分 React Native 专属 API 会受限。

第三条是主工程继续用原生 ArkTS，某个复杂页面或模块内嵌 React Native 容器。这种混合形态在存量鸿蒙 App 里最常见，适合新功能试水。我这次的项目就是这种形态，原生壳子负责导航和基础能力，信息流页面整体由 RN 承载。

选路线时建议先看团队底子。如果你团队本来就是 RN 技术栈，第一条最合理，能最大化复用现有代码；如果是从零开始且未来主要面向鸿蒙，可以考虑混合形态。无限滚动这个功能在三条路线上实现原理一致，但适配细节会略有差异，后面我会重点讲通用方案，再补充鸿蒙特有的坑。

2. 工程与环境准备：模拟器、真机、Metro 一条线跑通

2.1 脚手架搭建与目录结构要点

我基于 react-native-harmony 的模板工程来初始化。创建完 RN 工程后，鸿蒙侧会生成一个独立的 HarmonyOS 工程目录，二者通过构建脚本关联。这里最关键的一点：RN 侧的 node_modules、Metro 配置、bundle 产物的路径，必须在鸿蒙工程里配置正确，否则运行时直接报找不到 bundle。

初始化完成后先装 pod 依赖，然后启动 Metro，最后在鸿蒙工程里配置 bundle 入口。如果你是首次玩鸿蒙，建议先跑通模板自带的示例页面，确认能出 UI 再动业务代码。否则一旦混入自定义原生模块，排查问题的维度会指数级增加。我见过不少同事一上来就改原生代码，结果连模板页都白屏，最后查半天发现是 Metro 端口没开。

工程目录建议这样组织：js/ 放 RN 业务代码，harmony/ 放鸿蒙壳子工程，native-modules/ 放自定义 NAPI 模块源码。JS 和原生代码严格分离，后面做无限滚动列表时，涉及原生能力扩展（比如数据库缓存）就能立刻定位到文件。

2.2 模拟器只能跑 arm64，真机调试才是关键

热词里反复出现“鸿蒙模拟器目前只能在 arm64 平台运行”，这不是空穴来风。受限于 JSVM 的原生库编译架构，鸿蒙模拟器目前只支持 arm64 指令集。你的 Windows x86 电脑上跑模拟器，大概率会看到“运行设备不兼容”之类的提示。就算用 mac 的 M 系列芯片跑通了模拟器，也没有真机上那些传感器、深度相机、多窗口交互，列表性能数据参考意义有限。

所以我的建议很直接：鸿蒙 RN 开发，直接上真机。用 DevEco Studio 连接设备后，通过 hdc 命令管理应用安装和日志。hdc 的用法和安卓的 adb 很像，常用的就是 hdc list targets、hdc file send、hdc shell hilog。调试无限滚动时，我习惯用 hdc shell hilog 实时过滤 JS 侧的 console 日志，再结合 Metro 的终端输出定位问题。

2.3 Metro 与热更新链路调试技巧

RN 开发离不开 Metro，鸿蒙侧同样支持从 Metro 加载 bundle，这样你改 JS 代码后能秒级看到效果。启动 Metro 后，在鸿蒙工程里把 bundle 加载模式切换成开发模式，App 启动时会主动从本地端口拉取 JS bundle。

这里有个非常容易踩的坑：鸿蒙 App 默认有网络权限限制，如果设备没授权访问开发机端口，Metro 连接会一直失败，表现就是启动白屏加一行“Unable to load script”。排查思路是先用 hdc 确认 App 进程的网络权限，再确认设备能 ping 通开发机 IP。我在真机上遇到过 WiFi 隔了 VLAN 导致端口不通的情况，最后通过 hdc 端口转发解决。这个如果不提前处理，后续所有功能都没法开发。

3. 无限滚动主方案：用 FlatList 实现“滑到底自动加载”

3.1 为什么首选 FlatList 而不是 ScrollView

实现无限滚动，第一反应可能是用一个 ScrollView 包住所有数据，然后监听滚动位置判断是否到底。数据量小（比如几十条）这样够用，但一旦数据量上千，ScrollView 会把所有子组件一次性渲染出来，内存和渲染压力直接拉满，鸿蒙设备上会明显掉帧。

FlatList 的核心特性是“虚拟列表”，它只渲染当前窗口附近的数据项，滑出一定距离的项目会被回收。无限滚动本身就是为了让用户持续浏览大量数据，所以主方案优先选 FlatList。而且 FlatList 自带 onEndReached 回调，做分页加载几乎是开箱即用。

在鸿蒙的 RN 适配层中，FlatList 对应的底层实现会映射到 ArkUI 的滚动容器组件。这个映射有一个需要注意的点：由于底层是原生滚动容器，存在 JS 侧事件回传的一定延迟。所以在 onEndReached 里不能做太重的同步计算，否则会出现“滚动到列表底部后卡了半秒才加载新数据”的体感问题。

3.2 分页状态机：page、loading、hasMore 缺一不可

无限滚动最核心的不是 UI 层，而是状态管理。我把它拆成三个状态：当前页码 page、加载状态 loading、是否还有更多数据 hasMore。这三个状态必须配合严密，否则会出现重复请求或者“永远加载不完”的死循环。

第一次进入页面时，page 初始化为 1，loading 为 false，hasMore 为 true。FlatList 首次渲染后，若数据不满一屏，onEndReached 会立即触发，此时正常加载第二页。如果第一页返回的数据已经不足一页，可以把 hasMore 置为 false，避免无意义的请求。

加载更多时，先判断 loading 和 hasMore，若正在加载或没有更多数据则直接 return。请求成功后，把新数据追加到列表尾部，page 自增，hasMore 根据本次返回条数更新。这个状态机我贴一段可以直接用的代码：

const [list, setList] = useState<ItemType[]>([]); const [page, setPage] = useState(1); const [loading, setLoading] = useState(false); const [hasMore, setHasMore] = useState(true); const loadMore = useCallback(async () => { if (loading || !hasMore) return; setLoading(true); try { const res = await fetchList({ page: page + 1, pageSize: 20 }); setList(prev => [...prev, ...res.list]); setHasMore(res.list.length > 0); setPage(prev => prev + 1); } catch (e) { // 错误统一交给错误提示，这里建议保留 hasMore 不变，让用户可重试 } finally { setLoading(false); } }, [page, loading, hasMore]); <FlatList data={list} renderItem={renderItem} keyExtractor={item => String(item.id)} onEndReached={loadMore} onEndReachedThreshold={0.3} ListFooterComponent={() => loading ? <LoadingIndicator /> : hasMore ? null : <NoMoreFooter /> } />

注意 onEndReachedThreshold 的取值。它表示距离底部多远时触发回调，0.3 代表列表总长度的 30%。这个值不能太小，否则在快速滑动时可能来不及触发；也不能太大，否则用户还没到底就开始加载。我实测在鸿蒙设备上取 0.3 到 0.5 比较舒服，网络慢的场景建议改成 0.5，给加载预留时间。

3.3 鸿蒙上 onEndReached 的奇怪触发时机

安卓和 iOS 上 onEndReached 的触发时机相对稳定，但鸿蒙上我发现一个现象：列表初次渲染时，如果页面布局尚未完全稳定，onEndReached 可能会被提前触发一次，直接拉取了第二页。这在不经意间会导致首屏请求了两页数据，请求量翻倍。

排查办法是在 loadMore 里加一个可重入保护，用 ref 记录首次渲染完成标志。首次渲染完成且页面没有发生滚动时，不触发加载。另一种做法是延迟初始化 FlatList 的 data，等首屏布局完成后再从空数组切换为第一页数据。我比较推荐前者，代码侵入更小。

另外，如果 ListFooterComponent 返回了空视图，也可能影响 onEndReached 的计算。建议在 footer 中给一个明确高度，或者干脆用 null 控制占位，不要让 footer 的渲染影响滚动容器的 contentSize 计算。这个坑在鸿蒙的 ArkUI 容器上更容易出现，因为 footer 的高度计算链路和 RN 主分支略有差异。

4. 如果 FlatList 不满足需求：ScrollView 手写无限滚动

4.1 onScroll 阈值判断与节流

有些场景不能直接用 FlatList，比如需要自由排列的宫格瀑布流，或者列表项高度差异极大且需要动态测量的场景。这时候手写 ScrollView 监听方案反而是更稳的选择。

核心思路是监听 onScroll 事件，取出 contentOffset.y、layoutMeasurement.height、contentSize.height 三个值。当 contentOffset.y 加上可视高度已经接近内容总高度时，说明用户滑到底部，触发加载更多。我写了一个通用判断：

const handleScroll = ({ nativeEvent }: NativeSyntheticEvent<NativeScrollEvent>) => { const { layoutMeasurement, contentOffset, contentSize } = nativeEvent; const distanceFromBottom = contentSize.height - (contentOffset.y + layoutMeasurement.height); if (distanceFromBottom < 200) { loadMore(); } }; <ScrollView onScroll={handleScroll} scrollEventThrottle={16} > {children} </ScrollView>

scrollEventThrottle 很关键，它控制滚动事件的触发频率。设为 16 表示大约每 16 毫秒触发一次，接近 60FPS。如果不设，默认可能会以更高频率触发，导致 JS 侧频繁计算，滚动卡顿；设得太低（比如 100）又会导致滚动快时漏判。鸿蒙的 ArkUI 滚动事件回传链路比安卓稍长，我建议保持 16。

4.2 用 requestAnimationFrame 做防抖，避免重复触发

onScroll 是高频事件，用户在底部区域来回滑动时，handleScroll 可能被连续触发十几次。如果每一次都去请求接口，就会产生大量重复请求。最简单的方式是加一个时间窗口，或者用一个 ref 记录“是否已经在加载中”，跟 FlatList 方案的 loading 判断同理。

我习惯再叠加一层 requestAnimationFrame 节流。具体做法是：在 handleScroll 里用 rAF 标记一个待执行任务，如果上一次 rAF 还没有执行就不重复安排。这样即使 onScroll 触发频率再高，实际业务判断也只会每帧执行一次，既可靠又省电。代码如下：

const rafRef = useRef<number | null>(null); const handleScroll = (e) => { if (rafRef.current != null) return; rafRef.current = requestAnimationFrame(() => { rafRef.current = null; const { layoutMeasurement, contentOffset, contentSize } = e.nativeEvent; if (contentSize.height - (contentOffset.y + layoutMeasurement.height) < 200) { loadMore(); } }); };

这里要注意，rAF 的回调里拿到的 nativeEvent 是 e 上的引用，不要直接在外部重新取事件对象，否则某些 RN 版本会报“Attempted to access nativeEvent after it was released”之类的错误。

4.3 滚动加载的 UI 反馈与占位管理

手动管理 ScrollView 时，所有反馈元素都得自己拼。我的做法是在 children 尾部追加一个加载状态组件：loading 时显示转圈，没有更多数据时显示“已经到底了”。这个组件不要用绝对定位，直接放在内容流后面，否则会影响 contentSize 的判断。

很多新手会犯一个错误：在加载更多时把 loading 状态塞进现有列表的某个位置，导致内容跳动。正确做法是让 loading 组件固定占位高度，例如 60 像素左右。加载完成后，数据追加到尾部，loading 组件消失，页面滚动位置不会发生明显的视觉跳变。这个细节非常影响体验，尤其是用户正好停在底部时，如果页面突然被压缩，视觉跳动会非常明显。

5. 鸿蒙原生模块边界：从 JS 到 NAPI，你迟早会碰到

5.1 纯 JS 实现无限滚动够不够用

大部分信息流场景，纯 JS 的 FlatList 方案已经够用。但无限滚动做到后面，一定会遇到性能和数据持久化问题。比如用户飞速滑动时，从网络拉取新数据的速度跟不上，列表出现短暂的空白区；或者 App 被杀后，用户希望恢复上次浏览的位置和数据。

这些问题光靠 JS 层很难优雅解决。网络请求可以在 JS 层加缓存，但磁盘缓存、数据库存储、甚至本地文件缓存这些能力，都需要通过鸿蒙的原生接口来实现。RN 在鸿蒙上要调用原生能力，一般通过 NAPI 完成。NAPI（Native API）是鸿蒙提供的 C/C++ 接口层，你可以用它在 JS 和原生代码之间搭一座桥。

5.2 har 封装 so 库：一次封装，处处调用

在鸿蒙工程里，如果你需要把一段 C/C++ 代码暴露给 RN 的 JS 侧调用，通常流程是：用 DevEco Studio 创建 har 模块，内部封装 NAPI 接口，然后编译产物是 .so 文件。RN 侧只需要在工程配置里声明这个 har 依赖，就能通过一个全局对象调用原生方法。

我做无限滚动时用原生模块做了一个轻量级的本地分页缓存：把已加载的页面数据按页序列化后写入本地文件，下次启动时先读缓存再请求网络。这个缓存逻辑如果用 JS 层实现，读写文件会受限于 Node.js 核心模块的裁剪，很多模块在 RN 鸿蒙环境下并不可用。通过 NAPI 暴露一个简单的 readCache(page) 和 writeCache(page, data) 接口，JS 侧调用干净利落。

5.3 NAPI 调用时的数据序列化与线程安全

NAPI 调用不是免费的，每次跨语言调用都有序列化开销。无限滚动场景里，如果每条数据都单独调一次原生方法，性能会非常难看。我的做法是批量传递：把一页的数据组装成一个大数组，一次传给原生侧，原生侧统一写入。反过来读取缓存时，也是一次性返回整页数据。

另外要注意线程问题。NAPI 接口默认运行在调用线程，但如果你的原生实现里启动了子线程做 IO，必须在子线程里通过 napi_create_async_work 把结果回传到 JS 线程。这个坑我踩过，表现为偶尔数据不刷新，用 hilog 看日志才发现原生侧报线程相关错误。解决办法是给 NAPI 模块加一个 async work 的模板，所有耗时操作都走异步队列，确保 JS 侧拿到结果时一定在主线程。

6. 常见问题与排查实录：从白屏到卡顿，逐个击破

6.1 React Native 启动白屏问题

热词里“react native 启动白屏”出现频率很高，确实也是鸿蒙 RN 开发遇到最多的现象。白屏的本质是 JS bundle 没有成功加载。排查路径一般分三层：第一层确认 Metro 是否开着，第二层确认鸿蒙工程能否访问 Metro 端口，第三层确认 bundle 加载入口配置是否正确。

如果你用的是真机，建议先用 hdc 看看设备的 IP 是否能 ping 通开发机，再用 hdc 转发端口绕过网络限制。白屏时 Metro 终端通常会有日志输出，看到 “Running application xxx” 就说明连接已经建立。如果连 Metro 的日志都没有，问题大概率在网络层，而不是 RN 本身。

6.2 列表滚动卡顿与掉帧

无限滚动列表最容易暴露性能问题。卡顿的常见原因有三个：列表项组件太复杂、每次渲染的数据量太大、影子树更新过于频繁。

列表项组件太复杂时，需要把图片懒加载、圆角裁剪、阴影效果能省则省。鸿蒙的 ArkUI 渲染阴影的代价比安卓高，能截图替代就不要用动态阴影。数据量方面，检查 FlatList 的 initialNumToRender 和 maxToRenderPerBatch 参数，首屏渲染项数建议控制在 10 到 15 个，后续批量渲染控制在 10 个以内，避免一次性渲染过多导致掉帧。

6.3 重复请求与 loading 闪烁

重复请求的根源是 loadMore 没有做好防重入。除了用 loading 状态判断，还建议用 ref 记录“是否正在请求”，避免状态更新异步导致的老值判断。loading 闪烁通常是因为加载完成太快，footer 的 loading 组件一闪而过。体验优化方案是在 onEndReached 触发后强制让 loading 组件至少显示 300 毫秒，避免视觉闪烁，也降低用户感知焦虑。

6.4 内存持续上涨

无限滚动最怕内存爆炸。FlatList 虽然虚拟化后只渲染可见项，但如果你在 renderItem 里创建了过多的闭包、图片没走缓存、或者列表项 key 不稳定，都会导致内存只增不减。建议用 keyExtractor 返回 id 字符串，图片组件显式使用 resizeMethod 和 cache 属性。在鸿蒙原生侧，注意图片解码的内存占用，大图要先压缩再展示。

另外一个容易忽略的点是：onEndReached 触发的接口返回数据里，不要把所有字段都塞进 state。只保留渲染需要的字段，比如 id、title、cover、summary，其他元数据直接丢弃。这样能显著减少 JS 对象占用的堆内存，以及原生侧序列化的开销。

6.5 快速问题排查速查表

在无限滚动这个功能上，React Native 结合鸿蒙开发已经不是一个玩具级的组合，而是可以认真落地的方案。只要把环境链路、虚拟列表、状态机、原生模块边界这几个环节吃透，你完全可以在鸿蒙设备上做出一款信息流体验顺滑的跨平台应用。最后再分享一个小技巧：调试无限滚动时，强烈建议在开发模式下打开鸿蒙自带的性能分析工具，实时查看滚动帧率和内存曲线。很多卡顿问题不是在代码 review 时发现的，而是在性能录制过程中一眼看出来的。