Mac 版 Flutter 鸿蒙 3.35 环境搭建指南：从 DevEco Studio 到 doctor 验证

很多人第一次在 Mac 上搭 Flutter 鸿蒙环境，卡住的地方并不是 Dart 语法，而是第一步工具链就没有选对：Mac 是 arm64 还是 x86_64，DevEco Studio 装在哪里，Flutter 用普通版本还是鸿蒙适配分支，~/.zshrc 里到底该配哪些路径。只要其中一个环节错了，后面 flutter doctor -v 就会出现一堆看起来像 Flutter 问题、实际是环境路径问题的警告。

本文基于 GitCode 的“鸿蒙版 Flutter 环境 3.35 版本搭建指南”整理。需要提前说明一点：原始文件名是 3.35 版本搭建指南，但文档正文标题写了 3.32，具体命令又切到了 3.35.7-dev 分支。为了避免误导，本文按实际命令链路来讲，也就是 Mac 版鸿蒙 Flutter 3.35.7-dev 环境。

读完后你能完成这几件事：

1. 判断自己的 Mac 架构，避免下载错开发套件。
2. 安装 DevEco Studio，并记录真实安装路径。
3. 拉取鸿蒙版 Flutter 仓库并切到 3.35.7-dev 相关分支。
4. 配置 zsh 环境变量，让 ohpm、hvigor、node、flutter 都能在终端里被找到。
5. 读懂 flutter doctor -v 里的正常警告和真正需要处理的问题。

1. 先确认这篇教程适合什么环境

这篇文章写的是 Mac 环境，不是 Windows 环境。原文也说明 Flutter 鸿蒙适配目前可以在 Linux、Mac、Windows 下使用，但它的示例路径、终端配置和架构判断都是 Mac 写法。

项目	本文采用的写法	说明
操作系统	macOS	示例路径以 /Applications 和 /Users 开头
Shell	zsh 优先	新版 macOS 默认一般是 zsh
IDE	DevEco Studio 6.x	原文演示版本为 6.0.2 Release
Flutter	鸿蒙适配分支	不使用普通 Flutter SDK 直接替代
验证命令	flutter doctor -v	重点看 HarmonyOS toolchain

先在终端确认 Mac 架构：

uname -m

代码解释：

1. 输出 arm64，通常是 Apple Silicon 芯片，例如 M1、M2、M3、M4。
2. 输出 x86_64，通常是 Intel Mac。
3. 下载 DevEco Studio 或其他工具时，要选择和当前架构匹配的安装包。

2. 安装 DevEco Studio 并记录路径

DevEco Studio 是鸿蒙开发套件入口。原文给出的官方下载地址是华为开发者下载页：

https://developer.huawei.com/consumer/cn/download/

原文演示的版本信息如下：

DevEco Studio 6.0.2 Release
Build: 6.0.2.640
Runtime: 21.0.8+9-b1038.71
macOS: 15.2

代码解释：

1. 这里的版本是原文演示环境，不代表你需要安装完全相同的小版本。
2. 更稳的做法是使用华为官方下载页提供的当前稳定套件。
3. 安装完成后要记录 DevEco Studio 实际路径，后面 TOOL_HOME 会用到。

Mac 上常见安装路径是：

/Applications/DevEco-Studio.app/Contents

可以用下面命令确认目录是否存在：

ls /Applications/DevEco-Studio.app/Contents

代码解释：

1. 能看到 tools、jbr、plugins 等目录，说明 DevEco Studio 根路径基本正确。
2. 如果应用名或安装目录不一样，后续环境变量不能照抄，要按实际路径修改。
3. 如果首次启动 DevEco Studio 时提示下载 SDK 组件，先让 IDE 完成组件安装。

3. 拉取鸿蒙版 Flutter 仓库

Flutter 鸿蒙环境最重要的点是不要拿普通 Flutter SDK 直接替代鸿蒙适配版。原文给出的仓库地址是：

https://gitcode.com/openharmony-tpc/flutter_flutter

拉取仓库：

mkdir -p ~/harmony/flutter
cd ~/harmony/flutter
git clone https://gitcode.com/openharmony-tpc/flutter_flutter
cd flutter_flutter

代码解释：

1. ~/harmony/flutter 只是示例目录，可以换成你自己的开发目录。
2. 仓库体积较大，网络不稳定时建议保持终端不要中断。
3. 克隆完成后不要马上创建项目，先切分支并确认版本。

原文中的分支命令是：

git checkout -b h-3.35.7-dev origin/3.35.7-dev

代码解释：

1. origin/3.35.7-dev 是远端分支。
2. h-3.35.7-dev 是本地新建分支名，可以理解为本地工作分支。
3. 如果远端分支名变化，以仓库当前分支列表和 README 为准。

更谨慎的做法是先看远端分支：

git branch -r | grep 3.35

代码解释：

1. 这一步可以确认远端到底有没有 3.35.7-dev。
2. 如果仓库维护方调整了分支名，直接照抄旧命令会失败。
3. 分支确认后再执行 git checkout，错误更少。

4. 先用完整路径确认 Flutter 版本

切好分支以后，先不要依赖 PATH，直接用仓库内的 flutter 命令确认版本。

./bin/flutter --version

代码解释：

1. ./bin/flutter 指向当前仓库内的 Flutter，不受系统 PATH 影响。
2. 版本输出中如果能看到 ohos、ohos beta 或鸿蒙适配相关信息，说明方向基本正确。
3. 如果这里都不能运行，先处理仓库下载、分支和执行权限，不要急着改环境变量。

必要时给脚本执行权限：

chmod +x ./bin/flutter

代码解释：

1. macOS 上从某些渠道解压或同步文件后，脚本权限可能不完整。
2. Git clone 正常情况下通常不需要这一步，但遇到 permission 问题时可以排查。

5. 选择 zsh 配置文件

Mac 默认 Shell 通常是 zsh，所以原文推荐编辑 ~/.zshrc。

open ~/.zshrc

如果文件不存在，可以用终端编辑：

nano ~/.zshrc

代码解释：

1. open ~/.zshrc 会用默认编辑器打开配置文件。
2. nano ~/.zshrc 适合直接在终端里编辑。
3. 如果你使用 bash，再改 ~/.bash_profile，不要两个文件乱写导致自己不知道哪个生效。

确认当前 Shell：

echo $SHELL

代码解释：

1. 输出包含 /zsh，优先改 ~/.zshrc。
2. 输出包含 /bash，优先改 ~/.bash_profile。
3. 改错文件后，变量不会在新终端里生效。

6. 配置 DevEco Studio 与构建工具路径

下面是按原文整理后的 Mac zsh 配置。路径要按你的机器改，尤其是 TOOL_HOME 和 Flutter 路径。

export TOOL_HOME=/Applications/DevEco-Studio.app/Contents
export DEVECO_SDK_HOME=$TOOL_HOME/sdk

export PATH=$TOOL_HOME/tools/ohpm/bin:$PATH
export PATH=$TOOL_HOME/tools/hvigor/bin:$PATH
export PATH=$TOOL_HOME/tools/node/bin:$PATH

代码解释：

1. TOOL_HOME 指向 DevEco Studio 的 Contents 目录。
2. ohpm 负责鸿蒙包管理相关能力。
3. hvigor 是鸿蒙构建链路里的重要工具。
4. node 是 DevEco Studio 套件内置工具链的一部分，优先使用套件内路径更稳。

配置后可以确认命令是否能找到：

which ohpm
which hvigor
which node

代码解释：

1. which 输出应指向 DevEco Studio 的 tools 目录。
2. 如果输出为空，说明 PATH 没生效或 TOOL_HOME 写错。
3. 如果输出指向其他旧版本工具，要注意 PATH 顺序。

7. 配置 Flutter 路径与下载镜像

把鸿蒙版 Flutter 加入 PATH。下面路径来自示例，实际要换成你自己的仓库位置。

export PATH=$HOME/harmony/flutter/flutter_flutter/bin:$PATH

代码解释：

1. 这行要放在普通 Flutter SDK 路径前面。
2. 如果系统里装过多个 Flutter，PATH 顺序会直接影响 flutter 命中的版本。
3. 配置后用 which flutter 确认命中路径。

国内网络环境下，可以配置 Pub 和 Flutter 下载镜像：

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

代码解释：

1. PUB_HOSTED_URL 影响 Dart/Flutter 依赖包下载。
2. FLUTTER_STORAGE_BASE_URL 影响 Flutter 相关资源下载。
3. 如果团队有内部镜像，应优先使用团队规定的镜像地址。

为减少仓库来源警告，可以配置：

export FLUTTER_GIT_URL=git@gitcode.com:openharmony-tpc/flutter_flutter.git

代码解释：

1. 这个变量用于告诉 Flutter 当前上游仓库来源。
2. 原文中 doctor 输出里能看到 FLUTTER_GIT_URL 被识别。
3. 如果你用 HTTPS clone，也可以按团队实际仓库地址调整。

8. 刷新配置并确认命令命中

写完 ~/.zshrc 后，执行：

source ~/.zshrc

如果你改的是 bash 配置：

source ~/.bash_profile

代码解释：

1. source 会让当前终端立即加载新配置。
2. 如果你不执行 source，也可以重新打开一个终端窗口。
3. 改完变量后不要只看文件内容，要看终端实际命中的命令。

建议连续确认：

which flutter
flutter --version
which hvigor
which ohpm
which node

代码解释：

1. which flutter 应指向鸿蒙版 Flutter 仓库的 bin/flutter。
2. flutter --version 用来确认当前 Flutter 版本和分支。
3. hvigor、ohpm、node 应能正常找到。

9. 运行 flutter doctor -v

环境变量配置完成后，执行：

flutter doctor -v

代码解释：

1. 这一步不是看所有项目都必须打勾，而是重点看 HarmonyOS toolchain 是否可用。
2. 如果只开发鸿蒙，Android、iOS、Xcode 的一些提示可以按需处理。
3. Flutter channel 显示 unknown 或 user-branch，在鸿蒙定制版本里不一定是致命问题。

原文 doctor 输出里的关键判断点是：

[✓] HarmonyOS toolchain - develop for HarmonyOS devices
OpenHarmony Sdk at /Users/jianguo/Library/OpenHarmony/Sdk, available api versions has [20:20]
Ohpm version 6.0.1
Node version v23.11.0
Hvigorw binary at /Applications/DevEco-Studio.app/Contents/tools/hvigor/bin/hvigorw

代码解释：

1. [✓] HarmonyOS toolchain 是最关键的成功信号。
2. OpenHarmony Sdk 路径要指向当前用户真实 SDK 位置。
3. Ohpm、Node、Hvigorw 能被识别，说明 DevEco 工具链路径基本通了。
4. API 版本显示 [20:20] 是原文环境结果，实际以你本机 SDK 安装版本为准。

10. 正常警告和需要处理的问题分开看

doctor 输出不一定全是绿色才代表鸿蒙环境不能用。要分清“鸿蒙链路问题”和“可选平台问题”。

doctor 项	如何判断	处理建议
HarmonyOS toolchain	必须重点关注	这里失败要优先修 DevEco、SDK、PATH
Flutter channel	定制分支可能提示 unknown	只要来源和版本正确，可先继续
Git repository	可由 FLUTTER_GIT_URL 缓解	按仓库地址配置变量
Android toolchain	只做鸿蒙可暂不处理	需要 Android 再装 Android Studio
Xcode	只做鸿蒙可暂不处理	需要 iOS/macOS 再配置
Chrome / VS Code	辅助开发能力	不影响鸿蒙工具链主链路

如果看到 Git repository 相关提示，可以补充：

export FLUTTER_GIT_URL=git@gitcode.com:openharmony-tpc/flutter_flutter.git
source ~/.zshrc
flutter doctor -v

代码解释：

1. 第一行设置 Flutter 上游仓库地址。
2. 第二行让当前终端生效。
3. 第三行重新查看 doctor 输出是否还提示仓库来源问题。

11. 可选的 Android 和 iOS 配置不要混进主链路

原文里也提到 Android 和 iOS 是可选项。如果你只做鸿蒙 Flutter，先不要因为 Android 或 Xcode 警告打乱主线。

需要 Android 时再配置：

flutter config --android-sdk /Users/你的用户名/Library/Android/sdk
flutter doctor --android-licenses

代码解释：

1. flutter config --android-sdk 指定 Android SDK 路径。
2. flutter doctor --android-licenses 用于接受 Android 许可证。
3. 这两步服务于 Android 目标，不是鸿蒙工具链通过的必要条件。

需要 iOS 时再配置：

sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -runFirstLaunch
sudo gem install cocoapods

代码解释：

1. xcode-select 指定 Xcode 开发者目录。
2. xcodebuild -runFirstLaunch 完成首次启动配置。
3. cocoapods 主要服务 iOS 插件依赖管理。

12. 最终验证清单

发布项目或创建第一个鸿蒙 Flutter 工程前，建议按这个清单走一遍：

1. uname -m 已确认 Mac 架构。
2. DevEco Studio 已安装，并能打开。
3. TOOL_HOME 指向真实 DevEco Studio Contents 目录。
4. which ohpm 能找到 DevEco Studio 下的 ohpm。
5. which hvigor 能找到 DevEco Studio 下的 hvigor。
6. which node 能找到 DevEco Studio 下的 node。
7. which flutter 指向鸿蒙版 Flutter 仓库。
8. flutter --version 输出符合鸿蒙适配版本预期。
9. FLUTTER_GIT_URL 指向当前使用的鸿蒙 Flutter 仓库。
10. flutter doctor -v 中 HarmonyOS toolchain 为可用状态。
11. Android 和 iOS 提示已按实际需求判断，不和鸿蒙主链路混在一起。
12. 所有示例路径都已替换为自己机器上的真实路径。

13. 总结

Mac 版 Flutter 鸿蒙环境搭建的核心不是把别人机器上的路径完整复制过来，而是按顺序确认四件事：Mac 架构是否匹配、DevEco Studio 是否安装完整、Flutter 是否切到鸿蒙适配分支、终端是否能找到 ohpm、hvigor、node 和 flutter。最后再用 flutter doctor -v 查看 HarmonyOS toolchain 状态。

如果 doctor 里 HarmonyOS toolchain 已经可用，Flutter 版本也指向鸿蒙适配分支，就可以继续创建鸿蒙 Flutter 项目、连接设备或模拟器，再进入实际应用开发。

参考出处

本文参考并整理自 GitCode / Atom Flutter 文档：

https://gitcode.com/atom-flutter/docs/blob/main/环境搭建/鸿蒙版Flutter环境3.35版本搭建指南.md

原文说明由 GitCode 深圳团队出品。本文在整理时保留了 Mac 版搭建主线，并对文件名、正文标题和实际分支命令之间的版本差异做了说明。