用 asc xcode 归档、导出并上传 App…

当需要用 asc xcode helpers 构建、归档、导出 IPA/PKG，并上传到 App Store Connect、TestFlight 或做注册设备发布测试时，按此流程操作。

适用场景

解决思路

1. 优先使用 `asc xcode archive` 和 `asc xcode export`，而不是直接拼 raw `xcodebuild` 流程；只有当 `asc xcode archive --help` 或 `asc xcode export --help` 不覆盖项目特定选项时，才回退到 raw `xcodebuild`，并优先通过 `--xcodebuild-flag` 传额外参数。
2. 查看版本号：`asc xcode version view`。
3. 设置版本和构建号：`asc xcode version edit --version '1.3.0' --build-number '42'`。
4. 应用远程安全构建号：`asc xcode version edit --next-build-number --app 'APP_ID' --platform IOS`。
5. 递增构建号：`asc xcode version bump --type build`。
6. 递增补丁版本：`asc xcode version bump --type patch`。
7. 递增构建号并应用远程安全值：`asc xcode version bump --type build --next-build-number --app 'APP_ID' --platform IOS`。
8. 不在项目根目录时加 `--project-dir './MyApp'`。
9. 目录含多个项目时加 `--project './MyApp/App.xcodeproj'`。
10. 多 target 或多 configuration 时加 `--target 'App'` 和 `--configuration 'Release'`，以保证读取和写入确定性。
11. 为避免低 build-number 被拒，用一条命令解析并应用远程安全构建号：`asc xcode version edit --next-build-number --app 'APP_ID' --platform IOS --output json`。
12. 只查看远程安全值而不修改项目时，用 `asc builds next-build-number`。
13. 版本命令读取 project 与 xcconfig 设置且不启动 Xcode；当无法解析版本值时，默认 `--xcodebuild-settings-lookup auto` 会回退到 `xcodebuild -showBuildSettings` 并在 stderr 警告；必须禁止隐式启动 Xcode 的自动化中用 `--xcodebuild-settings-lookup never`。
14. 版本变更写入前会验证完整改动，并返回结构化输出标明更改的 configuration 和文件；编辑器会跟随递归 xcconfig includes 并保留无关 project/xcconfig 内容。
15. 仅做普通 simulator、device 或 CI 验证构建时用 `asc xcode build`，必须提供且只提供一个 project 或 workspace，以及一个 scheme。
16. 验证构建示例：`asc xcode build --project 'App.xcodeproj' --scheme 'App' --destination 'platform=iOS Simulator,name=iPhone 17 Pro Max,OS=27.0' --no-code-signing --result-bundle-path '.asc/artifacts/App.xcresult' --output json`。
17. `asc xcode build` 省略 `--derived-data-path` 时使用源码 checkout 外的稳定缓存；result bundle 目标目录必须尚不存在；Xcode 日志到 stderr，结构化结果到 stdout。
18. iOS/tvOS/visionOS 归档：`asc xcode archive --workspace 'App.xcworkspace' --scheme 'App' --configuration Release --clean --archive-path '.asc/artifacts/App.xcarchive' --xcodebuild-flag=-destination --xcodebuild-flag=generic/platform=iOS --output json`。
19. 仅 project 的 app 用 `--project 'App.xcodeproj'` 替代 `--workspace`。
20. 导出：默认 `asc xcode export` 生成 App Store Connect export options 并自动签名；未设置 `--wait` 时使用本地导出目标，设置后直接上传。示例：`asc xcode export --archive-path '.asc/artifacts/App.xcarchive' --ipa-path '.asc/artifacts/App.ipa' --xcodebuild-flag=-allowProvisioningUpdates --output json`。
21. 需要审查、复用或手动签名时，单独生成 plist：`asc xcode export-options generate --archive-path '.asc/artifacts/App.xcarchive' --output-path '.asc/ExportOptions.plist' --output json`。
22. 手动签名时加 `--signing-style manual`，可选 `--team-id 'TEAM_ID'`；替换已有文件需 `--overwrite`。
23. 要生成可安装到已注册设备的 IPA，使用 Xcode 当前 `release-testing` method；旧 `ad-hoc` 拼写已废弃且 asc 不接受。示例：`asc xcode export --archive-path '.asc/artifacts/App.xcarchive' --ipa-path '.asc/artifacts/App.ipa' --method release-testing --signing-style manual --team-id 'TEAM_ID' --output json`。
24. 需要审查或复用 release-testing plist 时单独生成：`asc xcode export-options generate --archive-path '.asc/artifacts/App.xcarchive' --method release-testing --signing-style manual --team-id 'TEAM_ID' --output-path '.asc/ExportOptions.release-testing.plist' --output json`。
25. `release-testing` 始终本地导出，不能与 `--wait` 组合。
26. 显式 `--export-options` plist 不能与 `--method`、`--signing-style` 或 `--team-id` 组合。
27. 设备/profile 协调、隔离签名、私有发布、可恢复性和实时验证，改用 `asc-ad-hoc-distribution` skill，不要手动拼这些阶段。
28. 通过 Xcode 直接上传并等待 App Store Connect 处理时，省略 `--export-options` 并加 `--wait`：`asc xcode export --archive-path '.asc/artifacts/App.xcarchive' --ipa-path '.asc/artifacts/App.ipa' --wait --output json`。
29. 上传已导出 IPA：`asc builds upload --app 'APP_ID' --ipa '.asc/artifacts/App.ipa' --wait`。
30. 分发到 TestFlight：`asc publish testflight --app 'APP_ID' --ipa '.asc/artifacts/App.ipa' --group 'GROUP_ID' --wait`。
31. 发布到 App Store：`asc publish appstore --app 'APP_ID' --ipa '.asc/artifacts/App.ipa' --version '1.2.3' --wait`。
32. 提交 App Store 审核：`asc publish appstore --app 'APP_ID' --ipa '.asc/artifacts/App.ipa' --version '1.2.3' --wait --submit --confirm`。
33. macOS App Store 归档：`asc xcode archive --project 'MacApp.xcodeproj' --scheme 'MacApp' --configuration Release --clean --archive-path '.asc/artifacts/MacApp.xcarchive' --xcodebuild-flag=-destination --xcodebuild-flag=generic/platform=macOS --output json`。
34. macOS 导出产生 `.pkg` 时用 helper 导出：`asc xcode export --archive-path '.asc/artifacts/MacApp.xcarchive' --pkg-path '.asc/artifacts/MacApp.pkg' --xcodebuild-flag=-allowProvisioningUpdates --output json`。
35. 上传 `.pkg`：`asc builds upload --app 'APP_ID' --pkg '.asc/artifacts/MacApp.pkg' --version '1.0.0' --build-number '123' --wait`。
36. `.pkg` 上传必须提供 `--version` 和 `--build-number`，因为它们不像 IPA metadata 会自动提取；项目需要自定义导出配置时加 `--export-options 'ExportOptions.plist'`。
37. raw xcodebuild fallback 先跑 `xcodebuild -showBuildSettings -scheme 'App'`。
38. 导出时 bundle ID 无 profiles：给 `asc xcode export` 加 `--xcodebuild-flag=-allowProvisioningUpdates`；确认 Apple ID 已登录 Xcode；用 `asc-signing-setup` skill 验证 profiles。
39. CFBundleVersion too low：运行 `asc xcode version edit --next-build-number --app 'APP_ID' --platform IOS`，然后重新构建并上传。
40. 构建因缺少 macOS icon 被拒：macOS 需要所有必需尺寸的 ICNS 图标；修复 asset catalog，重新构建，再导出/上传。
41. 默认生成的 export method 仍是 `app-store-connect`；要安装到已注册设备时显式请求 `--method release-testing`。
42. 仅在有意替换现有本地 artifacts 时使用 `--overwrite`。
43. 当下一步依赖已处理构建时，在 upload/publish 路径使用 `--wait`。
44. 检查提交就绪状态时使用 `asc-submission-health`。

适用边界 · 注意事项

• 没有安装 Xcode 和命令行工具、没有可用签名身份/provisioning profile 且未启用自动签名，或需要上传/查询构建但未配置 App Store Connect 认证时，不适用此流程。
• 项目特定选项无法通过 `asc xcode archive`、`asc xcode export` 或 `--xcodebuild-flag` 覆盖时，才考虑 raw `xcodebuild`；否则不要回退。
• 需要设备/profile 协调、隔离签名、私有发布、可恢复性和实时验证时，改用 `asc-ad-hoc-distribution` skill，而不是手动拼这些阶段。