diff --git a/flutter-app/15-flutter-sdk-cli.md b/flutter-app/15-flutter-sdk-cli.md new file mode 100644 index 0000000..4193654 --- /dev/null +++ b/flutter-app/15-flutter-sdk-cli.md @@ -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 `、`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 -- ` | 查看：`flutter config --list` | +| 新建 App | `flutter create --org ` | 默认创建当前 SDK 支持的平台 | +| 列出设备 | `flutter devices` | 获取 `deviceId` | +| 启动调试 | `flutter run -d ` | 构建、安装、运行、连接调试器 | +| 连接已运行应用 | `flutter attach -d ` | 不重新安装应用 | +| 截屏 | `flutter screenshot -d -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 ` 自动调用；日常不应把它当作完整应用打包命令。 + +## 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 `。应以当前 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 ` | +| `install` | 构建并安装到设备 | `flutter install -d --debug` | +| `attach` | 附加到已运行应用 | `flutter attach -d ` | +| `screenshot` | 截取设备屏幕 | `flutter screenshot -d -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 +``` + +- `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 ` 和 `flutter doctor -v` 为准。OHOS fork 版本演进很快，历史文档中的命令参数若与当前 CLI 帮助不一致，应以当前 CLI 为准。