【Flutter×鸿蒙】通关手册（一）：一个"插队"技巧，解决90%的 command not found

TT_Close
22 阅读8分钟

系列导航：

搞 Flutter 鸿蒙开发，第一步不是写代码，而是搭环境。我第一次配的时候，ohpm command not found 报了 5 次，最后发现核心就是一个字——"抢"：让鸿蒙工具在系统 PATH 里排到最前面。这篇把环境搭建拆成 4 关，照做一次过。

🗺️ 通关路线图

关卡任务预计耗时
第 1 关下载安装 DevEco Studio5-10 min
第 2 关安装 SDK 组件5-15 min（看网速）
第 3 关配置环境变量（最关键）5 min
第 4 关补齐 JDK 17 + 全面验证3 min

总共 4 关，顺利的话半小时内搞定。下面逐关击破。

🎯 第 1 关：下载安装 DevEco Studio

目标：电脑上装好鸿蒙的官方 IDE（类似 Android Studio）。

📋 操作

下载地址：developer.huawei.com/consumer/cn…

根据你的系统选择对应的安装包：

  • macOS：区分 Apple Silicon（M1/M2/M3/M4）和 Intel 芯片。下错了也能用，但性能差很多——Apple Silicon 的芯片跑 Intel 版需要走 Rosetta 转译，编译速度会慢一大截。
  • Windows：下 .exe 安装包。安装路径不要有中文或空格，否则后面工具链解析路径时可能出幺蛾子。

⚠️ macOS 首次打开可能提示"无法验证开发者"。解决办法：去 系统设置 → 隐私与安全性，找到被拦截的提示，点「仍要打开」即可。

✅ 验证

能正常打开 DevEco Studio，看到欢迎界面，就过关了。

01_deveco_welcome.png

如果不对：macOS 上双击没反应，大概率是被 Gatekeeper 拦了，按上面的方法去「隐私与安全性」里放行。Windows 上如果闪退，检查安装路径是否包含中文或空格。

🎯 第 2 关：安装 SDK 组件

目标：装好 HarmonyOS SDK 和工具链。

📋 操作

首次启动 DevEco Studio 会弹出安装引导向导，跟着走就行，但有两个地方要注意：

1. SDK 路径保持默认

  • macOS：/Users/你的用户名/Library/Huawei/Sdk
  • Windows：C:\Users\你的用户名\AppData\Local\Huawei\Sdk

保持默认路径的好处是：后续很多工具和文档都默认读这个位置，改了反而要到处补配置。

2. 组件检查

在向导或设置页面中：

  • HarmonyOS SDK：新版 IDE 可能提示“已包含在 IDE 中，无需单独安装”，这是正常的（如左图）。
  • OpenHarmony SDK：建议检查并安装最新的 API Version（如 API 20+），且必须确保 Toolchains 已勾选（如右图）。

⚠️ 如果不小心跳过了向导：打开 DevEco Studio → Settings（设置）→ SDK，在这里管理 SDK 和工具链。

✅ 验证

在 DevEco Studio 中打开 Settings → SDK 页面，看到：

  1. HarmonyOS SDK 状态正常（已安装或内置）。
  2. OpenHarmony SDK 中 Toolchains 状态为「已安装」。

两项都满足就过关。

HarmonyOS SDK（内置模式） 01_harmonyos_sdk_settings.png

OpenHarmony SDK（需勾选 Toolchains） 01_openharmony_sdk_settings.png

如果不对：回到 Settings → HarmonyOS SDK 页面，勾选缺失的组件点「Apply」重新下载。如果下载卡住，检查网络——华为的 SDK 服务器在国内，挂梯子反而可能更慢。

🎯 第 3 关：配置环境变量（本篇最关键）

目标：让终端也能找到 DevEco 自带的 ohpm、hvigorw、node 三个工具。

为什么需要这步？

DevEco Studio 内部自带了这些工具，但它们"躲"在 DevEco 的安装目录深处。你在 DevEco 的内置终端里用没问题，但打开系统终端（比如 Mac 的 Terminal、Windows 的 PowerShell），输入 ohpm 就会报 command not found——因为系统终端根本不知道去哪找这些工具。

我们需要做的，就是把这些工具的位置"告诉"系统终端。

这里有个最容易踩的坑

很多人电脑上已经装了 Node.js（比如之前做前端项目装的）。如果系统先找到了那个旧版 Node，而不是 DevEco 自带的版本，后面编译鸿蒙项目就会报各种莫名其妙的错——版本不兼容、模块找不到，排查半天发现根本不是代码的问题。

解决思路就是"插队"——把 DevEco 的工具路径放到 PATH 的最前面，这样系统找工具时，会先找到 DevEco 的版本。

📋 操作

macOS 用户

用编辑器打开终端配置文件 ~/.zshrc。

在终端里执行以下命令，用 VS Code 打开这个文件：

# 用 VS Code 打开终端配置文件
code ~/.zshrc

如果提示 code 命令找不到，也可以用：open -e ~/.zshrc（这条命令会用 Mac 自带的文本编辑器打开文件）

在文件末尾添加以下内容：

# ============ 鸿蒙开发环境 ============
# DevEco Studio 的安装位置（macOS 默认路径，如果修改了安装位置请同步修改此处）
export TOOL_HOME=/Applications/DevEco-Studio.app/Contents
export DEVECO_SDK_HOME=$TOOL_HOME/sdk


# 关键：把三个工具"插队"到 PATH 最前面
# 这样系统找工具时，会优先找到 DevEco 的版本
export PATH=$TOOL_HOME/tools/ohpm/bin:$PATH
export PATH=$TOOL_HOME/tools/hvigor/bin:$PATH
export PATH=$TOOL_HOME/tools/node/bin:$PATH

保存文件后，在终端里执行这条命令让设置立刻生效：

# 重新加载配置文件，让刚才的修改生效（不用重启终端）
source ~/.zshrc

或者更简单的方法：关掉终端窗口，重新打开一个新的。

Windows 用户

  1. 右键「此电脑」→「属性」→「高级系统设置」→「环境变量」
  2. 在「系统变量」区域，点「新建」，添加一个变量：
    • 变量名：DEVECO_SDK_HOME
    • 变量值：C:\Program Files\Huawei\DevEco Studio\sdk
  3. 在「系统变量」区域找到 Path，双击打开，添加以下三行，并且把它们拖到列表最顶端：
    • C:\Program Files\Huawei\DevEco Studio\tools\ohpm\bin
    • C:\Program Files\Huawei\DevEco Studio\tools\hvigor\bin
    • C:\Program Files\Huawei\DevEco Studio\tools\node

⚠️ Windows 的 Path 是从上往下依次查找的，所以一定要把这三行拖到最顶端。道理和 Mac 的"插队"一模一样——排在前面的先被找到。

✅ 验证

必须打开一个全新的终端窗口！ 旧窗口还在用修改前的配置，不会加载新设置。

逐个执行以下命令：

# 查看 ohpm 版本（鸿蒙的包管理工具）
ohpm -v

期望输出：版本号，比如 6.0.1

# 查看 Node.js 版本（应该是 DevEco 自带的版本）
node -v

期望输出：v18.x 或 v20.x

# 查看 hvigorw 版本（鸿蒙的构建工具）
hvigorw --version

期望输出：任何版本信息都行，能出东西就说明找到了

如果某个命令报 command not found：

  1. 确认你开的是新终端窗口（这是最常见的原因，旧窗口不会加载新配置）
  2. 检查 ~/.zshrc（Mac）或系统环境变量（Windows）里的路径是否拼写正确
  3. 用以下命令看看系统到底找到了哪个位置的工具： 
    # macOS：查看 ohpm 命令实际指向哪个文件
which ohpm
# Windows：查看 ohpm 命令实际指向哪个文件
where ohpm
    如果输出的路径不在 DevEco 目录下，说明没成功插到队伍前面——回去检查 PATH 配置的顺序。

🎯 第 4 关：补齐 JDK + 全面验证

目标：确认 Java 环境就位，所有工具全部可用。

为什么需要 JDK？

DevEco Studio 自带了 Java Runtime，日常开发够用。但编译某些三方鸿蒙插件时，构建工具会去找 JAVA_HOME 这个环境变量。如果系统里没装 JDK 17，到那时候才报错会更头疼——因为你会以为是插件的问题，排查半天才发现是 Java 没装。不如现在一步到位。

📋 操作

先检查一下当前的 Java 版本：

# 查看当前安装的 Java 版本
java -version

如果输出包含 17.x.x（比如 openjdk version "17.0.9"），直接跳过安装，去做最终验证。

如果没有输出或者版本不是 17：

macOS（在终端里执行）：

# 通过 Homebrew 安装 JDK 17
brew install openjdk@17

装完后 Homebrew 会提示你需要配置环境变量，按照提示把 JAVA_HOME 加到 ~/.zshrc 里即可。

Windows：

去 Oracle JDK 17 下载页 下载安装包，安装完成后：

  1. 新建系统变量 JAVA_HOME，值为 JDK 的安装路径（比如 C:\Program Files\Java\jdk-17）
  2. 在 Path 变量中添加 %JAVA_HOME%\bin

✅ 最终验证清单

打开一个全新的终端窗口，逐个执行：

命令期望结果
ohpm -v版本号（如 6.0.1）
node -vv18.x 或 v20.x
hvigorw --version版本信息
java -version17.x.x

四个都通过 = 通关！

01_open_version.png

如果 java -version 不对：

  • 确认安装的是 JDK 17，不是 8、11 或 21
  • macOS 用 brew info openjdk@17 查看安装状态和配置提示
  • Windows 确认 JAVA_HOME 环境变量指向了正确的目录，且 Path 里有 %JAVA_HOME%\bin

🏆 通关总结

项目状态
DevEco Studio✅ 已安装
HarmonyOS SDK✅ 已安装
ohpm✅ 命令行可用
hvigorw✅ 命令行可用
node✅ DevEco 版本优先
JDK✅ 17+

这一篇的核心就一件事——确保终端能找到 DevEco 的工具，而且优先找到它们（而不是系统里已有的旧版本）。理解了"插队"这个概念，后面遇到类似的 command not found 问题，你都知道该去哪查：先 which xxx 看系统找到的是哪个，再检查 PATH 里的顺序。

环境搭好了，接下来要装 Flutter 的鸿蒙版 SDK——但 FVM 根本不认识它，我们得想办法"哄"它接受。

→ 下一篇：【Flutter×鸿蒙】通关手册（二）：FVM 不认鸿蒙 SDK？4步手动塞进去

avatar
文章
阅读
粉丝