391 lines
16 KiB
Markdown
391 lines
16 KiB
Markdown
# 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`。
|