【Flutter×鸿蒙】debug 包也要签名，这点和 Android 差远了

系列导航：

• (1) 环境开荒
• (2) 驯服 SDK
• (3) 项目搬家 ← 你在这里
• (4) 保命急救箱

环境好了，SDK 稳了，真正的考验来了------把你手头已有的 Flutter 项目跑在鸿蒙设备上。我原以为就是敲几行命令的事，结果在 VS Code 版本显示不对、FVM 反复警告、签名这三个地方连续翻车。这篇把"老项目适配鸿蒙"拆成 5 关，每关一个核心操作。

前置条件 ：已完成第一篇（环境搭建）和第二篇（FVM + 鸿蒙 SDK），flutter doctor 中 HarmonyOS toolchain 为 ✓。

---

🗺️ 通关路线图

关卡	任务	预计耗时
第 1 关	锁定项目 SDK 版本 + 配置 VS Code	3 min
第 2 关	生成鸿蒙平台目录 ohos/	2 min
第 3 关	安装依赖 + 下载鸿蒙引擎	5-10 min（看网速）
第 4 关	配置签名（本篇 Boss 关）	5 min
第 5 关	构建运行	3-5 min

---

🎯 第 1 关：锁定 SDK 版本 + 配置 VS Code

目标：让当前项目使用鸿蒙版 Flutter SDK，并且 VS Code 也能识别。

📋 操作

在项目根目录的终端中执行以下命令，告诉 FVM"这个项目要用鸿蒙版 SDK"：

fvm use 3.35.8-ohos-0.0.2

FVM 会弹警告说版本号不标准，输入 y 回车即可。

执行后项目里会多出两个东西：

• .fvmrc 文件------记录版本号，提交到 Git
• .fvm/ 目录------SDK 的快捷方式，加入 .gitignore

然后配置 VS Code。在项目根目录下创建或编辑 .vscode/settings.json：

{
    "dart.flutterSdkPath": ".fvm/versions/3.35.8-ohos-0.0.2"
}

✅ 验证

• 看 VS Code 右下角的 Flutter 版本号是否变成 3.35.8-ohos-0.0.2。
• 如果没变：按 Cmd+Shift+P（Win: Ctrl+Shift+P），搜 Dart: Restart Analysis Server 重启分析器。

---

🎯 第 2 关：生成鸿蒙平台目录

目标 ：在项目里生成 ohos/ 目录（类似已有的 android/ 和 ios/）。

📋 操作

在项目根目录执行以下命令。yes | 的作用是自动跳过 FVM 的版本格式警告；末尾的 . 代表给当前目录的项目添加平台支持：

yes | fvm flutter create --platforms ohos .

执行后项目里会多出一个 ohos/ 目录，结构大致如下：

ohos/
├── AppScope/ # 应用全局配置（包名、图标等）
├── entry/ # 主模块（类似 Android 的 app 模块）
│ └── src/main/
│ ├── ets/ # ArkTS 代码（鸿蒙的 UI 框架代码）
│ └── module.json5
├── build-profile.json5 # 构建配置
├── oh-package.json5 # 包管理配置
└── hvigorfile.ts # 构建脚本

你不需要手动改这些文件，Flutter 已经帮你生成好了。

✅ 验证

在终端执行以下命令，列出 ohos 目录的内容：

ls ohos/

看到 AppScope、entry 等目录就过关。

如果报目录不存在，检查命令是否在项目根目录下执行。

---

🎯 第 3 关：安装依赖 + 下载鸿蒙引擎

目标：拉取 Dart 依赖包 + 下载鸿蒙平台的编译引擎。

📋 操作

先安装 Dart 依赖（你平时的 flutter pub get）：

yes | fvm flutter pub get

然后下载鸿蒙平台专用的引擎文件（约 200MB，只需每个 SDK 版本下载一次）：

yes | fvm flutter precache --ohos

⚠️ precache 这步很多人跳过，然后编译时被 Missing binary 红字砸晕。鸿蒙版 Flutter 需要专门的引擎编译产物（如 ohos-arm64），不手动下载的话编译必失败。
⚠️ 如果 precache 卡住不动，检查是否配了 Flutter 国内镜像。把下面这行加到 ~/.zshrc 里（~/.zshrc 是 macOS 终端的配置文件，编辑后执行 source ~/.zshrc 生效）：

export FLUTTER\_STORAGE\_BASE\_URL=<https://storage.flutter-io.cn>

✅ 验证

• pub get 最后一行输出 Got dependencies!
• precache 无报错完成

如果 pub get 报版本冲突，检查 pubspec.yaml 里的 SDK 约束是否兼容 3.35.x。

---

🎯 第 4 关：配置签名（本篇 Boss 关）

目标：给应用配好调试签名，否则连安装都装不上。

为什么这是 Boss 关

如果你是从 Android 过来的，这里的认知差异最大------Android 的 debug 包不需要签名就能装到手机上。但在鸿蒙系统里，所有应用都必须签名，包括 debug 包。没签名的应用连安装的资格都没有。

打个比方：Android 调试像进自家小区，刷脸就行；鸿蒙调试像进机关大院，再熟的面孔也得出示证件。

好消息是，DevEco Studio 提供了一键自动签名，不需要手动搞证书。

📋 操作（在 DevEco Studio 里操作，不是终端）

1. 打开 DevEco Studio
2. 点 Open Project，选择项目里的 ohos/ 子目录打开（不是项目根目录！）
3. 等右下角的进度条跑完（IDE 在加载项目）
4. 菜单 → File → Project Structure
5. 左侧选 Signing Configs
6. 勾选 Automatically generate signature
7. 首次需要登录华为开发者账号（没有就去注册一个，免费的）
8. 看到绿色的 Successfully generated signature 就成功了

⚠️ 第 2 步一定要选 ohos/ 目录，不是项目根目录。选错了 DevEco 不会识别为鸿蒙项目，你会看到一个空白的工程界面。

✅ 验证

ohos/ 目录下会多出签名相关的配置文件。你也可以直接进入下一关，构建时如果签名没配好会有明确的报错提示。

如果登录华为账号后仍然签名失败，检查网络连接，或尝试退出重新登录。

---

🎯 第 5 关：构建运行

目标：在鸿蒙设备上看到你的 Flutter 应用。

准备工作

• 用 USB 线连接鸿蒙手机（需要支持数据传输的线，充电线不一定行）
• 手机上打开开发者模式：设置 → 关于手机 → 连续点"软件版本"7 次
• 开启 USB 调试：设置 → 开发者选项 → USB 调试

📋 操作

先确认设备已连接（这条命令会列出电脑能识别的所有设备）：

~/fvm/versions/3.35.8-ohos-0.0.2/bin/flutter devices

看到设备列表里有你的鸿蒙手机后，构建并运行：

yes | fvm flutter run

⚠️ 第一次构建可能需要 3-5 分钟（hvigor 要下载依赖），后续会快很多。

✅ 验证

鸿蒙手机上出现你的 Flutter 应用界面 = 🎉 通关！

如果构建失败，按报错信息对号入座：

1. 提示"请配置调试签名" → 回第 4 关
2. 提示 Missing binary → 回第 3 关执行 precache
3. 看不到设备 → 检查数据线、USB 调试是否开启，试试换个 USB 口
4. 其他报错 → 下一篇"保命急救箱"专门解决

---

📦 Git 提交指南

把以下文件提交到 Git：

.fvmrc # 版本锁定（团队成员 clone 后 fvm install 自动配好）
.vscode/settings.json # VS Code SDK 路径
ohos/ # 鸿蒙平台代码（整个目录）

确保 .gitignore 里有：

.fvm/
ohos/.hvigor/
ohos/oh_modules/
build/

---

🏆 通关总结

项目	状态
项目 SDK 版本	✅ 已锁定为鸿蒙版
VS Code	✅ 识别鸿蒙版 SDK
ohos/ 目录	✅ 已生成
依赖安装	✅ pub get + precache 完成
签名配置	✅ DevEco 自动签名
构建运行	✅ 真机运行成功

回顾一下：这篇的核心是"让一个只有 android/ios 的老项目，多出一个能跑的 ohos 平台"。最大的认知差异在签名------记住鸿蒙上 debug 包也要签名，这点和 Android 完全不同。

下一篇预告 ：项目跑起来了，但迟早会遇到"昨天还好好的，今天突然报错"的情况。别慌，我给你准备了一套急救秘方。→ Flutter 鸿蒙通关手册（四）：保命急救箱

---

日常开发命令速查

# 以下命令都在项目根目录执行
# 安装/更新依赖
yes | fvm flutter pub get
# 运行（自动选择设备）
yes | fvm flutter run
# 构建 debug 包
yes | fvm flutter build hap --debug
# 构建 release 包
yes | fvm flutter build hap --release
# 查看设备列表
yes | fvm flutter devices
# 环境检查
yes | fvm flutter doctor

💡 如果嫌每次输 yes | 麻烦，直接用绝对路径：~/fvm/versions/3.35.8-ohos-0.0.2/bin/flutter run，完全不会弹警告。