【Day11】开源鸿蒙复盘（1）

最近在做 Flutter 迁移/鸿蒙化尝试的同学越来越多，但很多人第一步就会卡在“工具链搭不起来、能写 Flutter 但跑不进鸿蒙、hap 构建失败”这些问题上。因此 Day1-6 的学习价值非常高：它不是讲概念，而是手把手搭出一条 Flutter → OpenHarmony 的真实编译运行链路，并用 GitCode 口袋工具这个小项目验证链路可用。只要这一段走通，后面的组件封装、插件适配、业务

2401_84972713

391人浏览 · 2025-12-04 14:58:51

2401_84972713 · 2025-12-04 14:58:51 发布

参考链接

【DAY1-3】零基础Flutter 编译开发鸿蒙openHarmonyOS

DAY【4-6】开源鸿蒙Flutter如何搭建GitCode口袋工具

【Day7-10】开源鸿蒙之Flutter 的自定义组件封装（1）

【Day7-10】开源鸿蒙Flutter 常用组件封装实战（2）

【Day7-10】开源鸿蒙组件封装实战（3）仿知乎日报的首页轮播图实现

Day1-3 搭环境，Day4-6 用真实项目跑通整条链路。

前言

最近在做 Flutter 迁移/鸿蒙化尝试的同学越来越多，但很多人第一步就会卡在“工具链搭不起来、能写 Flutter 但跑不进鸿蒙、hap 构建失败”这些问题上。因此 Day1-6 的学习价值非常高：它不是讲概念，而是手把手搭出一条 Flutter → OpenHarmony 的真实编译运行链路，并用 GitCode 口袋工具这个小项目验证链路可用。只要这一段走通，后面的组件封装、插件适配、业务迁移才有意义。

1. 为什么要先搭链路

Flutter 本质是跨平台 UI 框架，但想在 OpenHarmony/鸿蒙生态落地，不能只装个 Flutter 就完事。鸿蒙侧需要自己的 SDK、模拟器、IDE、签名体系以及 ArkUI-X 相关组件。
因此 Day1-3 解决的是**“把鸿蒙端环境铺好，让 flutter build hap 变成可执行动作”；Day4-6 解决的是“给你一个真实项目，验证你这条链路不是玩具而是工程可用”**。

2. Windows 环境准备（Day1-3）

2.1 基础三件套

Git
用于拉取工程、管理版本。鸿蒙相关开源工程大概率在 GitCode/GitHub 上，不装 Git 后面寸步难行。
JDK 17
DevEco Studio + OpenHarmony 工具链对 Java 版本有要求。文章明确用 JDK17，版本低了会让 Gradle/构建链报奇怪错误。
Flutter SDK
Flutter 本体与 Dart 环境必须是可用状态，否则 hap 构建时依赖解析和本地引擎都过不去。

实战建议：三件套全部装在非 C 盘路径，且路径不要带中文/空格。很多构建坑都来自路径权限或字符异常。

2.2 DevEco Studio 安装（6.0.0 Release）

DevEco Studio 是鸿蒙端的主要 IDE，相当于 Android 的 Android Studio。安装过程按默认步骤走即可，但作者给了一个极其有用的工程化建议：

先手动建好统一目录结构，例如：

HarmonyOS/ ArkUI-X/ Sdk/ Emulator/ deployed/ OpenHarmony/ Sdk/

这样后面你装 SDK、装 ArkUI-X、装 Emulator 时都能指向同一父目录，避免“装哪了找不到、多个版本混在一起”的混乱。

3. DevEco Studio 内配置 OpenHarmony

3.1 安装 OpenHarmony SDK

DevEco → Settings → OpenHarmony SDK
选择你建好的 OpenHarmony/Sdk 路径 → 同意协议 → Next 下载。
装完后 IDE 会自动识别可用的平台版本（API）。

3.2 安装 ArkUI-X

Settings → ArkUI-X
选择 ArkUI-X/Sdk → 下载并配置。
ArkUI-X 是 Flutter 与鸿蒙侧桥接的一块关键能力，有它才能做跨端 UI 与系统能力对接。

3.3 配置 Emulator（模拟器）

Device Manager → 下载 Emulator 组件
安装路径选 Emulator/
New Emulator → 下载镜像 → Run
第一次启动慢，是因为要初始化系统镜像和模拟设备环境，这一步别慌。

到这里，Day1-3 的目标就达成了：IDE 能识别 OpenHarmony SDK、ArkUI-X、模拟器能跑起来，链路前置准备完成。

4. GitCode 口袋工具跑通（Day4-6）

4.1 拉工程并打开

从仓库下载 gitcode_pocket_tool，解压后用 DevEco Studio 打开 ohos 工程。
这一段的意义是：你不是在跑 HelloWorld，而是在跑一个真实社区项目。

4.2 配 GitCode Token

这个项目需要 GitCode API 访问令牌，否则只会停留在 UI 不能用的状态。
在 GitCode 里创建 classic token：

设置名字、过期时间
创建后立刻复制保存（只显示一次）
按项目说明写入常量/配置文件

5. 最高频的坑位复盘（建议收藏）

5.1 SDK / API 版本不匹配

表现：IDE 提示你设置 compatibleSdkVersion / targetSdkVersion，或构建直接失败。
原因：工程默认 API 版本与你本地 SDK 版本不同。

解决：手动把工程版本改成与你本机 SDK/模拟器一致的版本。
例如文章里模拟器 API 是 20，而工程默认是 18，那就把版本提升到 20 再 Try again。

5.2 别人项目签名信息残留

表现：Signing Configs 里带着作者自己的 debug 签名，导致你本机签名体系不匹配。
解决：删掉旧签名，让 DevEco 自动生成你的签名。

路径：Project Structure → Signing Configs
删除旧 debug 配置 → Try again → 自动生成新签名。

5.3 Flutter 依赖未完整拉取

表现：工程爆红，提示插件或 Dart 依赖找不到。
解决：在工程根目录执行：

flutter build hap

然后回到 DevEco 勾选自动签名：

File → Project Structure → Signing Configs
→ Automatically generate signature。

5.4 Project Structure 界面卡住

表现：打开签名设置一直转圈/空白。
解决：清 IDE 缓存：

File → Invalidate Caches
→ 勾 Delete embedded browser engine cache and cookies
→ 重启 IDE。

5.5 内置终端路径/权限异常

表现：DevEco 内置终端执行 flutter build hap 报错。
解决：直接用系统 cmd/PowerShell，确保当前目录在项目根下再执行。

6. 结语

Day1-6 的真正价值不是记住多少按钮在哪，而是建立一条可复用、可迁移的 Flutter → OpenHarmony 编译运行链路。当你看到 Run 变绿、模拟器成功显示页面时，说明你的“鸿蒙 Flutter 基座”已经搭好。
之后无论是做自定义组件库、插件鸿蒙化、还是迁移一个中大型 Flutter App，这里踩过的坑和对齐思路都会反复用到。