conti-retail-app/docs/15-flutter-sdk-cli.md

15. Flutter SDK CLI：官方 SDK 与 OpenHarmony SDK 速查

本文是本仓库的 Flutter 命令行总手册：先记录官方 Flutter SDK 的通用开发命令，再标记 CPF-Flutter OpenHarmony（OHOS）SDK 所增加的命令、环境和限制。它不是只讲 OHOS 的手册。

同一套 Dart / Flutter 业务代码通常使用相同的 CLI；区别主要在可用目标平台、原生构建工具、构建产物及插件实现。开发前先选定本次终端使用的 SDK，避免官方 Flutter 与 CPF-Flutter 混用。

本文是开发操作指南，不替代产品上线验收。首版正式交付范围仍以 README 所述 Android / iOS 为准；OHOS 的真机、插件和原生能力须分别验收。

1. 先选 SDK：官方 Flutter 还是 OHOS Flutter

目标	应使用的 SDK	典型命令
Android、iOS、Web、Windows、macOS、Linux	官方 Flutter SDK	flutter run、flutter build apk、flutter build appbundle、flutter build ipa、flutter build web 等
OpenHarmony	CPF-Flutter OHOS SDK	flutter run -d <OHOS设备>、flutter build hap
同时维护 Android / iOS / OHOS	CPF-Flutter OHOS SDK（项目和插件须完成 OHOS 兼容验证）	flutter run -d <对应设备>、按目标使用 build apk / build hap

检查当前终端实际使用哪个 SDK：

Get-Command flutter -All
flutter --version

不要把两个 SDK 的 bin 目录同时放在 PATH 前部并期待 Flutter 自动切换。flutter 命令只会使用 PATH 中排在最前的那个 SDK。需要明确切换时，调整 PATH、使用 FVM，或直接用目标 SDK 的 flutter.bat 完整路径执行。

官方 Flutter SDK 的通用命令

以下命令来自 Flutter CLI 本身，官方 Flutter SDK 与 CPF-Flutter OHOS SDK 都会保留（具体平台能力由当前 SDK 与目标设备决定）：

场景	命令	说明
查看版本	flutter --version	确认实际 SDK 与 Dart 版本
检查环境	flutter doctor -v	检查平台工具链与已连接设备
配置 SDK	flutter config --<key> <value>	查看：flutter config --list
新建 App	flutter create --org <org> <appName>	默认创建当前 SDK 支持的平台
列出设备	flutter devices	获取 deviceId
启动调试	flutter run -d <deviceId>	构建、安装、运行、连接调试器
连接已运行应用	flutter attach -d <deviceId>	不重新安装应用
截屏	flutter screenshot -d <deviceId> -o .\screen.png	默认截取设备完整屏幕
静态分析	flutter analyze	按 analysis_options.yaml 分析代码
执行测试	flutter test	执行 unit / widget 测试
获取依赖	flutter pub get	按 pubspec.yaml 解析依赖
更新依赖	flutter pub upgrade	更新允许范围内的依赖版本
查看依赖状态	flutter pub outdated	查看可升级依赖
清理项目	flutter clean	清理当前工程的构建与工具缓存
修复全局缓存	flutter pub cache repair	重新下载全局 Pub 缓存中的包
清空全局缓存	flutter pub cache clean	影响所有 Flutter / Dart 项目，最后手段

官方 Flutter SDK 的常见构建目标

这些是官方 SDK 的常用构建命令；是否可用取决于该平台的工具链与项目是否已生成对应目录。

flutter build apk --debug             # Android 测试 APK
flutter build apk --release           # Android 正式 APK
flutter build appbundle --release     # Android Play 上架 AAB
flutter build ipa --release           # iOS IPA（仅 macOS + Xcode 环境）
flutter build web --release           # Web 静态产物
flutter build windows --release       # Windows 桌面应用（Windows + Visual Studio）
flutter build macos --release         # macOS 桌面应用（仅 macOS）
flutter build linux --release         # Linux 桌面应用（仅 Linux）

flutter assemble 是底层 Flutter 资源构建入口，通常由上述 flutter build <target> 自动调用；日常不应把它当作完整应用打包命令。

2. 当前项目状态

app/ 已经是一个包含 OpenHarmony 平台目录的 Flutter 项目，不要在 app/ 目录重新执行 flutter create。这会以模板补全/修复工程，可能改写已有原生配置。

项目	当前值 / 状态
Flutter SDK	CPF-Flutter 3.41.10-ohos-1.0.0
Flutter SDK 路径	C:\Users\A200477427\Developments\flutter_flutter
OHOS 工程	app/ohos/ 已存在
DevEco OHOS SDK	C:\Program Files\Huawei\DevEco Studio\sdk
已验证模拟器	127.0.0.1:5555，ohos-x64
Flutter OHOS 开关	已启用：enable-ohos

3. OpenHarmony 专用：一次性环境配置（Windows）

CPF-Flutter 不是官方 Flutter release channel，因此 flutter doctor 可能提示非标准 remote / channel。这是该 OHOS SDK fork 的预期提示；不要为消除这条提示切回标准 Flutter SDK。

Flutter 配置

flutter config --enable-ohos
flutter config --ohos-sdk "C:\Program Files\Huawei\DevEco Studio\sdk"
flutter config --ohpm-home "C:\Program Files\Huawei\DevEco Studio\tools\ohpm"

Windows 用户级 PATH

将下面两个目录加到用户环境变量 Path，然后重启 PowerShell、VS Code / Android Studio：

C:\Program Files\Huawei\DevEco Studio\tools\ohpm\bin
C:\Program Files\Huawei\DevEco Studio\tools\hvigor\bin

可选地设置：

OHPM_HOME=C:\Program Files\Huawei\DevEco Studio\tools\ohpm

仅对当前 PowerShell 临时生效时：

$env:Path = "C:\Program Files\Huawei\DevEco Studio\tools\ohpm\bin;C:\Program Files\Huawei\DevEco Studio\tools\hvigor\bin;$env:Path"

验证

flutter doctor -v
flutter devices

必须看到：

[✓] HarmonyOS toolchain - develop for HarmonyOS devices

若未看到，优先检查 ohpm 和 hvigorw 是否能在新打开的 PowerShell 中直接执行，以及 DevEco Studio 是否安装了 OHOS SDK。

4. OpenHarmony 专用：日常运行、构建与安装

所有项目命令从 app/（包含 pubspec.yaml 的目录）运行：

cd C:\Users\A200477427\Developers\Continental-App\conti-retail-app\app

模拟器运行

flutter pub get
flutter devices
flutter run -d 127.0.0.1:5555

flutter run 会构建、安装、启动应用，并连接调试器。运行期间：r 热重载、R 热重启、q 退出调试。

HAP 构建

# x64 模拟器测试包
flutter build hap --debug --target-platform ohos-x64

# ARM64 真机测试包（默认目标也为 ohos-arm64）
flutter build hap --debug --target-platform ohos-arm64

# ARM64 真机正式包
flutter build hap --release --target-platform ohos-arm64

日常使用 SDK 自带的 OHOS Engine，不需 --local-engine。仅在自行编译了兼容 OHOS 的 Flutter Engine 时才传入该路径：

flutter build hap --debug --target-platform ohos-arm64 --local-engine="C:\path\to\ohos_debug_engine"

安装、附加调试和截图

# 构建并安装到指定设备（本机 SDK 的实际参数为 -d）
flutter install -d 127.0.0.1:5555 --debug

# 附加到已运行应用，不重新构建/安装
flutter attach -d 127.0.0.1:5555

# 截取完整设备屏幕
flutter screenshot -d 127.0.0.1:5555 -o .\ohos-screenshot.png

部分历史 OHOS SDK 文档将已有 HAP 的安装写为 flutter install -t <deviceId> <hap路径>。应以当前 SDK 的 flutter help install 为准；本项目当前 SDK 显示的是 -d / --device-id，且不将 HAP 路径作为该命令的位置参数。

5. OpenHarmony 扩展命令速查

[] 和 <> 均是文档占位符，实际执行时不要输入。

指令	作用	常用示例
doctor	检查开发环境	flutter doctor -v
config	配置 OHOS SDK 与工具	flutter config --enable-ohos
create（App）	创建独立多端应用	flutter create --platforms ohos,android,ios --org com.conti my_app
create（Module）	创建嵌入原生应用的 Flutter module	flutter create -t module my_module
create（Plugin）	创建 MethodChannel 插件	flutter create -t plugin --platforms ohos,android,ios my_plugin
create（Plugin FFI）	创建基于 Dart FFI 的插件	flutter create -t plugin_ffi --platforms ohos,android,ios my_plugin_ffi
devices	查找已连接设备	flutter devices
assemble	构建 Flutter 底层资源	flutter assemble（通常由 build hap 自动调用）
build hap	构建 OHOS HAP 安装包	flutter build hap --debug / --release
run	构建、安装、启动并调试	flutter run -d <deviceId>
install	构建并安装到设备	flutter install -d <deviceId> --debug
attach	附加到已运行应用	flutter attach -d <deviceId>
screenshot	截取设备屏幕	flutter screenshot -d <deviceId> -o .\screen.png
pub get	获取当前项目依赖	flutter pub get
clean	清理当前项目构建缓存	flutter clean
pub cache	管理全局 Pub 缓存	flutter pub cache repair
pub cache clean	清空全局 Pub 缓存	flutter pub cache clean

依赖与缓存的正确清理顺序

# 首选：只影响当前项目
flutter clean
flutter pub get

# 缓存确实损坏时：修复整机 Pub 缓存
flutter pub cache repair

# 最后手段：清空整机所有 Pub 缓存，再重新下载
flutter pub cache clean
flutter pub get

flutter pub cache clean 会影响电脑上的所有 Flutter / Dart 项目，不能作为普通构建失败时的第一反应。

6. CPF-Flutter OHOS SDK 与标准 Flutter SDK 的区别

维度	标准 Flutter SDK	CPF-Flutter OHOS SDK
维护与发行	Flutter 官方渠道及其 Engine	CPF-Flutter 维护的 OpenHarmony 适配发行版
新增目标平台	Android、iOS、Web、桌面等	在 Flutter 工具链中增加 ohos
原生工程目录	android/、ios/ 等	额外生成 ohos/
产物	Android APK/AAB、iOS IPA 等	OpenHarmony .hap
构建命令	flutter build apk、appbundle、ipa 等	flutter build hap --debug / --release
原生构建工具	Gradle、Xcode 等	DevEco Studio SDK、ohpm、hvigorw
设备发现/运行	flutter devices / flutter run	命令保持相同，但发现并运行 OHOS 实机/模拟器
插件实现	各平台的官方 embedding / API	插件必须有 OHOS 适配实现；并非所有 pub.dev 插件天然可用
SDK 版本标识	例如 3.41.x stable	例如 3.41.10-ohos-1.0.0，带 OHOS fork 后缀

不变的部分

• Dart、Flutter Widget、pubspec.yaml、flutter pub get、Widget / 单元测试的开发体验基本相同。
• flutter devices、flutter run、flutter attach、flutter screenshot 仍是主要 CLI 入口。
• 应用业务层不应因为增加 OHOS 平台而把平台判断散落到 feature 中；平台差异应集中在插件或原生集成层。

需要额外注意的部分

1. 插件兼容性不是自动获得的。 每个含原生能力的依赖（相机、扫码、WebView、推送、存储、权限等）都必须确认其是否有 OHOS implementation，并在 OHOS 模拟器与真机分别验证。
2. OHOS 使用 DevEco 构建链。 flutter build hap 内部会准备 Flutter 资源，再由 ohpm / hvigorw 完成 HAP 组装；前述工具未在 PATH 时 flutter doctor 会失败。
3. 模拟器与真机架构不同。 当前模拟器是 ohos-x64；大多数真机是 ohos-arm64。构建/测试时应明确目标。
4. 本地 Engine 是高级路径。 --local-engine 仅用于 SDK / Engine 开发或特定兼容性验证，普通业务开发使用随 CPF-Flutter SDK 提供的 Engine。
5. Windows 路径约束。 CPF-Flutter 文档提示，在 Windows 上 Flutter 项目与依赖插件项目应位于同一磁盘分区，避免宿主构建/插件解析出现路径问题。

7. 故障排查顺序

flutter doctor -v
    ↓
确认 HarmonyOS toolchain 为 ✓
    ↓
flutter devices
    ↓
确认目标设备 ID 与架构
    ↓
flutter clean && flutter pub get
    ↓
flutter run -d <deviceId>

• ohpm / hvigorw 缺失：确认第 3 节 PATH 配置，重开终端后再执行 flutter doctor -v。
• 设备未出现：确认模拟器已启动或真机已开启开发者模式/USB 调试，然后再次 flutter devices。
• 构建残留导致异常：先 flutter clean，再 flutter pub get；不要直接清除全局缓存。
• 某个原生功能不可用：先检查对应插件 OHOS 兼容性与 ohos/ 侧实现，不要默认 Dart 层代码跨平台即代表原生能力可用。

8. 来源与版本原则

• CPF-Flutter / flutter_flutter：OHOS Flutter SDK、支持命令与版本分支。
• OpenHarmony-SIG flutter_flutter README：环境要求、命令与 OpenHarmony 适配说明。
• 本机行为以 flutter --version、flutter help <command> 和 flutter doctor -v 为准。OHOS fork 版本演进很快，历史文档中的命令参数若与当前 CLI 帮助不一致，应以当前 CLI 为准。