Flutter 编译开发 OpenHarmony 全流程实战教程（基于 GitCode 社区项目）

在这里插入图片描述

• 个人首页： VON
• 鸿蒙系列专栏： 鸿蒙开发小型案例总结
• 综合案例 ：鸿蒙综合案例开发
• 鸿蒙6.0：从0开始的开源鸿蒙6.0.0
• 鸿蒙5.0：鸿蒙5.0零基础入门到项目实战
• Electron适配开源鸿蒙专栏：Electron for OpenHarmony
• 本文章所属专栏：Flutter for OpenHarmony

前言

作者：●VON 适用版本：HarmonyOS 6 / DevEco Studio 5.0+ / flutter_harmony 社区方案 v1.0.0 更新时间：2025 年 11 月 参考文档：【2025版 OpenHarmony】 GitCode 口袋工具：Flutter + Dio 网路请求 打造随身的鸿蒙版 GitCode 搜索助手

本文将手把手带你从 零开始配置并运行一个 Flutter + OpenHarmony 的混合项目，全程基于 GitCode 上开源的社区示例（如 pocket_tool-v1.0.0），解决“找不到插件”等典型问题，助你一次性跑通！

一、下载项目压缩包

为确保环境一致性，建议直接使用 稳定版本的项目压缩包（而非 git clone），避免分支变动导致兼容性问题。

👉 本文采用的是 v1.0.0 版本 的社区示例项目：

下载项目压缩包

💡 提示：可在 GitCode 项目 Release 页面或博主分享链接中获取该压缩包。 也可以直接去下载：压缩包

二、配置 GitCode 访问令牌（Token）

由于项目依赖私有或受保护的仓库（如 flutter_flutter），需配置 GitCode Personal Access Token 才能拉取依赖。

步骤 1：创建令牌

1. 访问 GitCode 令牌管理页
2. 点击 “新建令牌”
3. 勾选权限：read_repository（读取代码库）
4. 设置令牌名称（如 harmony_flutter_token）
5. 点击 “创建”

创建令牌

令牌权限设置

步骤 2：复制令牌

创建成功后，立即复制生成的令牌字符串（只显示一次！）：

复制令牌

三、在项目中配置令牌

1. 解压项目

将下载的 gitcode_pocket_tool-v1.0.0.zip 解压到本地目录，例如：

C:\Users\wxj05\Desktop\gitcode_pocket_tool-v1.0.0

解压项目

2. 配置 .dart

用 VS Code 打开项目根目录：

用 VS Code 打开

找到配置文件，填入你的令牌：

# .ohpmrc 示例
registry=https://gitcode.com/api/v4/packages/ohpm
//gitcode.com/:_authToken=your_copied_token_here

配置令牌位置

✅ 替换 your_copied_token_here 为你刚复制的完整令牌。

四、解决“找不到 flutter-hvigor-plugin”问题

首次用 DevEco Studio 打开项目时，大概率会报错：

Cannot find module 'flutter-hvigor-plugin'

别慌！这是因插件未安装导致的。

✅ 正确做法：在项目根目录执行依赖安装

1. 打开终端（Terminal），进入 项目根目录（即包含 ohos/ 和 flutter/ 的目录）
2. 执行：

flutter pub get

⚠️ 注意：此处的 flutter 必须是 项目自带的鸿蒙定制版 SDK（通常在 flutter/bin/flutter），建议使用完整路径或先配置 PATH。

执行 flutter pub get

该命令会：

• 拉取 flutter_hvigor_plugin
• 安装 Dart 依赖
• 生成必要的桥接文件

✅ 执行成功后，ohos/hvigorconfig.ts 就能正确识别插件了！

五、关键配置：统一 API 版本号

社区项目默认版本可能与你的 DevEco Studio 不匹配，需手动调整。

1. 查看当前编译器版本

在 DevEco Studio 中：

File → Settings → HarmonyOS SDK

记录 Compile SDK Version，例如 6.0.0 (20)。

2. 修改配置文件

全局搜索 5.0.0 或旧版本号，替换为你的实际版本（如 6.0.0），主要修改：

• ohos/build-profile.json5
• ohos/module.json5
• oh-package.json5

修改版本号

六、自动配置签名（可选但推荐）

为方便调试，可让 DevEco Studio 自动生成调试签名：

1. 点击菜单：File → Project Structure → Project
2. 在 Signing Configs 中点击 “Auto Generate”
3. 系统将自动创建 .p12、.csr 等文件

自动配置签名

🔐 此签名仅用于本地调试，上架需使用正式证书。

七、运行项目（模拟器 or 真机）

一切就绪后：

1. 启动 HarmonyOS 模拟器（或连接真机）
2. 在 DevEco Studio 中点击 ▶ Run
3. 等待构建完成

🎉 成功运行效果如下：

成功运行

你已成功在 HarmonyOS 6 上运行了一个 Flutter 应用！

八、常见问题总结

结语

虽然 Flutter on OpenHarmony 仍是社区驱动方案，但通过本文的标准化流程，你已掌握从 下载 → 配置 → 修复 → 运行 的完整链路。

🌟 技术的价值，不在于它是否官方，而在于你能否让它为你所用。

祝你开发顺利！如有疑问，欢迎交流 👇