Files

T

2026-08-07 18:31:37 +08:00

16 KiB

Raw Blame History

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 官网 → 发布 → 原生 App（离线）
离线 SDK 总入口：nativesupport AppDocs
iOS 开发环境/工程配置：usesdk/ios
导出前端资源：importfeproject/export
证书/Archive/上传：package/ios
iOS 原生资源（Info.plist 等）：app-nativeresource-ios
安心打包（Mac 本地签）：SafePack
模块/Pod 集成（5.13+）：iOSModuleConfig/common

官网结论摘要（先读再落地）

两条「本地」路径不要混

路径	本质	证书/前端代码	限制	适合
安心打包	云端生成原生壳，本机合并代码并签名	不上传代码与证书	非纯离线；改模块配置会重新拉壳；付费原生插件/原生混淆能力受限场景见文档	日常出包、Mac 打包机首选起步
离线打包	下载 iOS 离线 SDK，用 Xcode 本地编签	全程本机	无原生混淆；付费 uni 原生插件不可用；须申请 `dcloud_appkey`；编译器版本必须与 SDK 一致	强合规、深度原生定制、CI Archive

离线打包标准流水线（官方）

版本对齐：HBuilderX / npm run info 的编译器版本 ≡ 离线 SDK 版本（不一致会弹窗且功能异常）。
申请 Appkey（SDK ≥ 3.1.10）：在 Info.plist 配置 dcloud_appkey；Bundle ID + control.xml 中 appid 必须与申请一致。
导出资源：HBuilderX → 发行 → 原生 App-本地打包 → 生成本地打包 App 资源。
- vue-cli 项目不能用纯 CLI 导出，必须用 HBuilderX 打开项目再导出。
- manifest.json 的 appid 不能手填空值，须由 HBuilderX 获取（本仓库已有 __UNI__8A880C6）。
配置 Xcode 工程（HBuilder-Hello）：
- Bundle ID / Display Name / Version / Build
- 与导出资源中的 manifest、control.xml appid 对齐
- 图标、LaunchScreen、隐私描述、所需模块（参考 Feature-iOS.xls；新版推荐 CocoaPods uniapp_subspecs）
- 合并项目内 nativeResources/ios（离线时需手动合并进 Xcode）
Signing：生产证书 + Distribution Profile（与 Bundle ID 绑定）。
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+」门槛

文件与目录约定（打包机）

建议在打包机固定目录（示例，可按团队规范改）：

~/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: 导入钥匙串

# 在打包机执行（路径按实际修改）
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。

Step 2: 用 HBuilderX 打开项目根目录

确认能识别 src/manifest.json，appid 为 __UNI__8A880C6。

Step 3: 发行 → 原生 App-云端打包，勾选安心打包

按 SafePack：

首次：云端下发原生壳 → 本机合并代码 → 本机签名
后续仅改前端且模块配置不变：本地复用壳，速度更快，且不占免费云打包次数

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: 查编译器版本

在项目根目录：

cd /Users/ZhuanZ/Documents/gdfw/arcx-app
# 若已配置 uni info 脚本则：
npx uni -v
# 或在 HBuilderX 中查看关于/编译器版本

Expected: 记下与导出资源一致的版本号字符串。

Step 2: 下载同版本 iOS 离线 SDK

从 SDK 下载页（以官网当前入口为准）下载，解压到 ~/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
Step 1: 在 DCloud 开发者中心申请 Appkey

绑定：

DCloud appid：__UNI__8A880C6
Bundle ID：com.shelingxingqiu.arcx
Step 2: Info.plist 增加

<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 项目必须这一步，见官方说明）

Step 2: 拷贝资源进 HBuilder-Hello

按官方「导入前端资源」文档：将导出的应用资源放到原生工程 Pandora/apps/<appid>/www（目录名 = appid）。

建议脚本骨架 ~/Packaging/scripts/sync-www.sh：

#!/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。

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: 固化命令行（打包机自动化）

#!/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（官方）。

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: 版本升级流程（强制）

每次升级编译器：

升级 HBuilderX / 项目 @dcloudio/* 依赖
下载同版本 iOS 离线 SDK
重新导出资源
Diff HBuilder-Hello 与新 SDK 示例工程（Pods、隐私清单、基础库）
再 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；自定义基座（可选）

风险与明确不做

风险	应对
编译器与 SDK 版本不一致	出包前硬门禁，禁止混用
CLI 无法直接导出本地资源	打包机必须装 HBuilderX
离线无法用付费 uni 原生插件 / 原生混淆	评估插件策略；必要时改安心/传统云包
manifest 隐私项过多导致审核追问	上架前按真实能力删减
p12 密码曾出现在历史注释	已注释路径勿回填到 Git；轮换证书

Self-Review

Spec coverage： 官网离线流程（版本对齐、Appkey、导出资源、Xcode 配置、证书、Archive、Transporter）与安心打包路径均有 Task；本仓库 Bundle ID/appid/nativeResources 已映射。
Placeholder scan： 脚本中的路径以 SDK 实际目录为准，首次需人工核对后固化（已标明）。
一致性： Bundle ID 全程使用 com.shelingxingqiu.arcx；DCloud appid 全程 __UNI__8A880C6。

16 KiB Raw Blame History Unescape Escape

ARCX iOS 本地打包机落地计划

官网结论摘要（先读再落地）

两条「本地」路径不要混

离线打包标准流水线（官方）

与本仓库的映射

文件与目录约定（打包机）

Phase A：Mac 安心打包机（1–2 天，先打通）

Task 1: 账号与证书就绪

Task 2: HBuilderX 打开 CLI 项目并首次安心打包

Phase B：完整离线本地打包机（3–5 天）

Task 3: 下载并对齐 iOS 离线 SDK

Task 4: 申请并写入 dcloud_appkey

Task 5: HBuilderX 导出本地打包资源并导入工程

Task 6: 配置 Xcode Identity、模块与签名

Task 7: Archive 出包与上传

Phase C：打包机运维与门禁（持续）

Task 8: 目录权限、密钥与备份

Task 9: 版本升级流程（强制）

Task 10: 验收标准（Definition of Done）

推荐落地节奏

风险与明确不做

Self-Review

16 KiB

Raw Blame History