Flutter复杂表单编译时校验：代码生成与鸿蒙适配实践

如果你维护过一个字段超过二十、联动超过三层、校验规则互相依赖的 Flutter 表单页面，大概率体会过什么叫“状态混战”：controller 持有关系混乱、校验逻辑散落各处、一次 setState 的连锁反应谁也说不清。我在这个坑里蹲了大半年，最终靠 reactive_forms_generator 从根上解决了问题——它把类型安全校验提前到编译时阶段，由 build_runner 根据注解生成强类型的表单模型，复杂业务输入组件的状态管理终于不再靠“人肉维护”。最近我又把整套方案适配到了鸿蒙 HarmonyOS ohos 端侧，走完了一轮完整的移植，期间踩过 engine 版本、part 隔离、analyzer 约束这些典型坑。这篇文章就把整个过程拆开写清楚，适合被表单状态困扰的 Flutter 开发者，也适合正准备把 Flutter 工程迁到鸿蒙端侧的团队参考。

1. 被埋没的 Flutter 表单痛点：状态混战到底混在哪里

1.1 纯手写表单的“崩溃前夜”：三种典型状态灾难

用 TextFormField + setState 写表单，前十个字段都很顺，到第二十个字段时，代码会变得非常拧巴。我复盘过手头的大小项目，发现真正让人崩溃的并不是字段多，而是以下三种状态灾难反复出现。

第一，controller 的“双份状态”。TextFormField 需要 TextEditingController 持有输入值，但业务上你又不得不在 State 里额外维护一份“业务状态”用做联动判断和提交。两份状态的同步全靠 setState 手动搬运，任何一个分支忘记搬运，页面上显示的值和表单校验拿到的值就不一致。这种不一致往往只在特定操作路径下出现，复现成本很高。

第二，校验逻辑的“三处散落”。同一个字段的必填规则，可能存在于 widget 的输入校验参数里一份、提交按钮点击时的判断逻辑里一份、某个监听器里一份。规则一旦散落，需求变化时很容易只改了一处、漏了两处，线上反馈“这个字段明明填了却提示必填”的 bug，追踪根源都是校验逻辑不一致。

第三，联动更新的“蝴蝶效应”。A 改变要重置 B，B 的校验依赖 C，C 被 disable 后又反过来影响 A。手写联动时你会在一堆监听器里手动调用 controller.clear()、setState()，执行顺序稍微错一点，就是一个隐藏的时序 bug。页面上看不出异常，但只要换一种操作节奏，状态就会错乱。

这三类问题的共同根源是：表单本身是一个有状态的领域——值、校验、交互状态（enabled/disabled/touched/dirty）都是需要被建模的实体——而 TextFormField + setState 这套组合根本不为表单领域建模，状态散落在无数局部变量和 build 方法里。你缺的不是更聪明的 setState，而是一个独立的表单状态模型。

1.2 为什么通用状态管理方案救不了表单

很多人遇到表单复杂度的第一反应是上 Bloc 或 Riverpod。我一开始也是这么干的，结果折腾一圈发现方向上就不对。Bloc 处理的是“业务事件流”，但表单字段有自己的生命周期：focus、touched、dirty、pending、validationErrors，这些状态和 UI 渲染时机强绑定。如果你为每个输入框创建一个 event/state 对，敲击键盘的每一次变化都会产生一条事件，事件规模立刻失控。Riverpod 支持对单字段做细粒度监听，比 Bloc 顺手，但联动规则、校验依赖、错误展示这层领域能力仍然要你自己造轮子——注意，这些才是复杂表单真正的复杂度所在。

我现在的判断是：表单需要的是“响应式表单模型 + 声明式校验规则 + 自动生成的样板代码”，而不是又一个通用的状态容器。通用状态容器负责的是业务状态，表单状态应该由专门模型负责，两者通过少量桥接代码互通，这才是干净的分层。

1.3 响应式表单模型的解题方向

reactive_forms 这个库提供了 FormGroup（控件组）、FormControl（单个控件）、FormArray（动态数组）这套层级模型。字段值、校验状态、交互状态全部收敛到模型树里，UI 通过 Reactive 系列组件与模型绑定，由模型驱动界面而不是界面手动搬运状态。方向上没问题，但直接手写 reactive_forms 的模型仍然很啰嗦——10 个字段就要写 10 个 control 声明、10 段 validator 配置、10 个控件注册步骤。于是有了 reactive_forms_generator：用注解描述字段，用 build_runner 在编译时生成模型代码，把“声明表单结构”这一层从手写代码里解放出来。下一章我们深入生成器内部，看它是怎么跑通的。

2. reactive_forms_generator 的运作内核：注解、生成器与编译时拦截

2.1 reactive_forms 的核心模型：这棵字段树到底长什么样

先确立一个基础共识：reactive_forms 的表单就是一个由 AbstractControl 组成的控件树。

• FormControl 是叶子节点，持有 value、validationErrors、status（valid/invalid/pending/disabled）；
• FormGroup 是容器节点，可以嵌套，组成一棵树；
• FormArray 是同类型控件的动态数组，适合发票明细、成员列表这类行数不固定的场景；
• 每个节点都暴露 valueChanges、statusChanges、focusChanges 等流，可被订阅。

UI 层的绑定组件会监听这些流：例如 ReactiveTextFormField 收到控件的 valueChanges 后自动更新显示，不需要你在每个输入事件里手动搬运值。校验器则是注入到控件定义中的纯函数列表，控件 value 变化或调用 validate() 时触发。整个体系的核心收益在于：表单状态不再分散在 N 个 controller 和 setState 里，而是集中在一棵有明确父子关系的控件树中。

2.2 注解、build_runner 与生成产物的完整链路

reactive_forms_generator 的使用模式和 Dart 生态里常见的 codegen 库一致：你在源文件里用注解描述表单字段，跑flutter pub run build_runner build --delete-conflicting-outputs，生成器扫描注解并输出强类型的 FormGroup 子类代码。

一个典型的源文件大致长这样（不同库版本的注解名称可能略有差异，以实际安装版本为准，但整体模式是稳定的）：

import 'package:reactive_forms_generator/reactive_forms_generator.dart'; part 'profile_form.g.dart'; @GenerateForm([ FormItem('name', FormItemType.string, validators: [Validators.required]), FormItem('age', FormItemType.number, validators: [Validators.required, Validators.min(18)]), FormItem('email', FormItemType.string, validators: [Validators.required, Validators.email]), ]) class ProfileForm {}

跑完生成后，同目录下会多出一个 profile_form.g.dart。它根据注解里的字段名、类型、校验器列表，生成一个完整的 ProfileFormGroup 类和若干强类型字段入口。你在业务代码里直接实例化 ProfileFormGroup 就能拿到一个初始化完成、校验规则内置的表单树。关键的一点是：注解里写的一切——字段名、类型、校验器——在这个阶段已经被“固化”进代码了，它们不再是运行时的动态数据，而是静态的类定义。这就是标题里“介入类型安全校验编译时阶段”的具体含义。

2.3 为什么要引入 part：Dart 库隔离机制与生成代码的归属

每个用过 build_runner 的人都会在 part 上面懵一次。为什么生成代码要用part 'xxx.g.dart'，而不是像普通依赖那样import？这要从 Dart 的库模型讲起。

import 引入的是另一个库，库与库之间命名空间隔离，只有声明为 public 的成员可见；而 part 则是把多个文件“合并”到同一个库中，part 文件可以访问当前库中的所有私有成员，当前库也能看到 part 文件里的所有定义，两者共享同一个命名空间。codegen 必须用 part 的原因是：生成代码通常需要引用你源文件里定义的私有枚举、私有 validator 函数、甚至私有类型；如果把生成代码放在一个独立库里 import 进来，这些私有成员对它不可见，生成代码就无法编译。反过来，你的业务代码也可能需要直接调用生成代码里的私有辅助方法。

part 指令的位置也有讲究：它要放在 library 声明和所有 import 之后、其他声明之前。这不算什么华丽规则，但写错位置的代价很实际——生成代码无法被并入当前库，类自然不可见。我在第六章会给出一个真实踩坑场景，part 写错位置导致生成文件明明躺在那里，业务代码却完全看不到生成的类。

3. 编译时阶段介入类型安全：把错误挡在构建管道里

3.1 为什么不能在运行时依赖反射：dart:mirrors 的取舍

要解释“编译时阶段”为什么成立，得先回答一个底层问题：Dart 生态明明有反射，Flutter 为什么不用？Dart 标准库提供 dart:mirrors 可以用运行时反射扫描类成员、获取注解信息、动态调用方法，但 Flutter 为了控制 AOT 产物体积，把这部分能力裁掉了。你在 Flutter 工程里 import 'dart:mirrors' 会直接报错。基于动态注解和运行时反射去实现“类型安全校验”，在 Flutter 里是走不通的。

社区给出的答案就是代码生成：与其在运行时“看”注解，不如在编译之前就把注解处理成静态代码。build_runner 这类工具本质上是一个“元编译步骤”——它扫描注解、分析类型、生成代码，这几件事本来反射也能做，但代码生成做出来的结果是可以被编译器静态检查的强类型代码。与其说我们放弃了反射，不如说我们把反射的工作提前到编译期，并且产出了更可审计、更快的运行时代码。编译时阶段介入的另一个现实价值是：它能被 CI 捕获。跑一个单元测试可能需要几分钟甚至几十分钟，但编译失败是秒级反馈。

3.2 编译时校验拦截的是哪几类错误

有了生成代码，业务层拿到的表单对象不再是Map<String, dynamic>那种弱类型结构，而是具体的强类型类。我整理了一个对照表，能比较直观地看出编译时拦截的收益：

就举字段名拼错这一个例子。手写表单时form.control<FormControl<String>>('email')打成了'emial'，IDE 和编译器都不会有任何反应，代码正常运行，只是你取到的永远是 null，然后你在提交逻辑里看到一堆诡异的结果。而生成式表单给你的是form.email这种成员化的入口，拼错了在写代码的瞬间红波浪线就出来了。

这种情况如果出现在集成测试阶段，定位成本少说一小时起步，多则跨天——因为运行时错误往往只在特定操作路径上触发。编译时拦截则完全改变了游戏规则：你把绝大部分低级错误消灭在写代码的当下，留给测试工程师的只有真正的业务逻辑问题。

3.3 一个“编译期拦截”的实测对比：手写 vs 生成

为了把收益讲得更具体，我放一个实测对比。手写 reactive_forms 模型时，代码会是这样：

final form = fb.group({ 'name': FormControl<String>(validators: [Validators.required]), 'age': FormControl<int>(validators: [Validators.required, Validators.min(18)]), }); // 手一抖，把 age 打成了 ege final ageControl = form.control<FormControl<int>>('ege'); // 编译器毫无反应，运行时才炸

接入 reactive_forms_generator 之后，同样的表单变成这样：

final form = ProfileFormGroup(); // 直接访问生成出来的字段入口（生成的类成员命名依 generator 实现而定，核心是强类型入口） final ageValue = form.age.value; // 如果字段名写错，这里在编译期就通不过

对比非常直观：前者要等到某次运行路径触发才暴露问题，后者的错误提示出现在你按保存的那一刻。当然，生成式强类型并不能消灭所有运行时问题——业务级联动规则写错、对服务端返回值的特殊处理不当，依然会在运行时发生——但它的确把表单里占比最高、最重复的那类错误挡在了构建管道之外。这就是我认为“编译时类型安全校验”不是噱头、而是实打实可感知收益的原因。

4. 鸿蒙端侧适配工程要点：从镜像源到 ohos 包对齐

4.1 鸿蒙侧 Flutter 引擎分支与工具链准备

把 Flutter 工程迁到鸿蒙端侧，首先要纠正一个认知：鸿蒙不是 Android，Flutter 官方 SDK 不能直接构建 ohos 产物，需要用到面向 OpenHarmony 生态维护的 Flutter 分支。当前普遍的做法是使用社区维护的 flutter_flutter 分支，它在 Flutter 社区版基础上补齐 ohos 平台的构建能力，引擎产物以 OpenHarmony 组件的形式被 ohos 工程集成。

我这边跑通的准备流程大致如下：

1. 拉取与目标 Flutter 版本匹配的 ohos 分支 SDK，替换默认 Flutter SDK 路径；
2. 配置环境变量，让 Flutter 工具链从可访问的镜像仓库拉取依赖和 SDK 资源：国内团队通常会把 PUB_HOSTED_URL 和 FLUTTER_STORAGE_BASE_URL 指向华为云镜像，这一步几乎是绕不开的；
3. 在工程目录下创建 ohos 平台目录（具体方式取决于所用 Flutter 分支提供的工具链）；
4. 用 DevEco Studio 打开 ohos 工程，检查 API 版本与 SDK 配置；
5. 先把一个最简页面跑起来，验证 Flutter 引擎在鸿蒙端能正常渲染，再引入业务代码。

这里要特别提醒：不要把 pub get 拉取到的“社区版 Flutter SDK 依赖”直接用在 ohos 分支上。二者版本标记不同，混用会在后续构建阶段产生大量诡异报错。我的做法是每一台开发机、每一台 CI 机器上统一一套 SDK 版本，不允许各自升级，保证团队内版本一致。

4.2 三方依赖如何在 ohos 工程中落地：reactive_forms_generator 的适配

reactive_forms_generator 本身是纯 Dart 库，与原生平台无关，接入 ohos 的难点不在库本身，而在它依赖的工具链能否和新环境兼容。我实际遇到的有三类问题。

第一类是依赖解析。Flutter ohos 分支维护的 SDK 版本与社区版存在差异，pub 解析时可能出现 sdk constraint 告警；reactive_forms_generator 这类 codegen 库对 analyzer、source_gen、build_runner 的版本非常敏感，pub get 阶段就可能爆 constraint 冲突。这类问题必须在适配早期处理掉，否则后续每一步都会雪上加霜。

第二类是构建链路。鸿蒙 Flutter 应用的构建由 Flutter 工具链和 ohos 的构建体系分段完成，codegen 必须在 Flutter 侧 build phase 先执行。CI 配置里要明确拆成两步：先执行 build_runner 生成代码，再做 ohos 构建。如果直接把未生成的工程交给 ohos 构建管道，会在最后阶段报“找不到 XXFormGroup”的类错误，定位半天才发现是生成步骤没跑。

第三类是产物打包。如果项目里有自定义原生能力，需要为 ohos 端写 PlatformChannel 的实现；纯表单模型这一层不涉及原生，只要 Flutter 侧编译通过，ohos 打包一般不额外处理。但要注意，Reactive 系列的 UI 绑定组件内部没有任何原生调用，鸿蒙端可以放心使用。

4.3 构建配置与端侧验证清单

在鸿蒙端侧验证 reactive_forms_generator 是否适配成功，我建议按这个清单逐项过：

• pubspec.yaml 中已正确加入 reactive_forms_generator、build_runner，版本约束与当前 Flutter SDK 匹配；
• 源文件顶部有 part 指令，且生成的 .g.dart 已提交或已纳入构建生成步骤；
• flutter pub run build_runner build --delete-conflicting-outputs能稳定生成成功；
• flutter analyze在生成代码后无类型错误；
• ohos 工程中引用的 Flutter 引擎版本与 SDK 分支版本一致，真机/模拟器无 engine version mismatch 告警；
• 端侧跑通一个含 ReactiveTextFormField 的表单页面，确认输入、校验、提交整条链路正常。

其中第 5 条是我踩过的坑：版本不一致时，编译期通常没有明显错误，但真机上 Flutter 页面拉起瞬间可能黑屏或直接崩溃，表现极像引擎 bug，实际就是版本错配。下一章我用一个真实的重构案例来展示整个方案的完整收益。

5. 复杂业务输入组件重构实战：拆除 40 字段联动表单的地雷阵

5.1 改造前：40 字段“账单审核表单”的混乱现场

我接手过一个账单审核表单模块，40 个字段，分三组：基础信息、费用明细、审核备注。字段之间有三条联动规则：费用类型决定费用科目；是否对公决定开票相关字段是否可见；客户等级决定审核备注是否必填。改造前，代码特征非常典型：State 里持有 18 个 TextEditingController，build 方法里 6 个嵌套的可见性判断，每个 setState 都可能触发十几次 rebuild。最可怕的是提交时那个巨型 validate() 方法——几十个 if 依次判断，失败后弹一个 snackbar，用户根本不知道具体哪里错了。

之前加一个“客户等级决定备注必填”的需求，前后花了两个下午：要找到正确的 controller、处理两组字段的可见性切换、还要在提交校验里插入新规则。改完的代码我自己都不敢碰第二次，因为联动触发的时序问题一旦出现，真不好排查。

5.2 改造后：注解 + 生成代码驱动的表单模型

重构时先定义了数据结构——直接写在注解里，不写手动的模型重复代码。注解风格按你安装的库版本为准，我这里展示的是项目里实际使用的结构，重点是分组、类型、校验器如何声明：

@GenerateForm([ FormItem('baseInfo', FormItemType.group, children: [ FormItem('customerName', FormItemType.string, validators: [Validators.required]), FormItem('customerLevel', FormItemType.string, validators: [Validators.required]), FormItem('billType', FormItemType.string, validators: [Validators.required]), ]), FormItem('feeType', FormItemType.string, validators: [Validators.required]), FormItem('feeSubject', FormItemType.string, validators: [Validators.required]), FormItem('invoiceVisible', FormItemType.boolean), FormItem('invoiceTitle', FormItemType.string), FormItem('auditRemark', FormItemType.string), ]) class BillReviewForm {}

生成器产出的 BillReviewFormGroup 直接初始化整个表单树。UI 层把原来手写的 TextFormField 全部换成 Reactive 系列绑定组件，页面代码里不再出现 controller、不再有 setState 驱动的可见性 if。像“开票字段是否可见”这种逻辑，直接由 model 层的 controls 状态决定，UI 只是被动渲染。

原来的 300 多行表单初始化骨架，变成了 60 行左右的注解加生成的代码。更重要的是，字段结构本身现在是一份单一来源的声明，不会再出现“页面改了字段、提交逻辑没同步”的漂移。

5.3 联动逻辑沉淀：reactions 与 valueChanges 的正确姿势

联动逻辑的正确做法是只在模型层实现。以“费用类型决定费用科目”这条规则为例，监听 feeType 的 valueChanges，然后自己调整 feeSubject 的状态：

form.controls['feeType']!.valueChanges.listen((value) { final feeSubject = form.controls['feeSubject']!; if (value == '固定费用') { feeSubject.enabled = true; } else { feeSubject.value = null; feeSubject.disabled = true; } });

写联动时我有几个具体的经验，都是踩过不少次才沉淀下来的。

一是 disabled 控件的值会被清空，且不再参与校验。所以当你 disable 一个字段前，务必想清楚它的值还要不要保留：要保留就改 visible 控制而不是直接 disabled；不要保留就显式清空，不要依赖 disabled 行为去隐藏。这个语义差异很容易导致提交时数据丢失。

二是 markAllAsTouched、markAsTouched 与 updateValueAndValidity 这三个方法要分清。提交前典型做法是form.markAllAsTouched()触发所有控件的 touched 状态，让错误提示全部出现在 UI 上；此时如果控件的 disabled 状态错误，校验不会触发，错误提示也就永远不出现，表现为“页面没报错，但提交不了”。

三是把联动规则收敛在模型层后，UI 层组件重建时不会重复触发监听，从而避免了一套监听被注册多份、一份联动被重复执行的问题。这是从“到处 setState”到“模型驱动”之后才拿到的稳定性红利。

改造完的效果很直接：同一个需求再改起来，改动范围从两个下午缩到了一个小时内。因为字段结构变动时编译器会告诉我所有引用点，联动逻辑从页面里抽离到 model 后，看代码的人不需要再脑补整棵状态树。

6. 适配过程中的典型故障与定位思路

6.1 故障一：build_runner 生成失败与 analyzer 版本冲突

现象：执行flutter pub run build_runner build --delete-conflicting-outputs时，pub solve 阶段直接失败，日志尾部能看到类似 “version solving failed ... analyzer >=x.x.x <y.y.y” 的约束冲突信息。

我的排查链路是分成四步走的：

1. 不要看整个日志，只看 version solving 部分。pub 的报错里会把所有冲突的依赖列出来，先锁定参与冲突的三个角色：reactive_forms_generator、build_runner、以及和 analyzer 有约束关系的某个传递依赖；
2. 用flutter pub deps确认当前锁定的 analyzer 实际版本；
3. 到 pub.dev 上查 reactive_forms_generator 当前版本声明的 analyzer 约束范围，判定是哪个包的 constraint 覆盖了其它方；
4. 解决手段通常是两种抬一：要么升级 reactive_forms_generator 到匹配版本，要么锁定 build_runner 到旧版；如果冲突来自传递依赖，用 dependency_overrides 临时对齐一次。

这里有一条几乎不会错的经验：codegen 类工具链必须整族升级，不能只动一个库。build_runner、analyzer、source_gen、reactive_forms_generator 之间版本耦合很强，单独升级其中一个，大概率会引出新的约束冲突。我们在鸿蒙分支的适配中就是一口气把这一族都对齐到当前 Flutter SDK 支持的版本，没有再拆开升级。

6.2 故障二：鸿蒙真机上的引擎版本告警

现象：build 环节一切正常，但真机上拉起 Flutter 页面时，控制台出现 engine version mismatch 之类的告警，页面要么黑屏要么直接退出。

根因是 SDK 分支版本与 ohos 端侧引擎产物不一致。Flutter ohos 分支的 SDK 和引擎是绑定的，工程里如果用了 SDK 3.x 的某次构建，但 ohos 工程引用的 FlutterLoader 或引擎组件来自另一个版本，就会在运行时对不上。

排查路径：

1. 先在开发机上执行flutter --version，记录完整版本 hash；
2. 打开 ohos 工程，检查 flutter 引擎相关配置声明，看版本 hash 是否与 SDK 一致；
3. 把 ohos 目录下的 build、缓存目录删掉，重新执行构建——很多时候是增量构建把旧引擎产物混进来了；
4. 如果还不行，回到镜像源下载目录，确认拉取到的引擎确实是对应版本的产物，特别要留意配置了镜像源后，镜像上版本列表可能滞后，静默拉到的旧引擎没有被察觉。

这个故障最迷惑人的地方在于：编译期完全正常，只有真机运行时才暴露，且报错信息常常指向引擎内部代码而非你的业务代码。所以一旦在鸿蒙端出现“Flutter 页面异常退出”且表单代码逻辑没有明显问题，优先考虑版本错配，而不是去调试表单。

6.3 故障三：part 文件路径与 library 名不一致导致的编译错误

现象：build_runner 成功生成了 .g.dart，文件也躺在源码目录里，但业务代码编译时一直报 Undefined class 'ProfileFormGroup'，IDE 里那个类名怎么都找不出来。

这个问题的定位链路虽然不长，但原因很典型：

1. 先检查源文件里的 part 指令是否写在正确位置。part 必须放在 library 声明和所有 import 之后、其他业务声明之前。我见过有人把 part 放在 import 声明之前，或者夹在多个 import 之间，编译器直接报 unexpected token，生成代码和源文件没有建立预期的库合并关系；
2. 确认 .g.dart 文件名与源文件同名且在同一目录。生成器的路径规则是写死的，手动改文件名或移动到别的目录，part 关系立刻断裂；
3. 确认没有隐式的 library 名冲突。如果两个文件各自声明了不同的 library 名，或者其中一个文件的库名与生成文件期望的库名不一致，同样会出现“文件在眼前但类不可见”的诡异状态；
4. 如果以上都对，检查项目里 .g.dart 是否被 git 忽略、CI 拉取代码后没有重新生成。codegen 产物分两类团队习惯：提交进仓库，或在构建时统一生成。如果是后者，必须把 build_runner 步骤固化进 CI 的第一个 stage，否则每次换环境都要手动补一次。

这类问题几乎每个 build_runner 项目都会遇到一次，但成因就那么几个，按上面的链路从上到下过一遍，十分钟内基本能定位。

6.4 一个通用定位方法：最小复现工程

如果上面这些常规排查都失效，我的经验是别再原地打转了，直接做一个最小复现工程：把业务源文件和 pubspec.yaml 抽出来，放到一个干净目录，只跑 build_runner 和 flutter analyze，不碰业务构建。90% 的情况下，问题会被快速压缩到两种可能之一：要么是 pubspec 依赖组合有问题，要么是源文件里的注解/part 写法有问题。我的体感是，codegen 相关的疑难杂症里，至少六成最终定位到 pubspec 依赖组合，而不是业务代码本身。所以最小复现工程是效率最高的收尾手段。

最后再分享一个体会。之前团队里推广这套方案时，最有说服力的不是代码行数少了几百，而是“同事们终于敢改表单代码了”。编译期拦下来的错误，安全感完全不一样。如果你也在维护复杂 Flutter 表单，我的建议是别急着全量迁移，挑一个字段最多、联动最复杂的页面先试水，跑通一次 build_runner，看看重构前后的差异，再决定要不要推广。至于鸿蒙端侧，直接按本文的适配清单走就行，同时一定记得把 build_runner 生成步骤固化到 CI 的前置阶段——这一步能省掉后续无数个“环境对不上”的夜晚。