-
个人首页： VON
-
鸿蒙系列专栏： 鸿蒙开发小型案例总结
-
综合案例 ：鸿蒙综合案例开发
-
鸿蒙6.0：从0开始的开源鸿蒙6.0.0
-
鸿蒙5.0：鸿蒙5.0零基础入门到项目实战
-
Electron适配开源鸿蒙专栏：Electron for OpenHarmony
-
本文章所属专栏：Flutter for OpenHarmony
Flutter 编译开发 OpenHarmony 全流程实战教程（基于 GitCode 社区项目）
-
- 前言
- 一、下载项目压缩包
- [二、配置 GitCode 访问令牌（Token）](#二、配置 GitCode 访问令牌（Token）)
-
- [步骤 1：创建令牌](#步骤 1：创建令牌)
- [步骤 2：复制令牌](#步骤 2：复制令牌)
- 三、在项目中配置令牌
-
- [1. 解压项目](#1. 解压项目)
- [2. 配置 `.dart`](#2. 配置
.dart)
- [四、解决"找不到 flutter-hvigor-plugin"问题](#四、解决“找不到 flutter-hvigor-plugin”问题)
-
- [✅ 正确做法：在项目根目录执行依赖安装](#✅ 正确做法：在项目根目录执行依赖安装)
- [五、关键配置：统一 API 版本号](#五、关键配置：统一 API 版本号)
-
- [1. 查看当前编译器版本](#1. 查看当前编译器版本)
- [2. 修改配置文件](#2. 修改配置文件)
- 六、自动配置签名（可选但推荐）
- [七、运行项目（模拟器 or 真机）](#七、运行项目（模拟器 or 真机）)
- 八、常见问题总结
- 结语
前言
作者：●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：创建令牌
- 访问 GitCode 令牌管理页
- 点击 "新建令牌"
- 勾选权限：
read_repository（读取代码库） - 设置令牌名称（如
harmony_flutter_token） - 点击 "创建"
步骤 2：复制令牌
创建成功后，立即复制生成的令牌字符串（只显示一次！）：
三、在项目中配置令牌
1. 解压项目
将下载的 gitcode_pocket_tool-v1.0.0.zip 解压到本地目录，例如：
C:\Users\wxj05\Desktop\gitcode_pocket_tool-v1.0.0
2. 配置 .dart
用 VS Code 打开项目根目录：
找到配置文件，填入你的令牌：
ini
# .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'别慌！这是因插件未安装导致的。
✅ 正确做法：在项目根目录执行依赖安装
- 打开终端（Terminal），进入 项目根目录 （即包含
ohos/和flutter/的目录） - 执行：
bash
flutter pub get⚠️ 注意：此处的
flutter必须是 项目自带的鸿蒙定制版 SDK （通常在flutter/bin/flutter），建议使用完整路径或先配置 PATH。
该命令会：
- 拉取
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.json5ohos/module.json5oh-package.json5
六、自动配置签名（可选但推荐）
为方便调试，可让 DevEco Studio 自动生成调试签名：
- 点击菜单：File → Project Structure → Project
- 在 Signing Configs 中点击 "Auto Generate"
- 系统将自动创建
.p12、.csr等文件
🔐 此签名仅用于本地调试，上架需使用正式证书。
七、运行项目（模拟器 or 真机）
一切就绪后：
- 启动 HarmonyOS 模拟器（或连接真机）
- 在 DevEco Studio 中点击 ▶ Run
- 等待构建完成
🎉 成功运行效果如下：
你已成功在 HarmonyOS 6 上运行了一个 Flutter 应用！
八、常见问题总结
| 问题 | 解决方案 |
|---|---|
Cannot find module 'flutter-hvigor-plugin' |
执行 flutter pub get 安装插件 |
| 依赖拉取失败 | 检查 .ohpmrc 中的 token 是否正确 |
| 构建版本不匹配 | 统一修改所有配置文件中的 API 版本为 6.0.0 |
| hdc 无法识别设备 | 确保 toolchains 路径已加入系统 PATH |
结语
虽然 Flutter on OpenHarmony 仍是社区驱动方案，但通过本文的标准化流程，你已掌握从 下载 → 配置 → 修复 → 运行 的完整链路。
🌟 技术的价值，不在于它是否官方，而在于你能否让它为你所用。
祝你开发顺利！如有疑问，欢迎交流 👇