Badger4us做鸿蒙 Flutter 开发这段时间，我一直在琢磨一件事：怎么把那些重复得让人麻木的命令行操作，变成一条简单指令。比如打测试包、统一改版本号、切换接口域名、批量跑单元测试，每次都要翻笔记敲一串命令，项目多了以后终端里全是密密麻麻的手工输入，环境一多还容易敲错。后来我翻到 Flutter 社区里一个叫 derry 的三方库，发现这玩意儿正好能解决这个痛点——它本质上是一个用 Dart 写的脚本执行器，你只需要把常用任务定义在一个配置文件里，后续直接 derry run xxx 就能触发，不用再记复杂命令。这篇文章就围绕 derry 以及它在 Flutter for OpenHarmony 项目里的落地方式，完整聊聊我怎么用它搭了一个自定义脚本控制台，也算是给鸿蒙项目加了个工作流加速引擎。
如果你是刚开始接触 Flutter 鸿蒙开发，或者已经写了几个月的鸿蒙 Flutter 业务，只要你手头有大量重复性命令需要处理，这篇文章都能给你一套可以直接抄作业的方案。我会从环境准备讲起，再把 derry 的配置语法、脚本编写思路、常见坑都过一遍，最后结合真实的鸿蒙 Flutter 项目场景演示几个自动化示例，保证看完就能用起来。
1. 为什么 Flutter 鸿蒙项目需要自定义脚本控制台
1.1 Flutter 鸿蒙开发中的重复性工作痛点
先把场景摆出来。一个正常的鸿蒙 Flutter 项目，日常开发中至少会遇到下面这些重复操作：
- 构建产物：
flutter build hap --debug、flutter build hap --release，鸿蒙的安装包不叫 apk，而是叫 hap，命令参数和安卓有差异。 - 版本号管理：每次发布前要在 pubspec.yaml 里手动改 version，改完还得同步到鸿蒙侧的配置文件，很容易漏。
- 环境切换：开发环境、测试环境、预发环境各有不同的接口地址，改配置文件时人工操作很容易搞混淆。
- 多设备部署：手上有好几台鸿蒙设备或模拟器，每次调试都要重复安装启动，步骤琐碎。
- 日志与诊断：跑完测试、抓完日志后文件散落各处，没有一个统一的出口。
这些动作如果每次都在终端手敲，不仅效率低，还非常容易出错。尤其是构建命令，Flutter 鸿蒙工程的构建参数比安卓、iOS 更复杂，动不动就是一大串参数还带路径。时间一长，团队里每个人手里的"正确命令"版本还不一样，有人用旧参数、有人用新格式，最后出来的产物莫名其妙出问题。
1.2 从命令行到工作流引擎：脚本工具的定位
业界早就给出了解法：把常用命令脚本化。前端有 npm scripts，后端有 Makefile，Java 生态有 Gradle Task，本质上都是把一组命令变成具名任务，让机器去记，而不是让人去记。Flutter 项目里同样存在这种需求，但是 Flutter 官方并没给出一套足够优雅的脚本方案，所以社区才冒出各种第三方工具，derry 就是其中做得比较完善的一个。
derry 的核心定位很简洁：在 Flutter/Dart 项目里声明并执行自定义脚本。它不依赖 shell，不要求你懂 bash、cmd 或者 PowerShell，脚本本身就写在 Dart 项目里，天然跨平台。对做鸿蒙 Flutter 的人来说，这条尤其重要，因为你的开发主力可能是 Windows，你是用命令行的，如果你用 macOS，命令行又不同，写一份 shell 脚本两边跑不起来，工作量直接翻倍。derry 通过抽象这一层，让你只需要写一次配置文件，全平台通用。
注意：这里的"自定义脚本控制台"并不是指带图形界面的控制台，而是指一种开发者命令行控制中心。它把分散的命令收敛成标准化任务入口，让团队协作时有一个唯一的执行入口。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 环境准备：搭建可运行的 Flutter for OpenHarmony 开发环境
2.1 Flutter SDK 与 OpenHarmony SDK 的版本匹配
想跑通 derry，前提是 Flutter 鸿蒙开发环境已经能正常用。这里有个非常值得注意的点：Flutter 的版本号分为 stable（偶数版本，如 3.22.0）和 beta（奇数版本，如 3.24.0），而 OpenHarmony 的 Flutter 适配分支往往滞后于官方版本。实际开发中，我踩过版本不匹配的坑，具体表现是：插件编译报错、flutter 工具链找不到鸿蒙 SDK、hap 构建产物异常。
我这里的建议是：先确定你使用的 OpenHarmony SDK 版本，再去匹配 Flutter for OpenHarmony 的 Release 分支。社区维护方一般会在 Releases 页面写明需要哪个版本的 Flutter 和哪个版本的 OpenHarmony SDK，照着用最稳。不要盲目追求最新 Flutter 版本，否则很可能编译直接挂掉。
提示：热词里有"flutter 各个版本不对导致依赖包下不下来"，这就是典型的版本匹配问题。你 pub 源里某个包要求的 Flutter 比你本地的高，或者反过来低于你本地的，都会让依赖解析失败。做鸿蒙开发时，这类问题会因为你用了自定义 Flutter 分支而变得更难排查，所以第一原则是：锁定版本，尽量和官方示例工程保持一致。
2.2 开发工具链配置
除了 Flutter SDK 本身，跑鸿蒙 Flutter 项目还需要：
- OpenHarmony SDK：从开源社区渠道下载 SDK 包，里面包含了 ohos-sdk、toolchains、命令行工具等。配置到 DevEco Studio 里，让 Flutter 能感知到鸿蒙 SDK 的存在。
- Node.js：鸿蒙构建链路中的 hvigor 等工具依赖 Node.js，环境变量里最好配好，否则构建时可能因为找不到 node 而报错。
- DevEco Studio：官方 IDE，用于管理鸿蒙工程、设备连接、签名配置等。注意 DevEco Studio 的版本要和 OpenHarmony SDK 配套，太新或太旧都不行。
- 命令行工具：确保
flutter doctor能正常识别 OpenHarmony 相关的项。如果 flutter doctor 里看不到鸿蒙相关的检测项，大概率是环境变量或者 SDK 路径配置有问题。
我个人的建议是先把一个最简单的 Flutter 鸿蒙 Demo 跑起来，确认构建链没问题，再考虑引入 derry。否则环境都没通，脚本工具上也没法调试。
2.3 环境变量与常见坑
环境变量这块有个高频问题被反复问到——"path 需要新终端生效"。不管你是 Windows 还是 macOS，修改完环境变量之后，打开的旧终端窗口是拿不到新配置的，必须新开一个终端再执行 flutter --version 来验证。很多人在旧终端里反复输入 echo，发现没变化，以为自己配错了，其实只是没新开窗口。
另外，设置 OpenHarmony SDK 路径时，我建议把它写进 shell 配置文件里，例如 export OHOS_SDK_HOME=/path/to/sdk，而不是只加在 IDE 的图形界面配置里，这样在终端里跑命令时才能找得到 SDK。检查工具链是否就绪，可以直接跑：
bash复制flutter doctor -v
重点看看 OpenHarmony 路径是否显示正确，如果提示找不到 SDK 或者 SDK 版本非法，优先检查路径是否指向了 sdk 根目录，而不是某个子目录。
3. derry 核心机制：把脚本变成工程资产
3.1 derry 的安装与初始化
聊完环境，来到正题。derry 的安装方式和其他 Flutter 三方库一致，在项目根目录执行下面的命令：
bash复制flutter pub add derry
这会自动往 pubspec.yaml 的 dev_dependencies 里加上 derry 依赖。安装完成后，再执行初始化命令：
bash复制dart run derry init
初始化命令会在项目根目录生成一个默认的 derry.yaml 文件，里面有一个示例脚本。从这一步开始，你就有自己的脚本控制台雏形了。
如果你不想用 dart run derry init，也可以手动创建 derry.yaml，格式非常简单，后面会讲。我个人习惯还是先用 init 生成一个模板，再改，因为模板里带了一些注释和常用示例，方便记忆。
3.2 derry.yaml 配置语法速览
derry.yaml 的核心结构就是一个 scripts 字段，下面挂一组键值对。key 是脚本名，value 是你要执行的命令。举个例子：
yaml复制scripts:
clean: flutter clean
get: flutter pub get
build_debug: flutter build hap --debug
run_app: flutter run -d <deviceId>
执行方式也很直观：
bash复制dart run derry run build_debug
或者省略 run，直接用：
bash复制dart run derry build_debug
分布式团队协作时，这里就显出了一个巨大优势：你团队的同事不需要再记那串 flutter build hap --debug --target-platform ohos-arm64 之类的完整命令，只要知道脚本名字 build_debug 就够了。脚本文件的注释里甚至可以写上参数说明、产物输出路径、注意事项，信息集中管理，不用再靠聊天记录传递命令。
更底层的脚本值支持用 | 块写入多行命令，灵活组合：
yaml复制scripts:
build_and_install: |
flutter build hap --debug
hdc install ./build/ohos/outputs/hap/debug/*.hap
对于执行复杂逻辑，derry 也支持直接运行一个独立的 Dart 文件：
yaml复制scripts:
bump_version: dart run tool/bump_version.dart
这样你可以把版本号递增、接口域名替换、产物复制等逻辑全部用 Dart 写出来，不仅可读性好，还可以断言、报错提示、打印彩色日志。
3.3 为什么选择 derry 而不是直接用 shell 脚本
我在团队里推 derry 的时候，有人问我，为什么不用 shell 脚本？原因有几点：
第一，跨平台。Shell 脚本在 Windows 上天然弱势，cmd 和 PowerShell 的语法又不兼容，同一个调用逻辑在不同平台要写两套。derry 基于 Dart，一套配置全平台跑。
第二，类型和安全。shell 里面参数传递、转义处理非常容易出问题。Dart 作为一门有类型的语言，写复杂逻辑时更能避免低级错误。
第三，可维护性。yaml 文件里的脚本项比 shell 脚本更结构化，团队新人扫一眼就明白有哪些任务可用，不用逐个看脚本源码才知道怎么调用。
第四，依赖复用。如果你之前已经写过 Dart 的工具类，比如读取 pubspec.yaml 的库、解析 JSON 的库，直接在 derry 脚本里复用就行，不用在 shell 里重新实现一遍。
当然，derry 也支持在 yaml 里直接写 shell 命令，相当于把 shell 脚本封装成了任务，兼顾两个生态的优势。实际上我后来大部分复杂逻辑都是写 Dart，简单命令用 yaml 里的一行定义，两边配合很舒服。
4. 实战：为鸿蒙 Flutter 项目搭建工作流加速引擎
4.1 一键切换环境配置（开发/测试/生产）
鸿蒙 Flutter 项目里最常见的自动化场景之一就是环境切换。你可能有三个环境，每个环境对应不同的 API baseUrl、不同的 appId、不同的日志开关。
传统做法是手动改代码里的常量，或者用 --dart-define 传参。用 --dart-define 虽然比改代码好，但参数写在命令行里又长又容易错。在 derry 里，这件事可以写成三条命令：
yaml复制scripts:
run_dev: flutter run -d <device> --dart-define=ENV=dev
run_staging: flutter run -d <device> --dart-define=ENV=staging
run_prod: flutter run -d <device> --dart-define=ENV=prod
在业务代码里，你只需要用 String.fromEnvironment('ENV') 读取即可。这个方案的优点在于，团队里所有人都用统一的命令入口，环境名对不上号的情况大幅减少。不过如果项目里环境配置逻辑比较复杂，比如还需要动态生成鸿蒙侧的权限配置，那我会写一个 Dart 脚本，统一处理配置文件的生成，然后在 derry 里调用。
4.2 版本号自动管理
接下来看版本号自动管理。鸿蒙 Flutter 项目的版本信息一般有两个地方：Flutter 侧的 pubspec.yaml 里的 version 字段，以及鸿蒙工程里 module.json5 或构建配置里的版本号。手动同步非常烦。
我写过一个 Dart 脚本 tool/bump_version.dart，大致逻辑是：读取 pubspec.yaml，解析当前版本号，根据参数决定是增加 patch、minor 还是 major，然后写回 pubspec.yaml，同时把新版本号写到项目根目录的一个 version 文件里，供鸿蒙构建配置读取。这样每次发版时，只要执行：
bash复制dart run derry bump
就能完成版本号统一递增。脚本核心代码类似：
dart复制import 'dart:io';
import 'package:yaml/yaml.dart';
// 伪代码示例，实际生产环境还需处理异常
void main(List<String> args) {
final file = File('pubspec.yaml');
final yaml = loadYaml(file.readAsStringSync()) as YamlMap;
final current = yaml['version'].toString();
print('当前版本: $current');
// 解析并递增版本号
// 回写 pubspec.yaml 和鸿蒙版本文件
}
这里的关键是：版本号统一收口到一个脚本里，避免各端配置漂移。踩过坑的朋友会懂，发布出去后线上版本对不上账，排查起来特别痛苦。
4.3 构建 HAR / HAP 的快捷命令
然后是高频操作：构建 hap 包。实际上，一个 Flutter 鸿蒙项目的构建不仅只有 hap，还经常要构建 HAR（Harmony Archive）供其他模块复用。derry 里可以把这些构建命令全部注册成脚本：
yaml复制scripts:
build_har: flutter build har --release
build_hap_debug: flutter build hap --debug
build_hap_release: flutter build hap --release
build_all: |
flutter build har --release
flutter build hap --release
使用起来也会更可控，减少了敲错参数的风险。构建完成后，脚本还可以顺手帮你把产物复制到约定的输出目录，或者自动打开产物所在目录。这些细碎的小动作，看起来不起眼，但在每天高频构建的场景下，能省出不少时间和精力。
实操心得：我在实际项目中会把产物输出目录固定下来，并且让 derry 脚本在构建结束后执行一段 Dart 代码，读取出产物路径后再打印出来。如果误操作把 hap 构建到了其他目录，脚本会在控制台给出警告。这比每次都自己去 build 目录里翻文件要舒服得多。
4.4 多设备部署与日志追踪
鸿蒙开发中，模拟器、真机、远程调试设备经常交叉使用，多个设备连接时的安装部署就很有必要脚本化。你可以先通过 hdc list targets 拿到设备列表，再用 derry 脚本包装安装逻辑。
我常用的一种方式是，脚本先枚举当前在线设备，弹出设备序号让你选择，选完后再执行 install 和 launch。例如用 Dart 写一个交互式部署工具，然后在 derry 里引一条命令：
yaml复制scripts:
deploy: dart run tool/deploy.dart
工具内部逻辑大概是这样：调用 hdc list targets 获取设备列表，然后 Python 风格地打印编号，让用户输入；随后根据用户选择拼装 hdc install -r 和 hdc shell aa start 的命令，在终端里执行。最后把应用启动日志重定向到项目里的 logs 目录，方便后续排查。
这么做最大的收益是：再也不用担心手滑把测试包装到错误的设备上，因为脚本已经在设备选择阶段帮你做了保护。虽然只是一个小细节，但对团队来说，却避免了很多不必要的环境问题。
4.5 集成测试与静态检查
除了构建和部署，研发流程中的代码质量检查也适合用 derry 整合。你可以把 flutter analyze、flutter test、coverage 等操作打包：
yaml复制scripts:
analyze: flutter analyze
test: flutter test
check: |
flutter analyze
flutter test --coverage
generate_graphics: dart run tool/gen_assets.dart
通过这组脚本，每次提交前只需要跑 dart run derry check，就能把静态检查和单元测试一起跑完，非常省心。对于团队而言，这相当于约定了统一的"体检"入口，而不是每个人自己拼命令。
注意：如果你同时接了安卓、iOS 和鸿蒙三端，建议在脚本里加上平台标识，例如
check_ohos、check_android、check_ios，避免因平台不同而导致命令分歧。
5. 实战中的常见问题与排查技巧
5.1 依赖包下载失败系列
很多人在配置阶段遇到的最多的就是依赖包下载失败，尤其是 Flutter 版本不对导致的依赖解析问题。这个问题在鸿蒙场景里更明显，因为你本地的 Flutter 可能是社区维护的分支，而 pub.dev 上的部分包版本可能并没有及时适配。
我的排查思路是这样的：先把 pubspec.lock 删掉，执行 flutter clean，再重新 flutter pub get；如果还不行，就检查 pub 源是不是被公网阻断或者镜像地址有问题。在这种情况下，打开 pubspec.yaml，把依赖版本范围写得窄一点，甚至锁定到某个实测通过的版本，会比依赖最新版更稳。
5.2 SDK 版本不匹配导致构建异常
前面提过，harmony 分区版本的 Flutter 和 OpenHarmony SDK 版本要配套。如果你在执行 flutter build hap 时遇到了奇怪的编译错误，先看看是不是 SDK 版本不匹配。这种报错往往不会直接提示"版本不对"，而是一堆 C++ 编译错误或 ArkTS 编译错误，特别容易误导人。
如果碰到这类情况，我的处理办法是回到官方示例工程，用官方指定的版本组合重跑一遍，确认官方示例能不能编译通过。如果官方示例能过、你的项目不能过，那大概率和项目里的依赖或配置有关；如果官方示例也过不了，那问题基本可以断定在 SDK 或 Flutter 版本组合上。
5.3 脚本在 IDE 终端与外部终端表现不一致
另一个坑是 derry 脚本在 DevEco Studio 或 VS Code 内置终端里能跑，在系统外部终端里却报"找不到命令"。这通常是环境变量在 IDE 里被加载了，而外部终端没加载所导致的。遇到这种不一致，先检查系统级环境变量到底配没配全，然后把 IDE 完全重启，确认它会读取最新的环境变量。
实测经验：VS Code 启动后不会自动刷新环境变量，必须重启整个 IDE 才能拿到新配置。强烈建议改完环境变量后顺手重启 IDE，而不是开个新窗口糊弄过去，否则排查起来特别让人抓狂。
5.4 derry 脚本中的路径问题与跨平台适配
在 yaml 脚本里如果写了绝对路径或者用了 shell 特有的语法，很容易在不同平台上挂掉。我实际操作中也遇到过 hdc install 的参数在 Windows 横线转义上的问题，解决方式就是别在 derry.yaml 里写太多平台相关命令，而是把复杂逻辑都移到 Dart 脚本中，通过 Platform.isWindows 等做条件分支。
另外，如果脚本里需要拼接路径，不要手写 / 或 \，用 File(path).path 或者 p 包里的 join 方法来处理。路径分隔符的问题看似小了，但我见过太多因为 Windows 路径里多了一个反斜杠导致的构建失败案例。
6. 几个锦上添花的 derry 技巧
6.1 为脚本添加交互式输入
有些任务并非完全不需要人工干预，比如选择打包类型、填写版本号说明、决定是否发布到内部平台。derry 的脚本最终可以落到 Dart 文件里，所以你可以轻松引用一些终端交互库，实现类似问卷调查的输入流程，让命令执行更有引导性。
比如在打包脚本里，你可以先问用户"是 debug 还是 release"，再问"是否上传制品平台"，得到答案后再开始执行。虽然这类交互多了以后会显得繁琐，但在一次发布流程中，集中收集信息，反而比分散在几次命令里更清晰。这个设计很适合小团队使用，基本上只需要一个人维护脚本，全团队一起用。
6.2 组合脚本实现流水线
derry.yaml 的值支持多行命令，所以你可以像搭积木一样组合多个已有脚本：
yaml复制scripts:
all_debug: |
dart run derry clean
dart run derry get
dart run derry analyze
dart run derry test
dart run derry build_hap_debug
这套思路非常像连续执行流水线，执行完一步再进下一步，每一步失败就自动中断（命令行非零退出码会中断 derry 的后续指令），避免把错误产物继续往下传。我自己日常最常用的一条组合命令，就是提交代码前跑一遍"clean + get + analyze + test"，把质量关卡前置，给 CI 减少不少无用功。
6.3 后续扩展方向
derry 本身可以一直往项目工作流里扩展。比如去对接持续集成平台，让本地脚本和 CI 执行同一套命令，这样就不会出现"本地能过、CI 上失败"的尴尬。也可以在脚本里嵌入文档生成、Changelog 生成、截图批量处理等任务，慢慢把整个项目流程的自动化水平提起来。
如果你用了一段时间，发现 derry 的简单配置文件已经满足不了需求，也可以研究下它的源码，看看能不能二次扩展。但就我的经验来说，大多数场景下 derry.yaml + Dart 脚本的组合已经很够用了，没必要过度设计。
7. 写在最后的个人体会
实际用 derry 跑鸿蒙 Flutter 项目有一段时间之后，我最大的感受是：脚本化的价值不在于省掉那几秒敲命令的时间，而在于让团队对"怎么做一件事"达成一致。无论新同事还是老同事，只要看一眼 derry.yaml，就知道项目里有哪些常用操作、每个操作背后做了什么，这是文档替代不了的。
另一个体会是：不要一开始就想着把所有事都脚本化，而是从最高频、最容易出错的两个动作开始，比如版本号管理和打 hap 包。等大家都能接受这种工作方式了，再去扩展环境切换、部署、测试等场景，推进阻力会小很多。工具是给人用的，如果一上来全自动化，反而会让团队失去对命令细节的理解，出了问题也不知道从哪里排查。
如果你也正在做 Flutter for OpenHarmony 项目，手头正好被一堆重复命令搞得心烦，我建议你把 derry 加进去试试。先从最简单的三五个脚本开始，跑上一周，再回过头来感受一下差别。这个自定义脚本控制台，并不需要多高深的技术，但它能把你的日常开发从"手忙脚乱"变成"悠然自得"，体验过就离不开了。