React Native鸿蒙适配实践：横向List组件跨平台实现与性能优化

1. 项目背景与核心需求拆解

1.1 为什么会有这个项目

先交代一下背景。今年团队接了一个电商类的跨平台需求，产品侧要求在首页做一档“流行时尚商品”的横向滚动专区，风格参考主流电商App的“猜你喜欢”“潮流好物”这类模块——一张商品卡片横向排开，手指左右滑动切换，卡片上展示主图、价格、标签、加购入口等等。这个需求本身并不复杂，真正的难点在于我们同时要交付鸿蒙版本和安卓/iOS版本，而且业务方明确要求三端交互逻辑一致，不允许出现“鸿蒙版滑动手感跟安卓不一样”“iOS上惯性特别顺、鸿蒙上像在拖一个笨重的木箱”这种割裂体验。

这就引出了项目的核心技术选型问题：用什么方案做，才能既保证跨平台复用、又让鸿蒙端有自己的原生活力？我们最终选定的是React Native的鸿蒙适配方案，用同一套List组件横向模式来承载业务逻辑，再针对鸿蒙的滑动交互做适配。这篇文章会把整个实现过程、踩过的坑、以及最终沉淀出来的方案完整讲一遍，给正在做鸿蒙跨平台改造的团队一个可参考的样本。

1.2 核心关键词拆解：List组件横向模式到底指什么

在React Native生态里，List组件家族主要包含FlatList、SectionList和VirtualizedList。我们这里说的“横向模式”，就是给这些列表组件设置horizontal属性，让列表的布局主轴从垂直方向切换到水平方向，配合snapToInterval、pagingEnabled、decelerationRate等属性，就能实现商品卡片一屏一屏翻动或者自由滑动的效果。

很多新手容易有一个误解：横向滚动不就是把ScrollView丢进去然后设个horizontal吗？实际项目里完全不是这么回事。时尚商品列表的数据量动辄几十上百条，ScrollView会把所有子视图一次性全部渲染出来，哪怕屏幕外看不见的商品也占着内存和布局开销，在低端鸿蒙设备上滑动起来必然掉帧。FlatList这类虚拟化列表组件则不同，它只会渲染当前视口附近的部分商品卡片，滑动过程中动态回收和复用节点，这在跨平台场景下是保证性能的关键。

另外要注意的是，“横向模式”并不仅仅是把滚动方向改一下那么简单，它还牵扯到内容容器宽度计算、卡片间距处理、首尾对齐（contentContainerStyle）、以及跟外层竖向滚动手势的冲突权衡。这些细节在后面第三节的核心实现里我会逐个展开。

1.3 一个横跨三端的List组件，逻辑一致性如何保证

这个项目名字里有“逻辑一致”四个字，这其实是整个跨平台方案里最有嚼头的部分。所谓逻辑一致，指的是业务逻辑层——数据请求、状态管理、卡片渲染结构、点击事件上报——全部由React Native这一套代码输出，在三端保持一致；而底层滚动容器、手势响应、列表复用机制则分别由各端原生组件提供，这样每一端都能发挥自己原生的滑动特性。

我们选的鸿蒙适配方案，是OpenHarmony社区孵化的React Native适配层。它的原理是在鸿蒙原生侧实现一套与React Native对应的原生组件映射，把JS侧的FlatList映射为鸿蒙原生列表组件Scroll或List，事件通信通过桥接层转发。这样JS侧业务代码几乎不需要为鸿蒙端单独写第二份，真正做到“一套代码、多端运行”。

不过，逻辑一致不等于代码完全一致，滑动交互的适配细节恰恰是各端差异最容易冒出来的地方。鸿蒙系统的边缘回弹效果、嵌套滚动优先级、触摸事件分发顺序，跟安卓/iOS都不同，这部分必须单独处理。我会在第四节专门讲适配方案。

2. 环境准备与工程搭建

2.1 鸿蒙环境下RN开发环境的关键版本组合

如果你之前只在安卓/iOS上跑过React Native，第一次接触鸿蒙适配时会有点懵，因为需要的工具链多了一套。我这里直接给出经过验证的版本搭配，避免你在各种依赖冲突里绕圈子。

基础环境方面，需要准备DevEco Studio作为鸿蒙应用的原生开发IDE，同时保留Node.js和React Native对应的命令行工具。鸿蒙适配层选择的是@react-native-oh/react-native-harmony这个包，它的版本跟React Native版本是严格对应的，我们使用的是RN 0.72.x版本，对应的react-native-harmony包是0.72.x系列。这里有个关键点：React Native的版本小版本号也需要匹配，比如0.72.0和0.72.5对应适配包的编译版本就有差异，保险起见让两个版本号完全一致。

工程接入方式有两种：一种是从零创建一个全新的HarmonyOS工程，然后通过ohpm安装react-native-harmony桥接库；另一种是把现有的RN工程反向集成进鸿蒙工程里。我们项目的情况是已经有一套成熟的RN跨平台业务代码，所以走的是反向集成路线。鸿蒙工程负责提供原生运行容器，RN的JSBundle作为资源打进HAP包里，启动时加载。

这里分享一个环境搭建时容易踩的坑：DevEco Studio的SDK版本和react-native-harmony要求的最低API版本要提前核对。如果用低版本的API编译，会出现原生模块符号找不到的错误；用太高的版本又会遇到API废弃警告，虽然不影响编译，但会有运行时兼容隐患。我们最后锁定在API 9到API 11之间，兼容以前的老设备。

2.2 工程结构：RN业务层与鸿蒙容器层怎么分工

工程目录的规划直接影响后续开发和排障效率。我们的项目采用了双工程并行的结构，看起来像这样：

bash复制android-app/          # 安卓原生壳工程
ios-app/              # iOS原生壳工程
harmony-app/          # 鸿蒙原生壳工程
react-native-core/    # 共用的RN业务代码工程
  ├── src/
  │   ├── pages/
  │   ├── components/
  │   └── api/
  ├── index.js
  └── package.json

RN业务代码是独立的工程，负责所有页面和组件开发。三个原生壳工程只做一件事：把RN的Bundle加载起来，并提供原生桥接模块。鸿蒙壳工程里需要额外做的事情比安卓/iOS多一些，因为鸿蒙的模块加载机制和路由方案都更年轻，需要手动配置的项更细节。

在鸿蒙侧核心需要配置两个东西：一个是MainAbility里的onCreate方法，负责初始化React Native运行时并加载放在rawfile目录下的JSBundle文件；另一个是Ability的页面加载容器，我们用的是ReactHost和ReactInstanceManager组合的方式，跟安卓的ReactActivity非常相似。习惯安卓RN开发的同学上手很快，但要注意鸿蒙那边对want参数的处理跟安卓的intent有差异，所以原生传参的序列化格式要单独写一份适配代码。

2.3 为什么优先选择List而不是ScrollView去横向展示商品

这一点我在1.2节里提了一句，但值得单独展开说。

自己开发过程中我对比过两种实现，在商品量少（少于10条）的时候，ScrollView横向模式写法简单，代码量少，渲染也没有明显问题。但业务方给的数据量设计上限是50条商品，这就让ScrollView的劣势暴露无遗：

一次性加载50个商品卡片，每个卡片包含商品主图、标题、价格组件、标签组件，加上图片的缓存和布局计算，在中等配置的鸿蒙设备上初始化耗时就要多出300ms左右，滑动时还会出现新卡片渲染的白屏闪烁。而FlatList通过视口推算和预加载机制，初始只渲染屏幕宽度能够容纳的卡片数（比如3到4个），然后随着滑动逐步渲染并复用节点，实测在同样数据量下首屏加载时间缩短到原来的三分之一左右。

此外，FlatList的API能让我们精确控制onViewableItemsChanged，这个回调在电商场景里非常有用——可以实现“当某张商品卡片从不可见变成可见时，自动触发曝光埋点”的需求。ScrollView要实现类似的曝光判断就得自己写滚动监听去算每个子视图的坐标，麻烦得多，还容易算错。

所以最终的选型非常明确：横向商品展示的基础容器使用React Native的FlatList组件，映射到鸿蒙端原生列表组件，这是兼顾性能和数据驱动能力的正确选择。

3. 横向List组件的核心实现

3.1 核心代码：一个符合电商场景的横向FlatList

直接看代码。下面是我们项目里横向商品列表组件的核心实现，去掉了业务包装，保留了必要的结构：

tsx复制import React, { useCallback, useMemo, useRef } from 'react';
import { FlatList, View, Text, Image, Dimensions, NativeSyntheticEvent, NativeScrollEvent } from 'react-native';
import type { ListRenderItemInfo } from 'react-native';

const { width: screenWidth } = Dimensions.get('window');
const CARD_WIDTH = 120;
const CARD_MARGIN = 8;
const PAGE_WIDTH = screenWidth - 32; // 两侧16px边距

interface ProductItem {
  id: string;
  title: string;
  price: string;
  imageUrl: string;
  productType: string;
}

// 判断卡片是否可见，用于曝光埋点
const viewabilityConfig = {
  viewAreaCoveragePercentThreshold: 60,
};

export const HorizontalProductList = ({ data }: { data: ProductItem[] }) => {
  const onViewableItemsChanged = useRef(({ viewableItems }) => {
    const visibleIds = viewableItems.map((item) => item.key);
    // 上报曝光埋点
    reportExposure(visibleIds);
  }).current;

  const renderItem = useCallback(({ item }: ListRenderItemInfo<ProductItem>) => {
    return (
      <View
        style={{
          width: CARD_WIDTH,
          marginRight: CARD_MARGIN,
          borderRadius: 12,
          overflow: 'hidden',
          backgroundColor: '#fff',
        }}
      >
        <Image source={{ uri: item.imageUrl }} style={{ width: CARD_WIDTH, height: 120 }} resizeMode="cover" />
        <View style={{ padding: 8 }}>
          <Text numberOfLines={1} style={{ fontSize: 14, fontWeight: '600', color: '#222' }}>
            {item.title}
          </Text>
          <View style={{ marginTop: 6, flexDirection: 'row', alignItems: 'center' }}>
            <Text style={{ fontSize: 16, fontWeight: '700', color: '#ff3b30' }}>{item.price}</Text>
            {item.productType === 'hot' && (
              <View style={{ marginLeft: 6, backgroundColor: '#ffeceb', borderRadius: 4, paddingHorizontal: 4 }}>
                <Text style={{ fontSize: 10, color: '#ff3b30' }}>热卖</Text>
              </View>
            )}
          </View>
        </View>
      </View>
    );
  }, []);

  return (
    <View>
      <FlatList
        horizontal
        data={data}
        keyExtractor={(item) => item.id}
        renderItem={renderItem}
        showsHorizontalScrollIndicator={false}
        contentContainerStyle={{ paddingHorizontal: 16, paddingVertical: 12 }}
        initialNumToRender={5}
        maxToRenderPerBatch={5}
        windowSize={7}
        viewabilityConfig={viewabilityConfig}
        onViewableItemsChanged={onViewableItemsChanged}
        getItemLayout={(_, index) => ({
          length: CARD_WIDTH + CARD_MARGIN,
          offset: (CARD_WIDTH + CARD_MARGIN) * index,
          index,
        })}
        removeClippedSubviews
      />
    </View>
  );
};

这段代码里有几个参数值得逐个说清楚，因为它们直接影响鸿蒙端的滑动效果和渲染性能。

horizontal是核心属性，它让FlatList的主轴从垂直变为水平。initialNumToRender对应首屏渲染的卡片数量，我们设定为5，刚好覆盖一屏能看到的卡片数加上一个预加载位。maxToRenderPerBatch控制每次渲染的增量，这里取5，避免滑动过快时CPU一下子要处理太多新节点的创建。windowSize是虚拟化窗口的高度倍数，7这个值的意思是可视区域外上下各渲染3个屏幕宽度的内容作为缓冲，这个值调小会省内存，但滑动快速时容易白屏，调大会更流畅但卡片的节点创建更频繁，7是性能和流畅度的平衡点。

getItemLayout我特别推荐在横向列表中配置。它用来告诉列表组件每一个卡片的高度、宽度和偏移位置，可以让列表跳过动态测量布局的步骤直接计算出滚动位置。商品卡片宽度和间距是固定的，正好满足它的使用条件。配置了它之后，列表的滚动定位精度更高，特别是后面要用scrollToIndex回到指定商品时，百分比命中率高很多。

3.2 数据驱动：商品列表的加载、刷新和状态同步

横向列表的UI是表面上能看到的部分，数据层同样需要仔细设计。电商场景下，这个模块的商品列表不是静态的——它需要从服务端拉取，可能还有下拉刷新、分页加载、断网重试这些逻辑。

数据层设计上我们采用了useReducer加自定义Hook的方式，把列表状态集中管理。核心状态包括：

tsx复制interface ProductListState {
  data: ProductItem[];
  page: number;
  hasMore: boolean;
  loading: 'idle' | 'loading' | 'error';
  refreshing: boolean;
}

页面加载时触发首屏请求，拉回第一页数据填入列表；滚动到接近末尾时触发下一页请求，把新数据追加到数组尾部。在鸿蒙端这套逻辑跟安卓/iOS完全一致，因为网络请求、状态管理都在JS层运行，不牵扯原生实现。

实际操作中我发现一个容易犯的错误：很多人在做追加分页时，直接修改原数组的引用，导致FlatList对比新旧数据后整体重渲染了一遍，横向滑动的当前偏移位置也会被重置，用户觉得“怎么滑着滑着自己弹回去了”。正确做法是无论如何要保持数据数组引用稳定，每次追加数据时都生成一个全新的数组，这样FlatList才能识别到只是增量变化，而不会重置滚动位置。这个细节我建议在做需求时反复强调，比调试半天划算得多。

3.3 性能调优：窗口化、节点复用与图片加载

横向列表的性能调优，核心是三件事：减少渲染节点数、避免无效重渲染、降低图片解码开销。

第一件事由FlatList的虚拟化机制解决。第二件事需要从组件设计上入手。我们给renderItem生成的卡片组件做了React.memo封装，让卡片只在本身的item数据变化时才重渲染。同时在父组件中把回调函数用useCallback包裹，避免父组件每次刷新时传递了全新的函数引用，导致所有卡片被迫重渲染。

第三件事最隐蔽也最关键。商品主图是横向列表里最耗资源的元素，我们在鸿蒙端实测发现，大尺寸、高分辨率的图片在快速滑动时会导致明显的掉帧。原因是每张新卡片出现时都要经历一次图片解码过程，如果解码速度跟不上滑动速度，就会看到卡片先空白再突然显示图片。

解决方案有两个层面：第一，服务端下发图片时设定合适的尺寸规格，商品卡片的显示宽度只有120dp，我们就要求图片接口返回的URL带上了?imageView2/2/w/240这样的缩放参数，让下载和解码的图片分辨率跟实际展示分辨率匹配，这一步就能减少大量解码开销；第二，在代码层面对Image组件设置合理的resizeMode，我们用的cover模式让图片按比例缩放并裁剪，避免浏览器原生缩放的计算开销。如果业务场景对图片质量要求更高，可以考虑引入react-native-fast-image这类三方库，鸿蒙适配层把它映射到原生图片加载库，能获得更好的缓存管理，但这会引入额外依赖，需要评估团队维护成本。

4. 鸿蒙滑动交互逻辑适配

4.1 鸿蒙与外端滑动交互的差异逐项对比

鸿蒙的列表滚动机制底层实现与安卓上基于RecyclerView的方案、iOS上基于UICollectionView的方案完全不一样。react-native-harmony适配层把JS侧的FlatList映射为鸿蒙原生侧的List组件，但它只负责基础的滚动能力，一些平台的交互细节需要我们自己适配。

最直观的差异点有三个：边缘效果、惯性滑动、嵌套滚动。

边缘效果方面，鸿蒙的List默认在滚动到边界时会有一个“拉伸-回弹”的效果，这个效果在安卓5.0以上和iOS上也有，但回弹的阻力曲线完全不同。鸿蒙的阻尼感比较“软”，拉伸距离更大，回弹速度更柔和。如果不做适配，同一套代码在安卓上滑到顶部就“咔”一下停住，在鸿蒙上却会软绵绵地弹一下，用户会觉得“这两个端手感怎么不一样”。

惯性滑动方面，鸿蒙默认的fling速度衰减系数与外端有差异。具体表现是：同样大力滑动一下，iOS上能滑很远还很顺滑，鸿蒙上可能滑到一半就停下来了。跟产品沟通后确认，这不是Bug，而是不同系统对“惯性”的调校哲学不同。我们不需要强行改到跟iOS一模一样的物理曲线，但需要确保这个手感符合鸿蒙用户的使用习惯，否则总感觉列表“发闷”。

嵌套滚动方面，鸿蒙对子列表嵌套在父ScrollView里的手势优先级有自己的分发规则。我们首页整体是一个竖向滚动的页面，横向商品列表只是其中的一个子模块，两个维度的滑动方向不同，理论上可以共存，但鸿蒙在某些情况下会错误地抢占手势，导致横向列表滑不动、或者竖向页面被横向手势顶退。这个完全需要手动处理。

4.2 触摸事件分发与横向滚动手势冲突处理

先说我们遇到的最典型的冲突问题：当手指放在横向商品列表上，先左右滑动，再快速改变方向上下滑动时，鸿蒙的List组件有时会把第一个横向滑动的手势吃掉，导致页面突然卡顿一下，然后才开始正常滑动。这个问题在安卓和iOS上都没有，属于鸿蒙手势系统的特有行为。

排查这个问题需要对鸿蒙的手势分发机制有一定了解。鸿蒙原生侧的手势识别系统有一个“手势优先”策略，当一个手势被识别为横向拖动后，系统会在一段时间内“锁定”这个方向的优先级，如果用户在这个锁定期内快速切换到纵向滑动，系统可能还在等待横向手势结束，导致纵向响应延迟。

解决思路很直接：为鸿蒙端的横向列表容器搭配一个定制的手势协调器，把横向和纵向的手势识别用GestureExclusive标记为互斥，并调整二者识别的优先级。实际在鸿蒙原生代码里，我们通过List的axis属性明确指定滚动方向为Axis.Horizontal，同时在父级竖向滚动容器上设置nestedScroll属性，让内部横向列表优先处理消费触摸事件。代码层面，由于react-native-harmony已经把List的axis属性暴露到RC Bridge里，我们只需要在JS侧给FlatList的scrollEnabled属性动态控制，在特定场景下手动禁用横向滚动，避免与外层竖向滚动冲突。

这套适配方案我们用如下配置落地：

tsx复制<FlatList
  horizontal
  nestedScrollEnabled={false}
  directionalLockEnabled
  ...
/>

directionalLockEnabled这个属性非常关键。它的作用是让列表在用户开始滑动时锁定一个主方向，只有在这个方向被识别为“无法继续滑动”时才允许切换另一个方向。在嵌有横向列表的竖向页面里，开启这个属性后，用户左右滑动时页面竖向滚动手势会被抑制，反之亦然，滑动冲突的概率能下降一个量级。

4.3 边缘回弹与滑动阻尼效果的适配参数

边缘回弹的适配，我把它做成了可配置参数，方便不同业务模块按需调整。鸿蒙原生的List组件支持通过edgeEffect和friction属性控制边缘效果的类型和阻尼系数。

由于react-native-harmony对鸿蒙原生List的edgeEffect暴露还不完整，我们在鸿蒙原生侧写了一个自定义Component，包装了原生List组件，并通过组件的通用属性透传方式暴露给JS层调用。具体来说，我们在鸿蒙原生侧定义了一个自定义组件，在它的onReady回调里获取到原生List节点，然后动态设置边缘效果参数。这样JS侧的业务代码只需要传递一个edgeEffectType字符串，原生代码负责解析并应用：

tsx复制// JS侧
<FlatList
  ...
  edgeEffectType={Platform.OS === 'harmony' ? 'spring' : undefined}
/>

typescript复制// 鸿蒙原生侧伪代码
const listNode = customComponent.findChildById('nativeList');
listNode.edgeEffect(EdgeEffect.Spring);
listNode.friction(0.6);

这里EdgeEffect.Spring对应弹性回弹模式，friction设0.6表示滑动阻尼适中，回弹速度平缓。这个值是我们多次真机调试得出的——调成0.4会感觉“太飘”，一根手指微滑就飞出去；调到0.8又感觉“太黏”，像拖拽一个没有惯性的方块。0.6在多数鸿蒙真机上呈现的滑动手感最自然。

我再提一个容易被忽视的点：材质对滑动手感的影响。鸿蒙手表、平板和手机上的默认摩擦系数不同。平板横屏展示的商品列表卡片数量更多，滑动速度如果沿用手机的配置，用户会觉得“刷得太快”。我们后来在平板设备上单独做了配置，friction调高到0.75，相当于增加了滑动阻尼。如果你们的App也面向多设备，建议在滑动参数配置里预留设备类型的判断分支，不要一套参数吃遍所有设备。

5. 常见问题与排查技巧实录

5.1 React Native启动白屏与Bundle加载问题

做鸿蒙适配的过程中，遇到的第一大拦路虎就是启动白屏。症状是在鸿蒙真机上安装应用后，点击图标要等很久才出现页面，甚至出现长时间白屏。这个问题在安卓上几乎不会遇到，但在鸿蒙上因为JSBundle的加载路径和模块注册机制不同，很容易出问题。

排查后发现，白屏的根因大部分是JSBundle没有正确加载。鸿蒙壳工程的rawfile目录下的index.js.bundle是必须手动拷贝进去的。在调试阶段，我们通过Metro服务加载远程Bundle，配置了getSourceUrl方法指向开发机的IP和端口。一旦切到生产模式，就必须把Bundle文件放进rawfile目录，并在ReactHost初始化时把jsBundleAssetPath指向entry/resources/rawfile/index.js.bundle。

还有一个容易忽略的地方是AppRegistry.registerComponent的组件名必须跟原生侧调用loadScript后创建的组件名严格一致。我们曾经因为大小写不一致，应用启动后卡在“正在加载”状态，却没有任何报错日志，排查了大半天才通过查看hilog的ReactNative标签找到了componentName mismatch提示。这里给大家一个排查建议：遇到白屏时先看日志里有没有ReactNativeJS标签的输出，有输出说明JS执行正常，问题出在原生渲染层；没有输出则说明Bundle根本没被加载。

5.2 列表刷新时闪动与数据位置错乱

横向商品列表在做下拉刷新或者点击分类Tab切换商品列表时，经常出现闪动和位置错乱。闪动指的是刷新后卡片先是空白，然后一下子全部显示出来，视觉上像眨眼一样；位置错乱则是刷新后列表停留的滚动偏移不在期望的位置，比如明明切到了第5个分类，列表却还停在之前的滚动位置。

闪动的根因还是数据渲染和虚拟化机制配合不当。刷新接口返回新数据后，数组引用变化，FlatList在极短时间内把旧的视图节点销毁、再创建新的视图节点，由于鸿蒙的渲染调度是异步的，销毁和创建之间出现了一个空窗期，表现为闪动。

解决这个问题的关键是在数据层做一次统一的更新缓冲，而不是让数据直接驱动FlatList的瞬时刷新。我们引入了InteractionManager和requestAnimationFrame组合，在数据返回后先保存到状态中，等当前帧的滚动和绘制完成后再更新列表。另外给FlatList设置了extraData属性，把它绑定到一个会随数据变化的计数器上，确保列表组件感知到数据更新。

位置错乱的问题则通过scrollToOffset来解决。在切换分类时，先拿到分类对应的列表ID，调用列表实例的scrollToIndex定位到目标索引，并配合viewPosition参数指定目标索引在视口中的位置。这里有一个经验之谈：scrollToIndex在数据量少、列表尚未完全渲染时可能找不到目标索引而报错，可以在调用前先执行一次scrollToOffset设为零，再执行scrollToIndex，稳定性会明显提升。

5.3 横向列表与外层竖向滚动手势冲突的最终方案

4.2节详细讲了手势冲突的原理，这里补充最终的完整排查方案。我们遇到的冲突在低端鸿蒙设备上尤其明显，低端机的触摸采样率较低，系统识别滑动方向需要采集更多的位移点，这期间如果用户的手指轨迹是“先横后竖”或者“先竖后横”，就很容易出现方向误判。

最终方案分三步落地。第一步，在原生侧统一给横向列表的父容器调整touch事件的传递链，确保横向列表的onTouchEvent优先响应并消费水平位移事件。第二步，在JS侧开启directionalLockEnabled，没有这个属性的平台会忽略它，而鸿蒙端因此获得了方向锁定能力。第三步，针对低端设备禁用了横向列表的instant惯性模式，回退到更保守的滑动模式，换来了稳定流畅的手感。

这样一个组合策略在测试机上表现稳定，用户几乎无感知。

下面是常见问题排查速查表，整理给团队新人看的，也分享给大家：

5.4 热重载与调试的实用技巧

最后分享几个在鸿蒙RN开发中非常实用的调试技巧，这些是平时文档里不太会写的东西。

使用DevEco Studio自带的ArkUI Inspector来检查RN渲染出来的页面层级，可以看到FlatList在鸿蒙侧实际映射成什么样的原生节点。我们刚接入时发现FlatList的每张卡片外面包了一层Flex容器，这会影响卡片间距的布局计算，知道这个层级关系后才能准确调试样式。

Metro的热更新在鸿蒙真机上不像安卓那么无缝，经常出现改完代码后鸿蒙App没有反应的情况。排查后发现是鸿蒙的Ability生命周期对端口变化的处理不完善，Metro重启后端口变了，但App还连接着旧端口。解决方法是启动Metro时固定--port 8081参数，同时在鸿蒙壳工程的配置里写死这个端口，避免DevEco自动切换。

使用console.log在鸿蒙上看不到输出，需要改用hilog，或者通过鸿蒙的Log窗口查看ReactNativeJS标签的信息。我们封装了一个工具函数，在鸿蒙环境下把console.log转发到hilog输出，这样既可以用统一的代码调试，又能正常看到日志。

这个项目的实践沉淀下来，我现在最大的体会是：跨平台开发的本质不是要求所有平台处处一致，而是找到一致的那一层业务抽象，再为每个平台留出交互级的适配余地。React Native在鸿蒙上的适配方案已经能支撑真实的电商业务需求了，横向List组件的性能和稳定性都不错，但离“零适配”还有距离。希望这篇文章能帮到正在做鸿蒙适配的团队少走几步弯路，哪怕只是省下排查哪个问题的半天时间，也值了。