03. Flutter鸿蒙SDK配置：下载flutter_flutter并配置环境变量

普通 Flutter SDK 默认不带 OpenHarmony 平台构建能力。开发鸿蒙项目时，需要使用 OpenHarmony SIG 维护的 flutter_flutter 仓库，它在 Flutter Tools 的基础上扩展了 ohos 平台创建、构建、运行和调试能力。

下载 SDK

在工作区创建 SDK 目录：

cd /d D:\flutter_ohos_workspace
mkdir sdk
cd sdk
git clone https://gitee.com/openharmony-sig/flutter_flutter.git

如果仓库主页提示迁移或镜像地址变化，以项目主页给出的地址为准。克隆完成后目录大致如下：

D:\flutter_ohos_workspace\sdk\flutter_flutter
├─ bin
├─ packages
├─ examples
└─ version

真正需要加入 PATH 的是 bin 目录，不是仓库根目录。

配置 Flutter 环境变量

Windows 系统变量可以这样规划：

PUB_CACHE=D:\flutter_ohos_workspace\pub_cache
PUB_HOSTED_URL=https://pub.flutter-io.cn
FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn
PATH=D:\flutter_ohos_workspace\sdk\flutter_flutter\bin

PUB_CACHE 用来保存 Dart 依赖缓存，单独放在工作区内便于清理和迁移。两个镜像变量可以提高依赖下载速度。PATH 里必须包含 OpenHarmony 适配版 Flutter 的 bin 目录，否则命令行可能仍然调用系统里其他 Flutter。

配置 OpenHarmony 工具链变量

继续配置 DevEco 相关变量：

TOOL_HOME=D:\DevTools\DevEco Studio
DEVECO_SDK_HOME=%TOOL_HOME%\sdk
PATH=%TOOL_HOME%\tools\ohpm\bin
PATH=%TOOL_HOME%\tools\hvigor\bin
PATH=%TOOL_HOME%\tools\node

TOOL_HOME 指向 DevEco Studio 安装目录，DEVECO_SDK_HOME 指向 SDK 目录。ohpm、hvigor、node 三个目录都要追加到 PATH。环境变量改完后必须重新打开命令行窗口。

确认当前 flutter 来源

同一台电脑可能安装过多个 Flutter。配置完成后先查命令来源：

where flutter
flutter --version

where flutter 的第一个结果应该指向：

D:\flutter_ohos_workspace\sdk\flutter_flutter\bin\flutter.bat

如果第一个结果是其他目录，说明 PATH 顺序不对。把 flutter_flutter\bin 放到更靠前的位置，再重新打开命令行。

执行 doctor 检查

flutter doctor -v

重点看 Flutter 和 OpenHarmony 两块是否通过。常见问题和处理方式：

现象	处理
找不到 JDK	检查 JAVA_HOME 和 PATH
找不到 OpenHarmony SDK	检查 DEVECO_SDK_HOME
找不到 ohpm	检查 tools\ohpm\bin
找不到 hvigor	检查 tools\hvigor\bin
依赖下载慢	检查镜像变量和网络

缓存清理

如果切换了 SDK 版本、镜像地址或分支，缓存可能导致旧产物继续参与构建。可以按下面顺序清理：

flutter clean
flutter pub cache clean

必要时删除：

D:\flutter_ohos_workspace\sdk\flutter_flutter\bin\cache

然后重新执行：

flutter doctor -v
flutter pub get

SDK 分支和缓存的关系

切换 flutter_flutter 分支后，旧缓存可能继续影响构建。比较稳的处理方式是：

cd /d D:\flutter_ohos_workspace\sdk\flutter_flutter
git status
git branch
flutter clean

如果项目依赖也发生变化，再回到项目根目录：

cd /d D:\flutter_ohos_workspace\projects\hello_ohos
flutter pub get
flutter doctor -v

只有 SDK 和项目都处于明确状态，构建错误才容易定位。

镜像地址变化后的处理

如果改过 FLUTTER_STORAGE_BASE_URL，需要关注 bin/cache。缓存里的引擎产物和当前镜像不匹配时，可能会出现 Dart VM 快照版本相关错误。处理顺序：

1. 关闭正在运行的 flutter 命令
2. 删除 flutter_flutter/bin/cache
3. 重新打开命令行
4. 执行 flutter doctor -v
5. 回项目执行 flutter clean 和 flutter pub get

``text

1. 关闭正在运行的 flutter 命令
2. 删除 flutter_flutter/bin/cache
3. 重新打开命令行
4. 执行 flutter doctor -v
5. 回项目执行 flutter clean 和 flutter pub get