update

2026-08-07 18:31:37 +08:00
parent ccda415cd7
commit d0d48c1ffc
2 changed files with 471 additions and 71 deletions
@@ -0,0 +1,390 @@
+# ARCX iOS 本地打包机落地计划
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 在本机（或专用 Mac）建立可重复的 ARCX iOS 出包能力：前端资源导出 → 原生工程签名 → 产出可安装/可上架 ipa。
+
+**Architecture:** 采用「两阶段」：Phase A 先用 Mac **安心打包**快速打通证书与出包；Phase B 再搭建完整 **离线 SDK + Xcode** 本地打包机，满足证书/代码不出本机、可脚本化/CI 的需求。`arcx-app` 是 vue-cli/vite 项目，本地打包资源**必须经 HBuilderX 导出**，不能仅靠 `npm run build:ios`。
+
+**Tech Stack:** uni-app (Vue3/Vite) · HBuilderX · DCloud iOS 离线 SDK · Xcode 26+ · CocoaPods · Apple Developer 证书/Profile · Transporter
+
+**官方文档入口：**
+- 总览：[uni-app 官网](https://uniapp.dcloud.net.cn/) → 发布 → 原生 App（离线）
+- 离线 SDK 总入口：[nativesupport AppDocs](https://nativesupport.dcloud.net.cn/AppDocs/README)
+- iOS 开发环境/工程配置：[usesdk/ios](https://nativesupport.dcloud.net.cn/AppDocs/usesdk/ios)
+- 导出前端资源：[importfeproject/export](https://nativesupport.dcloud.net.cn/AppDocs/importfeproject/export.html)
+- 证书/Archive/上传：[package/ios](https://nativesupport.dcloud.net.cn/AppDocs/package/ios.html)
+- iOS 原生资源（Info.plist 等）：[app-nativeresource-ios](https://uniapp.dcloud.net.cn/tutorial/app-nativeresource-ios)
+- 安心打包（Mac 本地签）：[SafePack](https://uniapp.dcloud.net.cn/tutorial/build/SafePack.html)
+- 模块/Pod 集成（5.13+）：[iOSModuleConfig/common](https://nativesupport.dcloud.net.cn/AppDocs/usemodule/iOSModuleConfig/common.html)
+
+---
+
+## 官网结论摘要（先读再落地）
+
+### 两条「本地」路径不要混
+
+| 路径 | 本质 | 证书/前端代码 | 限制 | 适合 |
+|------|------|---------------|------|------|
+| **安心打包** | 云端生成原生壳，**本机合并代码并签名** | 不上传代码与证书 | 非纯离线；改模块配置会重新拉壳；付费原生插件/原生混淆能力受限场景见文档 | 日常出包、Mac 打包机首选起步 |
+| **离线打包** | 下载 iOS 离线 SDK，用 **Xcode** 本地编签 | 全程本机 | 无原生混淆；**付费 uni 原生插件不可用**；须申请 `dcloud_appkey`；编译器版本必须与 SDK 一致 | 强合规、深度原生定制、CI Archive |
+
+### 离线打包标准流水线（官方）
+
+1. **版本对齐**：HBuilderX / `npm run info` 的编译器版本 ≡ 离线 SDK 版本（不一致会弹窗且功能异常）。
+2. **申请 Appkey**（SDK ≥ 3.1.10）：在 Info.plist 配置 `dcloud_appkey`；Bundle ID + `control.xml` 中 appid 必须与申请一致。
+3. **导出资源**：HBuilderX → 发行 → 原生 App-本地打包 → **生成本地打包 App 资源**。  
+   - **vue-cli 项目不能用纯 CLI 导出**，必须用 HBuilderX 打开项目再导出。  
+   - `manifest.json` 的 `appid` 不能手填空值，须由 HBuilderX 获取（本仓库已有 `__UNI__8A880C6`）。
+4. **配置 Xcode 工程**（`HBuilder-Hello`）：
+   - Bundle ID / Display Name / Version / Build
+   - 与导出资源中的 `manifest`、`control.xml` appid 对齐
+   - 图标、LaunchScreen、隐私描述、所需模块（参考 `Feature-iOS.xls`；新版推荐 CocoaPods `uniapp_subspecs`）
+   - 合并项目内 `nativeResources/ios`（离线时需**手动**合并进 Xcode）
+5. **Signing**：生产证书 + Distribution Profile（与 Bundle ID 绑定）。
+6. **Product → Archive → 导出 ipa**；上架用 **Transporter** 上传。
+
+### 与本仓库的映射
+
+| 项 | 当前值 | 打包机要求 |
+|----|--------|------------|
+| 项目形态 | vite + `@dcloudio/uni-app` alpha `4080620251107001` | 离线 SDK 选与编译器对齐的版本；用 HBuilderX 打开本仓库根目录 |
+| DCloud appid | `__UNI__8A880C6` | 写入 SDK 工程 `control.xml` / 资源目录名 |
+| iOS Bundle ID | `com.shelingxingqiu.arcx` | Apple App ID + Provisioning 必须一致 |
+| 版本 | `versionName` 0.1.1 / `versionCode` 101 | Xcode Version / Build 对齐 |
+| 证书 | `manifest` 中 p12/profile **已注释** | 打包机钥匙串导入正式证书；勿把密码提交 Git |
+| 原生资源 | `nativeResources/ios/info.plist`（含 ATT 文案） | 云包自动合并；离线需手动合并 |
+| 本机工具 | macOS 26.1 · Xcode 26.1.1 · CocoaPods 已装 | 已满足官方「Xcode 26.0+」门槛 |
+
+---
+
+## 文件与目录约定（打包机）
+
+建议在打包机固定目录（示例，可按团队规范改）：
+
+```text
+~/Packaging/
+  credentials/          # 不进 Git：.p12、.mobileprovision、密码备忘（加密磁盘）
+  sdk/
+    iOS-SDK-<ver>/      # 解压后的离线 SDK（与编译器同版本）
+  workspace/
+    arcx-app/           # git clone
+    HBuilder-Hello/     # 从 SDK 拷出的长期维护工程（或软链）
+  artifacts/
+    ipa/                # 产出
+    logs/
+  scripts/
+    export-note.md      # HBuilderX 导出步骤备忘（GUI）
+    sync-www.sh         # 把导出的 www/资源拷进原生工程
+    archive.sh          # xcodebuild archive + export
+```
+
+项目内相关文件：
+- `src/manifest.json` — appid、ios.appid、隐私、图标路径
+- `nativeResources/ios/info.plist` — 额外 Info.plist 合并项
+- `package.json` — 编译器版本锚点
+- `docs/superpowers/plans/2026-08-07-ios-local-pack-machine.md` — 本计划
+
+---
+
+## Phase A：Mac 安心打包机（1–2 天，先打通）
+
+> 目标：Mac 上可重复产出已签名 ipa；证书与业务代码不上传云端（首次仍会提交模块配置拉取原生壳）。
+
+### Task 1: 账号与证书就绪
+
+**Files:**
+- 不改仓库；材料落在 `~/Packaging/credentials/`
+
+- [ ] **Step 1: Apple Developer**
+
+准备：
+- Apple Developer 账号
+- App ID：`com.shelingxingqiu.arcx`
+- Distribution Certificate（.p12 + 密码）
+- App Store / Ad Hoc `mobileprovision`（按发布渠道选）
+
+- [ ] **Step 2: 导入钥匙串**
+
+```bash
+# 在打包机执行（路径按实际修改）
+security import ~/Packaging/credentials/ios_dist.p12 -k ~/Library/Keychains/login.keychain-db -P '<P12_PASSWORD>' -T /usr/bin/codesign
+```
+
+Expected: 钥匙串可见「Apple Distribution: …」证书，信任链完整。
+
+- [ ] **Step 3: 在 HBuilderX 配置打包证书**
+
+打开 `src/manifest.json` → App 模块配置 / iOS 打包配置，填入（**勿提交明文密码到 Git**）：
+- Bundle ID：`com.shelingxingqiu.arcx`
+- 证书路径、密码、profile 路径
+
+本地可用环境变量或 HBuilderX 图形界面填写；保持仓库内注释状态。
+
+- [ ] **Step 4: 验收清单**
+
+- [ ] Bundle ID 与 Profile 一致  
+- [ ] 隐私文案与实际上架用途一致（当前含相机/相册/定位/麦克风/跟踪，无用项建议上架前删减）  
+- [ ] 图标资源 `unpackage/res/icons/` 齐全  
+
+### Task 2: HBuilderX 打开 CLI 项目并首次安心打包
+
+**Files:**
+- Modify locally only: HBuilderX 打开 `/Users/ZhuanZ/Documents/gdfw/arcx-app`
+- Output: `unpackage/release/ipa/`（或 HBuilderX 提示目录）
+
+- [ ] **Step 1: 安装与 HBuilderX 编译器对齐的版本**
+
+对照 `package.json` 中 `@dcloudio/uni-app` 版本号 `3.0.0-alpha-4080620251107001`（对应 HX/编译器 4.08.06 一带），安装匹配的 [HBuilderX](https://www.dcloud.io/hbuilderx.html)。
+
+- [ ] **Step 2: 用 HBuilderX 打开项目根目录**
+
+确认能识别 `src/manifest.json`，appid 为 `__UNI__8A880C6`。
+
+- [ ] **Step 3: 发行 → 原生 App-云端打包，勾选安心打包**
+
+按 [SafePack](https://uniapp.dcloud.net.cn/tutorial/build/SafePack.html)：
+1. 首次：云端下发原生壳 → 本机合并代码 → 本机签名  
+2. 后续仅改前端且模块配置不变：本地复用壳，速度更快，且不占免费云打包次数  
+
+- [ ] **Step 4: 安装 ipa 到测试机或上传 TestFlight**
+
+Expected: 应用可启动；若提示 appkey/证书问题，回到 Task 1。
+
+- [ ] **Step 5: 记录打包机 SOP 一页纸**
+
+写入 `~/Packaging/scripts/export-note.md`：HBuilderX 版本、证书别名、Profile 名称、成功产物路径、耗时。
+
+---
+
+## Phase B：完整离线本地打包机（3–5 天）
+
+> 目标：不依赖云端原生壳；用离线 SDK + Xcode Archive 出包；可脚本化。
+
+### Task 3: 下载并对齐 iOS 离线 SDK
+
+**Files:**
+- Create: `~/Packaging/sdk/iOS-SDK-<ver>/`
+
+- [ ] **Step 1: 查编译器版本**
+
+在项目根目录：
+
+```bash
+cd /Users/ZhuanZ/Documents/gdfw/arcx-app
+# 若已配置 uni info 脚本则：
+npx uni -v
+# 或在 HBuilderX 中查看关于/编译器版本
+```
+
+Expected: 记下与导出资源一致的版本号字符串。
+
+- [ ] **Step 2: 下载同版本 iOS 离线 SDK**
+
+从 [SDK 下载页](https://nativesupport.dcloud.net.cn/AppDocs/download/ios)（以官网当前入口为准）下载，解压到 `~/Packaging/sdk/`。
+
+目录应含：
+- `HBuilder-Hello` — 打包工程  
+- `Feature-iOS.xls` — 模块依赖表  
+- `SDK` — 库与资源  
+- （新版）`uniapp.podspec` / 示例 `Podfile`
+
+- [ ] **Step 3: 版本一致性门禁**
+
+建立检查表：`编译器版本` = `SDK 发布版本` = `HBuilderX 导出资源所用版本`。三者任一不一致禁止出生产包。
+
+### Task 4: 申请并写入 dcloud_appkey
+
+**Files:**
+- Modify (Xcode 工程): `HBuilder-Hello/.../Info.plist`
+- 参考：[usesdk/ios 配置 Appkey](https://nativesupport.dcloud.net.cn/AppDocs/usesdk/ios)
+
+- [ ] **Step 1: 在 DCloud 开发者中心申请 Appkey**
+
+绑定：
+- DCloud appid：`__UNI__8A880C6`
+- Bundle ID：`com.shelingxingqiu.arcx`
+
+- [ ] **Step 2: Info.plist 增加**
+
+```xml
+<key>dcloud_appkey</key>
+<string>YOUR_DCLOUD_APPKEY</string>
+```
+
+- [ ] **Step 3: 同步修改 control.xml 中的 appid 与 Bundle ID**
+
+Expected: 真机运行不再提示 appkey 错误。
+
+### Task 5: HBuilderX 导出本地打包资源并导入工程
+
+**Files:**
+- Output from HX: 通常在项目 `unpackage/resources/` 或发行提示路径下的 www/app 资源
+- Modify: `HBuilder-Hello` 内 Pandora/apps 资源目录
+
+- [ ] **Step 1: 导出**
+
+HBuilderX → 发行 → **原生 App-本地打包** → **生成本地打包 App 资源**  
+（CLI 项目必须这一步，见[官方说明](https://nativesupport.dcloud.net.cn/AppDocs/importfeproject/export.html)）
+
+- [ ] **Step 2: 拷贝资源进 HBuilder-Hello**
+
+按官方「导入前端资源」文档：将导出的应用资源放到原生工程 `Pandora/apps/<appid>/www`（目录名 = appid）。
+
+建议脚本骨架 `~/Packaging/scripts/sync-www.sh`：
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+APPID="__UNI__8A880C6"
+SRC="${1:?usage: sync-www.sh <exported_www_dir>}"
+DST="$HOME/Packaging/workspace/HBuilder-Hello/HBuilder/Pandora/apps/${APPID}/www"
+rm -rf "$DST"
+mkdir -p "$DST"
+cp -R "$SRC"/. "$DST"/
+echo "synced -> $DST"
+```
+
+> 实际 `Pandora` 相对路径以当次 SDK 示例工程为准，首次手工核对后再固化脚本。
+
+- [ ] **Step 3: 合并 `nativeResources/ios`**
+
+将仓库 `nativeResources/ios/info.plist` 中的键（如 `NSUserTrackingUsageDescription`）合并进 Xcode Info.plist；有 `Resources` 时拷入 Bundle Resources。
+
+### Task 6: 配置 Xcode Identity、模块与签名
+
+**Files:**
+- Modify: Xcode Target `HBuilder` General / Signing / Info.plist /（新版）Podfile
+
+- [ ] **Step 1: Identity**
+
+| 字段 | 值 |
+|------|-----|
+| Display Name | ARCX |
+| Bundle Identifier | `com.shelingxingqiu.arcx` |
+| Version | `0.1.1`（随 `manifest.versionName`） |
+| Build | `101`（随 `manifest.versionCode`） |
+
+同时打开工程内 `manifest`，使 name/version 与上表一致。
+
+- [ ] **Step 2: 模块精简**
+
+本项目 `manifest.app-plus.modules` 当前为空 → 离线工程只保留基础能力。  
+若后续加支付/推送/登录，按 `Feature-iOS.xls` 或 `Podfile` 的 `uniapp_subspecs` 开启，再 `pod install`。
+
+```bash
+cd ~/Packaging/workspace/HBuilder-Hello
+pod install
+open HBuilder-Hello.xcworkspace   # 使用 Pods 时必须开 workspace
+```
+
+- [ ] **Step 3: Signing & Capabilities**
+
+- Team + Distribution 证书  
+- Release 使用正确 Provisioning Profile  
+- 需要 ATT 时已有隐私描述；按需加 Associated Domains 等  
+
+- [ ] **Step 4: 真机 Run 冒烟**
+
+Expected: App 启动到首页 Tab，无「版本不一致 / appkey 错误」弹窗。
+
+### Task 7: Archive 出包与上传
+
+**Files:**
+- Create: `~/Packaging/scripts/archive.sh`
+- Output: `~/Packaging/artifacts/ipa/`
+
+- [ ] **Step 1: GUI 首次 Archive**
+
+Xcode → Product → Archive → Distribute App → 导出 ipa（App Store Connect 或 Ad Hoc）。
+
+- [ ] **Step 2: 固化命令行（打包机自动化）**
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+WS="$HOME/Packaging/workspace/HBuilder-Hello/HBuilder-Hello.xcworkspace"
+SCHEME="HBuilder"
+OUT="$HOME/Packaging/artifacts/ipa"
+ARCHIVE="$OUT/ARCX.xcarchive"
+EXPORT_PLIST="$HOME/Packaging/scripts/ExportOptions.plist"
+
+xcodebuild -workspace "$WS" -scheme "$SCHEME" \
+  -configuration Release -archivePath "$ARCHIVE" archive
+
+xcodebuild -exportArchive -archivePath "$ARCHIVE" \
+  -exportOptionsPlist "$EXPORT_PLIST" -exportPath "$OUT"
+```
+
+`ExportOptions.plist` 首次用 Xcode 导出后从 Organizer 旁路生成，或按 Apple 文档手写 `method=app-store-connect`。
+
+- [ ] **Step 3: 上传**
+
+使用 **Transporter** 上传 ipa 至 App Store Connect（[官方](https://nativesupport.dcloud.net.cn/AppDocs/package/ios.html)）。
+
+- [ ] **Step 4: 打生产包前检查**
+
+- [ ] `control.xml` **去掉** `debug="true"` / `syncDebug="true"`（自定义基座调试用，留着会导致热更新等问题）  
+- [ ] Version/Build 已递增  
+- [ ] 隐私清单（SDK 4.13+ 示例工程含基础 PrivacyInfo）已按模块补齐  
+
+---
+
+## Phase C：打包机运维与门禁（持续）
+
+### Task 8: 目录权限、密钥与备份
+
+- [ ] **Step 1:** `credentials/` 放加密卷或 1Password；**禁止进 Git**  
+- [ ] **Step 2:** `.gitignore` 确认忽略 `unpackage/release/`、本地 p12、profile  
+- [ ] **Step 3:** 每月检查：Apple 证书过期日、HBuilderX/SDK 升级窗口、Xcode 与 macOS 兼容性  
+
+### Task 9: 版本升级流程（强制）
+
+每次升级编译器：
+
+1. 升级 HBuilderX / 项目 `@dcloudio/*` 依赖  
+2. 下载**同版本** iOS 离线 SDK  
+3. 重新导出资源  
+4. Diff `HBuilder-Hello` 与新 SDK 示例工程（Pods、隐私清单、基础库）  
+5. 再 Archive  
+
+### Task 10: 验收标准（Definition of Done）
+
+- [ ] 安心打包：本机产出可安装 ipa（Phase A）  
+- [ ] 离线打包：Xcode Archive 产出 ipa，安装后无版本/appkey 弹窗（Phase B）  
+- [ ] 同一 commit 资源可重复出包（脚本化 sync + archive）  
+- [ ] 证书与密码不在仓库中  
+- [ ] 有一页 SOP：版本号对齐表 + 出包命令 + 回滚方式  
+
+---
+
+## 推荐落地节奏
+
+| 周次 | 交付 |
+|------|------|
+| Day 1 | 证书/Profile + HBuilderX 打开项目 + 安心打包首包 |
+| Day 2 | TestFlight/真机验收；写 SOP；决定是否上离线 |
+| Day 3–4 | 下载对齐 SDK、Appkey、导出资源、Xcode Identity/签名 |
+| Day 5 | Archive 脚本化 + Transporter；自定义基座（可选） |
+
+**默认建议：** ARCX 现阶段模块少、无付费原生插件 → **先 Phase A（安心打包）**；若合规要求「完全不碰云原生壳」或要 CI Archive，再上 Phase B。
+
+---
+
+## 风险与明确不做
+
+| 风险 | 应对 |
+|------|------|
+| 编译器与 SDK 版本不一致 | 出包前硬门禁，禁止混用 |
+| CLI 无法直接导出本地资源 | 打包机必须装 HBuilderX |
+| 离线无法用付费 uni 原生插件 / 原生混淆 | 评估插件策略；必要时改安心/传统云包 |
+| manifest 隐私项过多导致审核追问 | 上架前按真实能力删减 |
+| p12 密码曾出现在历史注释 | 已注释路径勿回填到 Git；轮换证书 |
+
+---
+
+## Self-Review
+
+1. **Spec coverage：** 官网离线流程（版本对齐、Appkey、导出资源、Xcode 配置、证书、Archive、Transporter）与安心打包路径均有 Task；本仓库 Bundle ID/appid/nativeResources 已映射。  
+2. **Placeholder scan：** 脚本中的路径以 SDK 实际目录为准，首次需人工核对后固化（已标明）。  
+3. **一致性：** Bundle ID 全程使用 `com.shelingxingqiu.arcx`；DCloud appid 全程 `__UNI__8A880C6`。