这两年只要碰 Flutter 工程化基本绕不开三件事脚手架生成、依赖管理、构建流水线。pro_cli 就是用 Dart 写的那个干活的工具核心能力是生成一套标准化的 Dart 项目骨架支持自定义模版注入还能在创建完项目之后挂一整套工程化动作。听起来不复杂但真到鸿蒙化适配这一步你会发现原来的假设基本被推翻多了一个平台目录、一套完全不同的构建系统还有一套全新的依赖体系。这篇文章就围绕 pro_cli 的鸿蒙化适配把脚手架生成、模版注入、流水线定制这条链路怎么改、怎么验、怎么排坑完整梳理一遍适合正在给 Flutter 工程化工具做鸿蒙支持、或者想自己搭一套多端脚手架体系的团队参考。1. 先搞明白鸿蒙化适配到底在适配什么1.1 pro_cli 在工程化链路里的真实定位pro_cli 表面上是create命令本质上是把一个 Flutter 项目应该长什么样固化成模板、把创建项目之后要执行哪些工序固化为流水线的契约工具。团队里项目一多手工作坊式的复制老项目改包名就会出问题有人漏了换 bundle ID、有人忘了改描述文件、有人引用的依赖版本还停留在半年前的。脚手架把这些问题都变成模板里的变量和生成后的校验脚本出错概率一下就降下来了。这里要强调一点pro_cli 不是简单的 file copy它是模板渲染 配置下发 生命周期钩子三层结构。模板渲染负责把 projectName、bundleId 这类变量填进文件配置下发负责按平台生成对应的工程目录生命周期钩子负责在生成前后执行 pub get、代码格式化、目录迁移这些动作。这三层结构决定了它做鸿蒙化适配时我们是有明确的切入点可以动手的不需要把整个工具推翻重写。1.2 鸿蒙引入的三个新变量第一个新变量是平台目录。Flutter 老项目的标准平台是 android、ios、web、windows、macos、linux 这些鸿蒙不在其中。OpenHarmony SIG 维护了一份 Flutter 的分支工具链通过扩展 flutter 命令行工具识别ohos平台生成工程时自然要多出一整个ohos/目录里面是 DevEco Studio 那一套工程结构entry、module.json5、EntryAbility、ets 页面等等。这对 pro_cli 意味着模板树和平台枚举都要扩。第二个新变量是构建系统。Android 用 Gradle鸿蒙用的是 hvigor 和 ohpm产物是 HAP 包命令从flutter build apk变成hvigorw assembleHap。生成后的流水线不能再只认 flutter 全家桶得把这些新的构建命令编排进去。第三个新变量是依赖体系。普通 pub.dev 上的包大多没有鸿蒙的原生实现需要换成flutter_ohos这一系列的兼容包还要和当前 Flutter SDK 版本严格对齐。这块是后面踩坑最多的部分我放在第 5 节详细说。2. 拆解 pro_cli一次 create 背后完整跑过哪些流程2.1 从参数解析到模版渲染的四个关键环节一条典型的创建命令长这样pro_cli create app my_app --template basic --platform ohos,android --bundle-id com.example.myapp执行过程分成四段。第一段是参数解析pro_cli 会读入命令行参数同时读取模板目录下的 meta.yaml把模板声明的变量表 merge 进来。第二段是变量收集有的变量来自命令行有的来自交互式问答项目名、包名、描述、作者这些都是标准变量。第三段是复制并渲染模板里凡是带.tpl后缀的文件都会经过渲染引擎处理把{{ projectName }}这类占位符替换成真实值普通静态文件直接复制。第四段是生命周期钩子生成完毕后按照 meta.yaml 里配置的顺序执行afterCreate动作。理解这四个环节很重要因为鸿蒙化改造基本是在第二段和第三段做文章变量表里要加自己的鸿蒙参数模板渲染的目录树里要加 ohos 平台层。2.2 自定义模版注入的设计逻辑pro_cli 的自定义模版不是靠改源码实现的而是通过约定目录结构实现的。个人和团队可以把模版放在~/.pro_cli/templates/下也可以放在项目仓库里通过--template指定路径。每个模版就是一个目录里面必须有 meta.yaml 和 files 目录basic/ meta.yaml files/ pubspec.yaml.tpl analysis_options.yaml.tpl lib/ main.dart.tpl ohos/ entry/ src/main/module.json5.tplmeta.yaml 里描述这个模板的元信息和变量定义比如模板名、适用平台、变量默认值、生成后执行的钩子。这层设计把模板引擎和模板内容解耦所以鸿蒙化适配时完全可以在不动引擎代码的前提下通过新增一套带 ohos 目录的模板来做兼容。2.3 流水线定制的切入位置pro_cli 的流水线定制体现在生命周期钩子上。常见的钩子有beforeCreate、afterRender、afterCreate每个钩子可以声明多条命令。比如生成完毕之后先执行dart format再执行flutter pub get最后跑一遍静态分析这些都可以写进 meta.yamlhooks: afterCreate: - command: dart format . - command: flutter pub get - command: flutter analyze --no-pub鸿蒙化之后这个钩子列表里得加入ohpm install和hvigorw assembleHap。而且要注意执行顺序必须先保证 pub 依赖拿到的是与 SDK 匹配的 ohos 兼容版本再走鸿蒙的依赖安装和构建否则大概率在构建阶段报一堆链接错误。3. 鸿蒙化改造实操模板层、依赖层与自定义注入3.1 在模板树里加 ohos 平台层实操的第一步是扩展模板树。沿用原有目录结构在files/下新增ohos/entry/对应的目录层级files/ ohos/ entry/ src/main/ module.json5.tpl ets/ entryability/ EntryAbility.ets.tpl pages/ Index.ets.tplmodule.json5 是鸿蒙工程的核心配置文件里面最关键的变量是 bundleName 和 moduleName。bundleName 类似 Android 的 applicationId要求反域名格式而且一旦发布不能随意修改。在模板里我会把它声明为单独的变量不让它和 Dart 包名混在一起{ module: { name: entry, type: entry, srcEntry: ets/entryability/EntryAbility.ets, deviceTypes: [phone, tablet], bundleName: {{ bundleId }}, versionCode: {{ versionCode }}, versionName: {{ versionName }} } }有一点特别提醒module.json5 的字段比 AndroidManifest 严格缺失字段在 DevEco Studio 的编辑器里可能不报错但 hvigor 构建时会直接失败。所以模板变量越完整越好宁可多声明不要少声明。3.2 pubspec 依赖与 Flutter OHOS 运行时对齐鸿蒙化的依赖对齐是整套适配里最容易被忽略、又最容易炸的一环。普通 Flutter 工程的 pubspec 长这样dependencies: flutter: sdk: flutter flutter_local_notifications: ^17.0.0鸿蒙工程里Flutter SDK 本身用的是支持 ohos 平台的分支pub 依赖里则需要引入对应的兼容实现。以社区常见的做法为例pubspec 中会多出类似这样的配置dependencies: flutter: sdk: flutter flutter_ohos: ^1.0.0 flutter_local_notifications_ohos: ^17.0.0注意最后面这个版本号不是随便填的它需要和你实际使用的 Flutter SDK 分支版本对应。这里的逻辑是flutter_ohos包里编译的是与特定 Flutter 版本匹配的引擎封装版本差一个补丁都可能出现运行时找不到原生方法的问题。我们团队的做法是在脚手架模板里维护一张Flutter 版本 ↔ ohos 兼容包版本的映射表生成工程时根据命令行传入的 Flutter 版本自动挑选依赖版本而不是让开发者手填。3.3 自定义模版注入的鸿蒙化扩展团队内部通常会有自己的模板仓库比如统一封装了登录、埋点、主题的三方模板。这类模板做鸿蒙化时除了加 ohos 目录还需要在 meta.yaml 里补平台声明。我建议在模板元信息中增加platforms字段明确这个模板支持哪些平台name: company_basic platforms: [ohos, android, ios] variables: bundleId: type: string default: com.example.app useBloc: type: bool default: true模板注入带来的另一个问题是局部平台差异。同一个业务模块在 Android 和鸿蒙上往往需要不同的原生实现模板里可以用{{#if useBloc}}这类条件渲染来处理也可以为不同平台准备不同的文件后缀比如bootstrap.android.ets.tpl和bootstrap.ohos.ets.tpl。生成时 pro_cli 根据传入的平台列表只保留对应文件这样自定义模板既可以服务老的 Android/iOS 项目也能服务新的鸿蒙项目一套模板两处复用。4. 流水线定制与端到端验证4.1 生成后的置顶动作编排脚手架的价值一半在生成一半在生成后的动作。鸿蒙化之后我们的afterCreate钩子是这样排的hooks: afterCreate: - command: dart format . - command: flutter pub get - command: ohpm install - command: flutter analyze --no-pub顺序是有讲究的。ohpm install必须放在flutter pub get之后因为鸿蒙工程的 oh-package.json5 里往往要引用最近 pub 解析产出的本地路径flutter analyze放在最后是因为前面如果依赖没装齐analyze 会把一堆无法解析包的误报怼到你脸上排障时白费时间。4.2 CI 编排与产物验证脚手架生成的工程最终要进 CI。鸿蒙构建在 CI 里的编排和 Android 很相似但有几个关键差异。第一需要额外安装支持 ohos 平台的 Flutter SDK并且确保 PATH 里的 flutter 是这份而不是官方原版否则 flutter 命令根本看不到 ohos 设备。第二hvigor 依赖 Node.js 环境DevEco Studio 自带了一套但 CI 机器上得自己装好并且版本满足要求。第三构建命令不再是flutter build apk而是进入ohos/entry目录执行hvigorw assembleHap --mode module -p productdefault产物路径一般在ohos/entry/build/default/outputs/default/entry-default-unsigned.hap。CI 里拿到这个路径后建议顺手把产物做一次签名或压测验证避免每次都到真机才发现 HAP 装不上。4.3 业务层桥接验证EventChannel 与 Dart Stream 的配合鸿蒙化适配做完模板生成的工程能不能跑业务核心看桥接层。Flutter 与原生通信有三板斧MethodChannel、EventChannel、BasicMessageChannel。EventChannel 在鸿蒙端对应原生能力是事件流的推送比如电量变化、网络状态变化Dart 侧用 Stream 接收。这里有个高频问题很多团队的方法通道在 Android 上好好的换到鸿蒙就收不到事件原因是鸿蒙端的 EventChannel 需要在 EntryAbility 或对应的 AbilityStage 里主动注册并且事件发送的线程必须是指定线程随意切线程会导致事件丢失。模板里我一般会预置一个platform_bridge.dart把 MethodChannel 和 EventChannel 的创建、事件流封装、错误回调统一收敛在一个文件里业务层只面向 Dart Stream 编程。模板的鸿蒙侧同样预置对应的 ETS 实现生成工程后两端接口天然对齐不用每次新项目都重新趟一遍桥接的坑。如果模板里预置了 BLoC 这类状态管理结构桥接层也要跟着模块化否则 Dart Stream 的数据流到业务层时容易出现订阅时机错位界面上表现为数据延迟刷新。5. 常见问题与排查实录5.1 版本错位Flutter SDK 与 flutter_ohos 不同步这是鸿蒙化适配里遇到最多的坑。现象是构建时报类似 current configured Flutter SDK is not known to be fully supported 的警告或者运行时 Native 方法找不到直接崩。原因基本是 flutter_ohos 兼容包版本和当前使用的 Flutter SDK 分支版本错位。排查路径很固定先flutter --version确认 SDK 版本再去 flutter_ohos 的 release 说明里找对应的 Flutter 版本号两个对上才继续。我们在脚手架的版本映射表里已经加了校验生成工程时如果用户指定的组合不合法直接拒绝创建并提示可用组合从源头拦住这类问题。5.2 模板渲染失败与路径遗漏模板里常见的坑有两个。一个是渲染引擎对 bool 值的处理Mustache 类模板引擎对false和空字符串的行为在不同实现里有差异有些引擎里{{#if useBloc}}即使值是 false 也会走 true 分支必须强制转成字符串再渲染。另一个是文件路径遗漏.gitignore、.metadata 这类隐藏文件在复制阶段经常被过滤掉导致生成出来的工程在 git 里缺东西CI 一拉代码就构建失败。我们的解法是复制阶段用显式白名单把 dot 文件也纳入模板管理。5.3 构建阶段报错与平台插件适配hvigor 构建时最容易炸的地方是签名和插件。签名配置缺失会报 Signing configuration is not found平台插件适配不到位会在运行期报服务端找不到实现。建议每个三方可选插件都做成独立的 ohos 兼容包而不是在模板里打补丁。另外之前遇到过打包时抛出类似java.lang.AssertionError的异常大概率是 Gradle 或 hvigor 的缓存目录损坏清理~/.gradle/caches和相关构建缓存后重跑基本能恢复别一开始就去翻代码逻辑。还有业务侧如果从旧工程迁移过来记得检查 Gradle 脚本里是否存在把 Flutter 的 Gradle 插件用apply方式强引用的老写法鸿蒙分支的工具链对这类命令式引用比较敏感建议统一改成声明式配置。下面把高频问题整理成速查表现象可能原因处理建议pub get 后找不到 flutter_ohos 包依赖版本与 SDK 不匹配检查版本映射表使用脚手架推荐组合模板渲染出现字面量 {{ }}bool 值未转字符串渲染前统一类型转换hvigor 构建找不到 hvigorw 命令Node.js 环境缺失或版本低安装匹配版本并加入 PATH生成工程缺 .gitignore 等隐藏文件复制阶段过滤了 dot 文件改为显式白名单复制运行期 MethodChannel 无法调通鸿蒙端未注册对应能力在 EntryAbility 里补注册打包抛 AssertionErrorGradle 或 hvigor 缓存损坏清理缓存目录后重跑6. 一些亲测踩坑后的心得这套适配做完之后我自己最大的体会是脚手架工具的鸿蒙化本质上不是在适配一个新平台而是在适配一套新工具链。如果只改模板目录而不动钩子、不动版本映射、不动桥接层那生成的工程在 DevEco Studio 里能打开但一提交 CI 就各种断。所以做的时候一定要把模板、依赖、流水线、验证四件事当做一个整体来设计缺一环后面都要还债。另外有个小经验可以分享适配初期不要急着把所有模板一次性改成鸿蒙可用先挑一个最简模板跑通生成到构建的完整链路再逐步把公司内部那些带业务封装的模板迁移过来。这样风险可控排障时也容易定位是模板问题还是工具问题。pro_cli 这件事做完之后团队新建鸿蒙 Flutter 项目的时间从原来的一小时手工配置缩短到一条命令加两分钟等待这个收益还是相当实在的。