鸿蒙端作为拉取端提交配置

2026-06-02 02:31:31 +08:00
parent ba60d8d5be
commit 1cb9bc8649
5 changed files with 667 additions and 3519 deletions
--- a/iOS_macOS_Developer_Guide.md
+++ b/iOS_macOS_Developer_Guide.md
@@ -6,6 +6,17 @@

 ---

+## 文档更新日志
+
+| 日期 | 版本 | 变更内容 |
+|---|---|---|
+| 2026-06-02 | v7 | **重大变更**：pubspec.yaml 拆分为双模板（pubspec.ohos.yaml + pubspec.macos.yaml），pubspec.yaml 不再提交到 Git；新增三方库变更通知机制；新增 setup_pubspec.ps1 脚本 |
+| 2026-06-02 | v6 | 鸿蒙端 pubspec.yaml 同步 bitsdojo_window → window_manager 迁移；更新 file_picker 本地包版本注释(v8.3.7→v11.0.0-ohos.1)；更新 speech_to_text(^7.0.0→^7.4.0)、live_activities(^2.0.0→^2.4.9) 远程版本号；补充 dependency_overrides 中 bitsdojo_window_windows 移除说明 |
+| 2026-06-01 | v5 | 新增 §2.6 pub cache 补丁说明；标记 bitsdojo_window 迁移完成；file_picker 升级到 12.x |
+| 2026-05-30 | v4 | 初版完整指南 |
+
+---
+
 ## 一、环境准备与项目拉取

 ### 1.1 Flutter SDK 选择
@@ -35,15 +46,21 @@ git checkout feature/xxx
 git checkout main
 ```

-### 1.3 修改 pubspec.yaml 并安装依赖
+### 1.3 生成 pubspec.yaml 并安装依赖

-MacBook Pro 端需要将 `pubspec.yaml` 中的本地包引用替换为远程版本号（详见 §2.2）。
+> ⚠️ **`pubspec.yaml` 不再提交到 Git**。项目使用双模板机制：
+> - `pubspec.ohos.yaml` — 鸿蒙端模板（使用本地 packages/ 目录）
+> - `pubspec.macos.yaml` — MacBook Pro 端模板（使用远程版本号）
+> - `pubspec.yaml` — 由脚本自动生成，已加入 `.gitignore`

 ```bash
 # 1. 确认使用官方 Flutter SDK
 flutter --version   # 应显示官方版本，非 flutter-ohos

-# 2. 修改 pubspec.yaml（参见 §2.2 替换清单）
+# 2. 运行脚本生成 pubspec.yaml（MacBook Pro 端）
+.\tools\setup_pubspec.ps1 -Platform macos
+# 或自动检测平台
+.\tools\setup_pubspec.ps1

 # 3. 获取依赖
 flutter pub get
@@ -53,23 +70,53 @@ flutter build ios --no-codesign

 # 5. macOS 编译验证
 flutter build macos
+```

-# 5. 防止误提交 pubspec.yaml
-git stash push -m "macOS-local-pubspec" pubspec.yaml
+鸿蒙端开发者：
+```bash
+# 1. 确认使用 flutter-ohos SDK
+flutter --version   # 应显示 ohos 版本
+
+# 2. 运行脚本生成 pubspec.yaml（鸿蒙端）
+.\tools\setup_pubspec.ps1 -Platform ohos
+
+# 3. 获取依赖
+flutter pub get
 ```

 ---

-## 二、pubspec.yaml 与三方库
+## 二、pubspec.yaml 双模板机制

-### 2.1 MacBook Pro 端的核心原则
+### 2.1 架构概述
+
+> **`pubspec.yaml` 不再提交到 Git**，两端各自维护独立的模板文件。
+
+```
+项目根目录/
+├── pubspec.ohos.yaml    ← 鸿蒙端模板（tracked，使用本地 packages/ 目录）
+├── pubspec.macos.yaml   ← MacBook Pro 端模板（tracked，使用远程版本号）
+├── pubspec.yaml          ← 本地生成文件（.gitignore，不提交）
+└── tools/
+    └── setup_pubspec.ps1 ← 自动生成脚本
+```
+
+**为什么这样做？**
+
+之前鸿蒙端和 MacBook Pro 端共用一个 `pubspec.yaml`，MacBook Pro 端每次 `git pull` 后需要手动替换 82 行本地包引用，容易出错且经常互相覆盖。
+
+现在：
+- 鸿蒙端模板 `pubspec.ohos.yaml` 包含所有 `path: packages/` 引用
+- MacBook Pro 端模板 `pubspec.macos.yaml` 使用远程版本号
+- `pubspec.yaml` 由脚本自动生成，两边都不提交
+
+### 2.2 MacBook Pro 端的核心原则

 > **MacBook Pro 端不需要 `packages/` 目录，直接使用远程三方库即可。**

-项目 `pubspec.yaml` 中的本地包引用（`path: packages/xxx`）是为鸿蒙端准备的。
-MacBook Pro 端使用官方 Flutter SDK，需要将这些本地包引用替换为远程版本号。
+`pubspec.macos.yaml` 已将所有本地包引用替换为远程版本号，无需手动修改。

-**为什么不能直接用本地包？**
+**为什么不能直接用鸿蒙端的本地包？**

 本地包中包含 `TargetPlatform.ohos` 引用（鸿蒙SDK新增的枚举值），官方 SDK 没有此值，会导致编译报错：

@@ -89,154 +136,136 @@ Error: The getter 'ohos' isn't defined for the class 'TargetPlatform'

 **解决方案**：MacBook Pro 端使用远程版本，远程版本不含 `TargetPlatform.ohos`，编译正常。

-### 2.2 MacBook Pro 端 pubspec.yaml 修改指南
+### 2.3 双模板差异对照表

-克隆项目后，需要修改 `pubspec.yaml`，将本地包引用替换为远程版本号。
-
-#### 2.2.1 dependencies 区域 — 需要替换的包
-
-将以下包从 `path: packages/xxx` 改为版本号：
-
-```yaml
-# ❌ 原始写法（鸿蒙端）
-  shared_preferences:
-    path: packages/shared_preferences
-
-# ✅ MacBook Pro 端改为远程版本
-  shared_preferences: ^2.5.5
-```
-
-**完整替换清单：**
-
-| 包名 | 远程版本号 | 说明 |
+| 区域 | pubspec.ohos.yaml（鸿蒙端） | pubspec.macos.yaml（MacBook Pro端） |
 |---|---|---|
-| shared_preferences | ^2.5.5 | 轻量KV持久化 |
-| flutter_secure_storage | ^10.2.0 | 加密安全存储 |
-| hive_flutter | ^1.1.0 | Hive Flutter适配 |
-| path_provider | ^2.1.5 | 系统目录路径获取 |
-| package_info_plus | ^10.1.0 | 应用包信息读取 |
-| connectivity_plus | ^7.1.1 | 网络连接状态监听 |
-| device_info_plus | ^13.1.0 | 设备硬件信息读取 |
-| permission_handler | ^12.0.1 | 运行时权限请求 |
-| flutter_local_notifications | ^21.0.0 | 本地推送通知 |
-| url_launcher | ^6.3.2 | 打开外部URL/应用 |
-| app_links | ^7.0.0 | 深度链接处理 |
-| home_widget | ^0.9.1 | iOS/Android桌面小组件 |
-| file_picker | ^12.0.0-beta.5 | 文件选择器（⚠️ 12.x兼容win32 6.x，见§2.6） |
-| image_picker | ^1.2.2 | 相机/相册选图 |
-| share_plus | ^13.1.0 | 系统分享面板 |
-| gal | ^2.3.0 | 保存图片/视频到相册 |
-| pro_image_editor | ^12.4.4 | 图片编辑器核心（⚠️ 见§2.5） |
-| flutter_quill | ^11.5.0 | Quill富文本编辑器 |
-| flex_color_picker | ^3.8.0 | HSL颜色选择器 |
-| flutter_image_compress | ^2.4.0 | 图片压缩 |
-| wakelock_plus | ^1.4.0 | 屏幕常亮控制 |
-| audioplayers | ^6.5.0 | 音频播放 |
-| record | ^6.0.0 | 录音 |
-| video_compress | ^3.1.2 | 视频压缩 |
-| video_player | ^2.10.0 | 视频播放 |
-| local_auth | ^3.0.1 | 生物识别认证 |
-| sensors_plus | ^6.1.0 | 加速度传感器 |
-| battery_plus | ^7.0.0 | 电池状态监听 |
-| network_info_plus | ^8.1.0 | WiFi网络信息 |
-| flutter_webrtc | ^1.4.0 | WebRTC音视频通信 |
-| flutter_blue_plus | ^2.1.0 | 蓝牙BLE通信 |
-| flutter_nfc_kit | ^3.6.0 | NFC读写 |
-| mobile_scanner | ^7.1.4 | 二维码/条形码扫描 |
-| wifi_iot | ^0.3.19 | WiFi IoT设备连接 |
-| nearby_service | ^0.2.1 | 近场设备发现+通信 |
-| sqflite | ^2.4.1 | SQLite轻量数据库 |
-| receive_sharing_intent | git引用 | 接收外部分享内容（⚠️ gitcode引用，见§2.5） |
-| workmanager | ^0.9.0 | 后台任务调度 |
-| flutter_tts | ^4.2.0 | TTS文本转语音朗读 |
-| speech_to_text | ^7.0.0 | 语音转文字 |
-| live_activities | ^2.0.0 | 灵动岛/实时活动 |
-| flutter_vibrate | git引用 | 跨平台触觉反馈（⚠️ gitcode引用，见§2.5） |
-| bitsdojo_window | - | ❌ 已移除，替换为 window_manager（lib/代码已迁移完成） |
-| window_manager | ^0.5.1 | 桌面端窗口管理（替代 bitsdojo_window，已集成） |
+| shared_preferences | `path: packages/shared_preferences` | `^2.5.5` |
+| flutter_secure_storage | `path: packages/flutter_secure_storage` | `^10.2.0` |
+| hive_flutter | `path: packages/hive_flutter` | `^1.1.0` |
+| path_provider | `path: packages/path_provider` | `^2.1.5` |
+| package_info_plus | `path: packages/package_info_plus` | `^10.1.0` |
+| connectivity_plus | `path: packages/connectivity_plus` | `^7.1.1` |
+| device_info_plus | `path: packages/device_info_plus` | `^13.1.0` |
+| permission_handler | `path: packages/permission_handler` | `^12.0.1` |
+| flutter_local_notifications | `path: packages/flutter_local_notifications` | `^21.0.0` |
+| url_launcher | `path: packages/url_launcher` | `^6.3.2` |
+| app_links | `path: packages/app_links` | `^7.0.0` |
+| home_widget | `git: gitcode.com/...` | `^0.9.1` |
+| file_picker | `path: packages/file_picker` | `^12.0.0-beta.5` |
+| image_picker | `path: packages/image_picker` | `^1.2.2` |
+| share_plus | `path: packages/share_plus` | `^13.1.0` |
+| gal | `path: packages/gal` | `^2.3.0` |
+| flutter_quill | `path: packages/flutter_quill` | `^11.5.0` |
+| flex_color_picker | `path: packages/flex_color_picker` | `^3.8.0` |
+| flutter_image_compress | `path: packages/flutter_image_compress` | `^2.4.0` |
+| wakelock_plus | `path: packages/wakelock_plus` | `^1.4.0` |
+| audioplayers | `path: packages/audioplayers` | `^6.5.0` |
+| record | `path: packages/record` | `^6.0.0` |
+| video_compress | `path: packages/video_compress` | `^3.1.2` |
+| video_player | `path: packages/video_player` | `^2.10.0` |
+| local_auth | `path: packages/local_auth` | `^3.0.1` |
+| sensors_plus | `path: packages/sensors_plus` | `^6.1.0` |
+| battery_plus | `path: packages/battery_plus` | `^7.0.0` |
+| network_info_plus | `path: packages/network_info_plus` | `^8.1.0` |
+| flutter_webrtc | `path: packages/flutter_webrtc` | `^1.4.0` |
+| flutter_blue_plus | `path: packages/flutter_blue_plus` | `^2.1.0` |
+| flutter_nfc_kit | `path: packages/flutter_nfc_kit` | `^3.6.0` |
+| mobile_scanner | `path: packages/mobile_scanner` | `^7.1.4` |
+| wifi_iot | `path: packages/wifi_iot` | `^0.3.19` |
+| nearby_service | `path: packages/nearby_service` | `^0.2.1` |
+| sqflite | `path: packages/sqflite` | `^2.4.1` |
+| workmanager | `path: packages/workmanager` | `^0.9.0` |
+| flutter_tts | `path: packages/flutter_tts` | `^4.2.0` |
+| speech_to_text | `path: packages/speech_to_text` | `^7.4.0` |
+| live_activities | `path: packages/live_activities` | `^2.4.9` |
+| dependency_overrides | 40+ 行（含本地包覆盖 + ohos 子包） | 4 行（仅版本号覆盖 + win32） |

-#### 2.2.2 dependency_overrides 区域 — 整体替换
+### 2.4 ⚠️ 新增三方库变更流程（必读）

-MacBook Pro 端不需要 `dependency_overrides` 中的本地包覆盖，改为仅保留版本号覆盖：
-
-```yaml
-# MacBook Pro 端的 dependency_overrides（精简版）
-dependency_overrides:
-  meta: ^1.17.0
-  web: ^1.1.0
-  timezone: ^0.11.0
-  win32: ^6.0.1
-  # 删除所有 path: packages/xxx 条目
-```
-
-#### 2.2.3 快速替换脚本
-
-```bash
-# 在项目根目录执行，自动将本地包引用替换为远程版本
-# ⚠️ 执行前请备份 pubspec.yaml
-
-# 方式1：手动替换（推荐，更可控）
-# 用编辑器打开 pubspec.yaml，搜索 "path: packages/" 逐个替换
-
-# 方式2：使用 sed 批量替换（macOS 终端）
-# 将所有 "path: packages/xxx" 行替换为对应版本号
-# 注意：此脚本仅作参考，请根据实际版本号调整
-```
-
-#### 2.2.4 ⚠️ 重要：不要提交修改后的 pubspec.yaml
-
-```bash
-# 修改 pubspec.yaml 后，使用 git stash 暂存，不要提交
-git stash push -m "macOS-local-pubspec" pubspec.yaml
-
-# 需要恢复时
-git stash pop
-
-# 或者将修改后的 pubspec.yaml 加入 .git/info/exclude
-echo "pubspec.yaml" >> .git/info/exclude
-```
-
-> **铁律**：MacBook Pro 端对 `pubspec.yaml` 的修改**绝对不能提交到 Git**。
-> 仓库中的 `pubspec.yaml` 必须保持鸿蒙端的本地包引用配置。
-
-### 2.3 已迁移至远程版本的纯Dart包
-
-以下包已从本地包迁移为远程版本依赖，两端无需额外操作：
+> **铁律：新增三方库时，必须同时更新两个模板 + 本文档。**

 ```
-badges ^3.2.0 | catcher_2 ^2.1.9 | flutter_card_swiper ^7.2.0
-stupid_simple_sheet ^0.9.1+1 | liquid_glass_easy ^1.1.1
-liquid_glass_widgets ^0.11.0 | flutter_shaders_ui ^0.1.0
-flutter_spritesheet_animation ^1.0.1 | image_size_getter ^2.4.1
-extended_image ^10.0.1 | photo_view ^0.15.0
+新增三方库流程：
+1. 在 pubspec.ohos.yaml 添加依赖（鸿蒙端优先）
+2. 在 pubspec.macos.yaml 添加对应远程版本
+3. 在本文档 §2.3 差异对照表添加一行
+4. 在本文档顶部更新日志记录变更
+5. 在 CHANGELOG.md 记录变更
+6. git push 后通知另一端开发者
+7. 另一端开发者: git pull → 运行 setup_pubspec.ps1 → flutter pub get
 ```

-### 2.4 MacBook Pro 端完整操作流程
+**鸿蒙端新增本地化包时额外步骤：**
+- 将包放入 `packages/` 目录
+- 在 `pubspec.ohos.yaml` 的 `dependency_overrides` 中添加覆盖
+- 在 `pubspec.macos.yaml` 中使用远程版本号
+- 更新本文档 §2.3 差异对照表
+
+**升级三方库版本时：**
+- 在对应模板中更新版本号
+- 如果是鸿蒙本地包升级，同步更新 `pubspec.ohos.yaml` 中的版本注释
+- 更新本文档 §2.3 差异对照表中的版本号
+
+### 2.5 setup_pubspec.ps1 脚本说明
+
+```powershell
+# 鸿蒙端
+.\tools\setup_pubspec.ps1 -Platform ohos
+
+# MacBook Pro 端
+.\tools\setup_pubspec.ps1 -Platform macos
+
+# 自动检测（根据 flutter --version 或 packages/ 目录是否存在）
+.\tools\setup_pubspec.ps1
+```
+
+脚本功能：
+- 将对应模板复制为 `pubspec.yaml`
+- 自动备份现有 `pubspec.yaml` → `pubspec.yaml.bak`
+- 验证模板内容（鸿蒙端检查 `path: packages/`，MacBook Pro 端检查无本地包引用）
+- 输出后续操作提示
+
+### 2.6 MacBook Pro 端完整操作流程

 ```bash
 # 1. 克隆仓库
 git clone <仓库URL> xianyan
 cd xianyan

-# 2. 修改 pubspec.yaml（替换本地包为远程版本）
-#    参见 §2.2 的替换清单
+# 2. 生成 pubspec.yaml
+.\tools\setup_pubspec.ps1 -Platform macos

 # 3. 获取依赖
 flutter pub get

-# 4. 编译验证
+# 4. 应用 pub cache 补丁（见 §2.8）
+bash scripts/patch_pub_cache.sh
+
+# 5. 编译验证
 flutter build ios --no-codesign
 flutter build macos
-
-# 6. 防止误提交 pubspec.yaml
-git stash push -m "macOS-local-pubspec" pubspec.yaml
-# 或
-echo "pubspec.yaml" >> .git/info/exclude
 ```

-### 2.5 特殊包说明
+### 2.7 鸿蒙端完整操作流程

-#### 2.5.1 pro_image_editor（已迁移至远程版本）
+```bash
+# 1. 克隆仓库
+git clone <仓库URL> xianyan
+cd xianyan
+
+# 2. 确保 packages/ 目录已准备好（从 zip 解压或 git submodule）
+
+# 3. 生成 pubspec.yaml
+.\tools\setup_pubspec.ps1 -Platform ohos
+
+# 4. 获取依赖
+flutter pub get
+```
+
+### 2.8 特殊包说明
+
+#### 2.8.1 pro_image_editor（已迁移至远程版本）

 `pro_image_editor` 已从本地包迁移为远程版本 `^12.4.4`，MacBook Pro 端直接使用远程版本即可：

@@ -249,7 +278,7 @@ echo "pubspec.yaml" >> .git/info/exclude
 > 远程版本可能不包含此类型，需要检查兼容性。
 > 如遇编译错误，可恢复使用本地包版本（`path: packages/pro_image_editor`）。

-#### 2.5.2 file_picker（API 变更 + win32 6.x 兼容）
+#### 2.8.2 file_picker（API 变更 + win32 6.x 兼容）

 `file_picker` 已从 `^11.0.0` 升级为 `^12.0.0-beta.5`，原因：

@@ -268,15 +297,19 @@ final result = await FilePicker.pickFiles();
   - `file_picker ^12.0.0-beta.5` 兼容 `win32 ^6.0.1`，解决 macOS 构建失败
   - ⚠️ 12.x 为 beta 版本，如遇问题可回退到 11.x（需同时降级 win32 override，见§2.6）

-项目代码已更新为新版 API。鸿蒙端如使用本地包版本（`file_picker ^8.x`），
-需注意 API 差异，或升级本地包到 `^11.x`。
+项目代码已更新为新版 API。鸿蒙端本地包版本已升级为 `11.0.0-ohos.1`（基于 file_picker 11.x 适配），
+API 已与远程版本对齐，无需额外处理。

-#### 2.5.3 flutter_secure_storage（版本升级）
+#### 2.8.3 flutter_secure_storage（版本差异说明）

-`flutter_secure_storage ^10.2.0` 的 Windows 平台实现兼容 `win32 ^6.0.1`，
+MacBook Pro 端使用远程版本 `^10.2.0`，其 Windows 平台实现兼容 `win32 ^6.0.1`，
 解决了之前版本与 `win32 6.x` 的编译冲突。

-#### 2.5.4 receive_sharing_intent（gitcode 引用）
+> **注意**：鸿蒙端本地包版本为 `9.2.4-ohos.1`（基于 9.x 适配），
+> 与 MacBook Pro 端远程版本 `10.2.0` 存在主版本号差异。
+> 两端 API 兼容，`lib/` 代码无需特殊处理。
+
+#### 2.8.4 receive_sharing_intent（gitcode 引用）

 `receive_sharing_intent` 在 pub.dev 上的版本与鸿蒙端不兼容，MacBook Pro 端需使用 gitcode 引用：

@@ -291,7 +324,7 @@ final result = await FilePicker.pickFiles();
 > **注意**：gitcode 版本的 `SharedMediaFile` 构造函数可能包含 `ohosPath` 等鸿蒙特有参数，
 > 官方 SDK 不存在这些参数。项目代码中已通过 `pu.isOhos` 条件分支隔离。

-#### 2.5.5 flutter_vibrate（gitcode 引用）
+#### 2.8.5 flutter_vibrate（gitcode 引用）

 `flutter_vibrate` 在 pub.dev 上的版本不支持鸿蒙，MacBook Pro 端需使用 gitcode 引用：

@@ -302,7 +335,7 @@ final result = await FilePicker.pickFiles();
      url: https://gitcode.com/openharmony-sig/fluttertpc_flutter_vibrate.git
 ```

-#### 2.5.6 home_widget（pub.dev 远程版本）
+#### 2.8.6 home_widget（pub.dev 远程版本）

 `home_widget` 的 gitcode 版本依赖 `path_provider` 的 git 版本，会与远程 `path_provider` 冲突。
 MacBook Pro 端使用 pub.dev 版本 `^0.9.1`，鸿蒙端的 `ohosName` 参数通过 `pu.isOhos` + `dynamic` 调用隔离：
@@ -312,20 +345,20 @@ MacBook Pro 端使用 pub.dev 版本 `^0.9.1`，鸿蒙端的 `ohosName` 参数
  home_widget: ^0.9.1
 ```

-### 2.6 ⚠️ pub cache 补丁（MacBook Pro 端必读）
+### 2.9 ⚠️ pub cache 补丁（MacBook Pro 端必读）

 > **关键问题**：`dependency_overrides` 中 `win32: ^6.0.1` 导致部分依赖 `win32 ^5.x` 的三方包编译失败。
 > 这些三方包的 Windows 平台代码在 macOS 构建时也会被编译（Dart 编译器不区分平台）。
 > 需要手动修补 pub cache 中的文件，使它们兼容 win32 6.x API。

-#### 2.6.1 需要修补的包
+#### 2.9.1 需要修补的包

 | 包名 | 版本 | 问题 | 修补文件 |
 |---|---|---|---|
 | quill_native_bridge_windows | 0.0.2 | 使用 win32 5.x API（`TEXT()`、`OpenClipboard(NULL)==FALSE` 等） | `lib/quill_native_bridge_windows.dart` + `lib/src/clipboard_html_format.dart` |
 | flutter_vibrate | gitcode | `TARGET_OS_SIMULATOR` 在 Xcode 16+/Swift 6 中不可用 | `ios/Classes/SwiftVibratePlugin.swift` |

-#### 2.6.2 补丁应用流程
+#### 2.9.2 补丁应用流程

 ```bash
 # 1. 确保 flutter pub get 已执行
@@ -341,7 +374,7 @@ flutter build ios --no-codesign

 > ⚠️ `flutter clean` 或 `flutter pub cache repair` 会清除补丁，需重新执行步骤 2。

-#### 2.6.3 补丁脚本
+#### 2.9.3 补丁脚本

 在项目根目录创建 `scripts/patch_pub_cache.sh`（已包含在仓库中），内容如下：

@@ -662,7 +695,7 @@ echo "🎉 All patches applied!"
 echo "⚠️  Note: Run this script again after 'flutter clean' or 'flutter pub cache repair'"
 ```

-#### 2.6.4 win32 5.x → 6.x API 迁移参考
+#### 2.9.4 win32 5.x → 6.x API 迁移参考

 如需修补其他使用 win32 的三方包，以下是关键 API 变更：

@@ -1010,10 +1043,14 @@ iOS/macOS 端这些检测不会执行（`isOhos` 为 false），无需关心。

 ### 5.4 packages 目录说明

- `packages/` 目录存放鸿蒙适配的本地三方库，已在 `.gitignore` 中排除
+- `packages/` 目录存放鸿蒙适配的本地三方库，已在 `.gitignore` 中排除（`/packages/`）
 - MacBook Pro 端需要 `packages/pro_image_editor/`（含魔改的 `CanvasStyleModel`），从 zip 解压获取
 - 其他本地包 MacBook Pro 端使用远程版本，无需放在 `packages/` 目录
 - 鸿蒙开发者需手动维护本地 `packages/` 目录
+- `packages/bitsdojo_window_windows/` 已随 bitsdojo_window 移除而废弃，可安全删除
+- ⚠️ `pubspec.yaml` 已加入 `.gitignore`，不再提交到 Git
+- 鸿蒙端模板：`pubspec.ohos.yaml`，MacBook Pro 端模板：`pubspec.macos.yaml`
+- 使用 `tools/setup_pubspec.ps1` 生成 `pubspec.yaml`

 ### 5.5 MacBook Pro 修改 ios/macos 后，鸿蒙端是否需要同步？

@@ -1022,24 +1059,30 @@ iOS/macOS 端这些检测不会执行（`isOhos` 为 false），无需关心。
 | `ios/` 目录 | ❌ 不需要 | 平台原生代码，鸿蒙不使用 |
 | `macos/` 目录 | ❌ 不需要 | 平台原生代码，鸿蒙不使用 |
 | `lib/` 目录 | ✅ 需要同步 | Dart 代码所有平台共用 |
-| `pubspec.yaml` | ✅ 需要同步 | 依赖配置共享（鸿蒙端自行维护本地包版本） |
+| `pubspec.ohos.yaml` | ✅ 鸿蒙端模板 | 鸿蒙端依赖配置 |
+| `pubspec.macos.yaml` | ✅ MacBook Pro端模板 | MacBook Pro端依赖配置 |
+| `pubspec.yaml` | ❌ 不提交 | 已加入 .gitignore，本地生成 |
 | `assets/` 目录 | ✅ 需要同步 | 资源文件共享 |

+> **实际案例**：`bitsdojo_window → window_manager` 迁移时，MacBook Pro 端先完成代码和依赖替换，
+> 鸿蒙端随后同步更新 `pubspec.yaml`（移除 `bitsdojo_window`，添加 `window_manager`），
+> 并删除 `packages/bitsdojo_window_windows/` 废弃目录。
+
 ### 5.6 常见问题

 | 问题 | 原因 | 解决方案 |
 |---|---|---|
-| `flutter pub get` 报 packages/xxx 目录不存在 | pubspec.yaml 中有 `path: packages/xxx` 引用 | 替换为远程版本号，参见 §2.2 |
-| 编译报 `TargetPlatform.ohos` 不存在 | 使用了含 ohos 引用的本地包 | 使用远程版本，参见 §2.1 |
+| `flutter pub get` 报 packages/xxx 目录不存在 | pubspec.yaml 是鸿蒙端模板 | MacBook Pro端运行 `.\tools\setup_pubspec.ps1 -Platform macos` |
+| 编译报 `TargetPlatform.ohos` 不存在 | 使用了含 ohos 引用的本地包 | 确认使用 `pubspec.macos.yaml` 生成的 pubspec.yaml |
 | iOS 编译报 ohos 相关错误 | 误用鸿蒙SDK编译iOS | 切换到官方 Flutter SDK |
 | GoRouter 路由正常但鸿蒙端白屏 | 鸿蒙端不支持 GoRouter | 检查 OhosNavBridge 路由映射 |
-| git pull 后 pubspec.yaml 被覆盖 | 仓库版本是鸿蒙端配置 | 重新替换为远程版本，参见 §3.3.4 |
-| 误提交了 MacBook Pro 端的 pubspec.yaml | 删除了鸿蒙本地包引用 | 立即回退，恢复鸿蒙端配置 |
+| git pull 后 pubspec.yaml 被覆盖 | pubspec.yaml 已在 .gitignore | 重新运行 `.\tools\setup_pubspec.ps1` |
+| 新增依赖后另一端报错 | 只更新了一个模板 | 必须同时更新两个模板 + 文档，参见 §2.4 |
 | 新增依赖后鸿蒙端报错 | 新增的三方库未适配鸿蒙 | 通知鸿蒙开发者评估，必要时本地化到 packages/ |
 | 编译报 `OhosInitializationSettings` 不存在 | 官方SDK无此类型 | 使用 `notification_init_stub.dart` 桥接，参见 §4.5 |
 | 编译报 `ohosName` 参数不存在 | 官方SDK的 HomeWidget 无此参数 | 使用 `dynamic` 调用，参见 §4.5.2 |
-| `pro_image_editor` 报 `CanvasStyleModel` 不存在 | 远程版本不含魔改内容 | 使用本地包 `path: packages/pro_image_editor`，参见 §2.5.1 |
-| `FilePicker.platform` 报错 | file_picker 11.x API 变更 | 使用 `FilePicker.pickFiles()`，参见 §2.5.2 |
+| `pro_image_editor` 报 `CanvasStyleModel` 不存在 | 远程版本不含魔改内容 | 使用本地包 `path: packages/pro_image_editor`，参见 §2.8.1 |
+| `FilePicker.platform` 报错 | file_picker 11.x API 变更 | 使用 `FilePicker.pickFiles()`，参见 §2.8.2 |

 ---