✨“俺はモンキー・D・ルフィ。海贼王になる男だ！”

---

前言

随着 OpenHarmony 生态的快速发展，越来越多的开发者开始关注鸿蒙应用开发。本文将详细介绍在 Windows 11 系统上搭建 Flutter OpenHarmony 开发环境的完整流程，以及解决常见问题的方法。

注意：本文适用于 Windows 11 系统，其他操作系统可能需要调整部分步骤。

---

一、开发环境概览

在开始之前，我们需要准备以下开发工具：

工具	用途	下载地址
DevEco Studio	鸿蒙官方IDE	developer.huawei.com
Flutter SDK	Flutter开发框架	flutter.dev
Git	版本控制工具	git-scm.com
Node.js	JavaScript运行时	DevEco内置

---

二、环境配置步骤

步骤1：安装 DevEco Studio

DevEco Studio 是华为推出的鸿蒙应用开发 IDE，基于 IntelliJ IDEA 定制。

1. 访问华为开发者联盟下载 DevEco Studio
2. 运行安装程序，选择安装路径
3. 安装完成后启动，进行初始化配置

步骤2：安装 Flutter SDK

1. 下载 Windows 版本的 Flutter SDK 压缩包
2. 解压到指定目录，例如 C:\flutter
3. 配置环境变量：
   • 新建系统变量 FLUTTER_HOME，值为 Flutter 安装路径
   • 在 Path 中添加 %FLUTTER_HOME%\bin

步骤3：配置 Git

1. 下载 Git for Windows 安装包
2. 运行安装程序，使用默认配置即可
3. 安装完成后验证：打开命令行输入 git --version

步骤4：安装 DevEco Studio SDK

1. 启动 DevEco Studio
2. 进入 Settings → Appearance & Behavior → System Settings → HarmonyOS SDK
3. 安装以下组件：
   • SDK（API 9 或以上）
   • Node.js（推荐使用 DevEco 内置版本）
   • Hvigor（构建工具）

---

三、常见问题与解决方案

问题 1：flutter doctor 找不到 Android SDK

现象

[!] Android toolchain - develop for Android devices
    ✗ Unable to locate Android SDK.

原因分析

Flutter 需要 Android SDK 来构建 Android 平台的应用，即使你的目标是 OpenHarmony，Flutter 仍需要 Android SDK。

解决方案

1. 安装 Android Studio
2. 打开 Android Studio → Settings → Languages & Frameworks → Android SDK
3. 记录 SDK 路径（通常是 C:\Users\用户名\AppData\Local\Android\Sdk）

注意：我自己安装在了e盘

5. 配置环境变量：

   • 新建变量 ANDROID_HOME，值为 SDK 路径
   • 在 Path 中添加：
     • %ANDROID_HOME%\platform-tools
     • %ANDROID_HOME%\tools

6. 重要：关闭所有命令行窗口，重新打开验证

---

问题 2：提示缺少 cmdline-tools

现象

✗ cmdline-tools component is missing

解决方案

1. 打开 Android Studio
2. 进入 File → Settings → Languages & Frameworks → Android SDK
3. 切换到 SDK Tools 标签页
4. 勾选 Android SDK Command-line Tools (latest)
5. 点击 Apply 或 OK 进行安装

---

问题 3：Android 许可协议未接受

现象

✗ Some Android licenses not accepted. To resolve this, run:
  flutter doctor --android-licenses

解决方案

在命令行执行：

flutter doctor --android-licenses

然后依次输入 y 并回车，接受所有许可协议。

---

问题 4：pub 下载失败或速度慢

现象

• flutter pub get 下载依赖时卡住或失败
• 下载速度非常慢

原因分析

默认情况下，Flutter 从 Google 服务器下载资源，国内访问可能不稳定。

解决方案（三种方法）

方法一：清理缓存

# 删除缓存目录后重试
rmdir /s /q %FLUTTER_HOME%\bin\cache
flutter pub get

方法二：使用国内镜像

在环境变量中添加：

PUB_HOSTED_URL=https://pub.flutter-io.cn
FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn

方法三：切换回官方源

如果镜像也有问题，可以切换回官方源：

PUB_HOSTED_URL=https://pub.dev
FLUTTER_STORAGE_BASE_URL=https://storage.googleapis.com

---

问题 5：Node.js 版本冲突

现象

Error: Node.js version mismatch. Expected: xx.x.x, Actual: yy.y.y

原因分析

系统安装的 Node.js 版本与 DevEco Studio 要求的版本不一致。

解决方案

1. 打开环境变量设置

2. 在 Path 中，确保 DevEco 内置 Node.js 路径在最前面：

   %TOOL_HOME%\tools\node
   

3. 移除或注释掉其他 Node.js 路径

4. 验证版本：

node --version

个人建议：开发 OpenHarmony 应用时，优先使用 DevEco 内置的 Node.js，避免版本冲突。

---

问题 6：flutter 命令找不到

现象

'flutter' 不是内部或外部命令，也不是可运行的程序

排查步骤

1. 确认环境变量配置正确

   • 检查 FLUTTER_HOME 变量是否存在
   • 检查 Path 中是否包含 %FLUTTER_HOME%\bin

2. 使用完整路径测试

C:\flutter\bin\flutter --version

如果完整路径可以执行，说明是环境变量配置问题。

3. 重启命令行和系统

   配置环境变量后，必须：

   • 关闭所有命令行窗口
   • 重新打开命令行
   • 如果还不行，重启电脑

---

问题 7：环境变量配置不生效

现象

明明配置了环境变量，但在命令行中仍然找不到。

核心原因

Windows 环境变量只在新的进程中生效，已打开的命令行窗口不会自动加载新的配置。

解决方案

1. 彻底关闭所有命令行窗口（包括 PowerShell、CMD）
2. 重新打开命令行
3. 如果还不生效，重启电脑

经验总结：这是新手最容易犯的错误 —— 配置完环境变量后忘记重启命令行。

---

问题 8：模拟器启动失败

现象

• DevEco Studio 模拟器无法启动
• 启动后黑屏或闪退

排查与解决

1. 检查 BIOS 虚拟化设置

   • 重启电脑进入 BIOS
   • 启用 VT-x（Intel）或 AMD-V（AMD）
   • 保存并退出

2. 检查磁盘空间

   确保至少有 5GB 可用空间。

3. 查看模拟器日志

   在 DevEco Studio 中查看模拟器日志，定位具体错误。

4. 重建模拟器

   删除现有模拟器，重新创建。

---

问题 9：应用签名失败

现象

打包 HAP 文件时提示签名失败。

解决方案

1. 确认华为开发者账号状态

   • 账号必须完成实名认证
   • 登录状态正常

2. 检查网络连接

   签名过程需要联网验证。

3. 重新登录账号

   在 DevEco Studio 中退出登录，重新登录。

4. 检查签名配置

   确保项目中的签名文件配置正确。

---

问题 10：编译 HAP 包失败

现象

Execution failed for task ':ohos:compileHap'.

排查步骤

1. 查看详细错误信息

   错误日志中会包含具体失败原因。

2. 检查环境变量配置

   确保所有必要的环境变量都正确配置。

3. 清理构建缓存

flutter clean
flutter pub get
flutter build hap --debug

4. 检查项目配置

   • pubspec.yaml 依赖是否正确
   • build.gradle 配置是否正确

5. 检查 DevEco SDK

   确保 SDK 完整安装，没有缺失组件。

---

四、验证环境配置

完成所有配置后，运行以下命令验证：

flutter doctor -v

确保所有检查项都显示绿色对勾（OpenHarmony 相关项可以有警告）。

---

五、创建第一个项目

1. 创建 Flutter 项目：

flutter create hello_harmony
cd hello_harmony

2. 添加 OpenHarmony 依赖：

flutter pub add flutter鸿蒙依赖

3. 运行到模拟器：

flutter run -d harmony

---

六、个人经验总结

开发心得

经过一段时间的 Flutter OpenHarmony 开发，我总结出以下经验：

1. 环境变量是基础：90% 的问题都与环境变量配置有关
2. 重启是万能钥匙：配置改变后，记得重启命令行
3. 查看错误日志：不要盲目尝试，先看错误信息
4. 使用国内镜像：大幅提升依赖下载速度

推荐工具

工具	用途
DevEco Studio	鸿蒙开发必备
Windows Terminal	更好的命令行体验
PowerToys	增强 Windows 功能

学习资源

• Flutter 官方文档
• OpenHarmony 官方文档
• 鸿蒙开发者社区

---

结语

搭建 Flutter OpenHarmony 开发环境虽然步骤较多，但只要按照本文的步骤逐一配置，遇到问题参考解决方案，就能顺利完成。

记住：遇到问题不要慌，大多数问题都有解决方案。多查看错误信息，多尝试，多搜索，很快你就能熟练掌握 Flutter OpenHarmony 开发！

如果你在搭建过程中遇到其他问题，欢迎在评论区交流讨论。