Continental-AG/conti-docs
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add comprehensive Flutter SDK CLI guide for OpenHarmony integration

Browse Source
This commit is contained in:
Guangfei.Zhao
2026-09-03 14:25:02 +08:00
parent acdfc95686
commit c9fba7194e
1 changed files with 273 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
flutter-app/15-flutter-sdk-cli.md
+273
View File
@@ -0,0 +1,273 @@
# 15. Flutter SDK CLI：官方 SDK 与 OpenHarmony SDK 速查
本文是本仓库的 **Flutter 命令行总手册**：先记录官方 Flutter SDK 的通用开发命令，再标记 CPF-Flutter OpenHarmony（OHOS）SDK 所增加的命令、环境和限制。它不是只讲 OHOS 的手册。
同一套 Dart / Flutter 业务代码通常使用相同的 CLI；区别主要在可用目标平台、原生构建工具、构建产物及插件实现。开发前先选定本次终端使用的 SDK，避免官方 Flutter 与 CPF-Flutter 混用。
> 本文是开发操作指南，不替代产品上线验收。首版正式交付范围仍以 [README](./README.md) 所述 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：
```powershell
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 的常用构建命令；是否可用取决于该平台的工具链与项目是否已生成对应目录。
```powershell
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 配置
```powershell
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：
```text
C:\Program Files\Huawei\DevEco Studio\tools\ohpm\bin
C:\Program Files\Huawei\DevEco Studio\tools\hvigor\bin
```
可选地设置：
```text
OHPM_HOME=C:\Program Files\Huawei\DevEco Studio\tools\ohpm
```
仅对当前 PowerShell 临时生效时：
```powershell
$env:Path = "C:\Program Files\Huawei\DevEco Studio\tools\ohpm\bin;C:\Program Files\Huawei\DevEco Studio\tools\hvigor\bin;$env:Path"
```
### 验证
```powershell
flutter doctor -v
flutter devices
```
必须看到：
```text
[✓] HarmonyOS toolchain - develop for HarmonyOS devices
```
若未看到，优先检查 `ohpm` 和 `hvigorw` 是否能在新打开的 PowerShell 中直接执行，以及 DevEco Studio 是否安装了 OHOS SDK。
## 4. OpenHarmony 专用：日常运行、构建与安装
所有项目命令从 `app/`（包含 `pubspec.yaml` 的目录）运行：
```powershell
cd C:\Users\A200477427\Developers\Continental-App\conti-retail-app\app
```
### 模拟器运行
```powershell
flutter pub get
flutter devices
flutter run -d 127.0.0.1:5555
```
`flutter run` 会构建、安装、启动应用，并连接调试器。运行期间：`r` 热重载、`R` 热重启、`q` 退出调试。
### HAP 构建
```powershell
# 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 时才传入该路径：
```powershell
flutter build hap --debug --target-platform ohos-arm64 --local-engine="C:\path\to\ohos_debug_engine"
```
### 安装、附加调试和截图
```powershell
# 构建并安装到指定设备（本机 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` |
### 依赖与缓存的正确清理顺序
```powershell
# 首选：只影响当前项目
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. 故障排查顺序
```text
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](https://gitcode.com/CPF-Flutter/flutter_flutter)：OHOS Flutter SDK、支持命令与版本分支。
- [OpenHarmony-SIG flutter_flutter README](https://gitee.com/openharmony-sig/flutter_flutter/blob/master/README.en.md)：环境要求、命令与 OpenHarmony 适配说明。
- 本机行为以 `flutter --version`、`flutter help <command>` 和 `flutter doctor -v` 为准。OHOS fork 版本演进很快，历史文档中的命令参数若与当前 CLI 帮助不一致，应以当前 CLI 为准。