App Store Connect 对大多数 API 请求拒绝有效期超过 20 分钟的 JWT。这个限制意味着自动化流程需要按需生成令牌，不意味着每次发布都要手动登录。结论：优先为 fastlane 已支持的操作配置 API Key；只有目标 action 不支持 API Key 时，才为对应任务保留 Apple ID 认证。上传构建、更新商店资料和 TestFlight 分发要分别核对支持范围。(Apple 的 JWT 有效期规则)
适合准备把手动发布改为自动化的独立开发者；需要在远程 Mac 或 CI 上维护发布流程的小型团队；以及正在厘清 API Key 权限或 Apple ID 登录要求的 fastlane 维护者。
01 先核对 fastlane 每个发布动作的认证支持
fastlane 的支持矩阵列出各工具对 API Key 与 Apple ID 的支持情况：deliver、pilot、sigh、cert、match 支持 API Key；produce 仅部分支持且不支持 API Key；pem 不支持 API Key；precheck 支持 API Key，但应用内购买（IAP）检查有例外。(fastlane App Store Connect API 支持矩阵)
| 发布任务 | API Key 适用判断 | 需要继续核实 |
|---|---|---|
| 更新商店元数据或截图 | deliver 支持 |
具体字段及调用的 action |
| 上传 App 二进制 | 有 API Key 相关上传路径 | deliver 使用的传输工具和上传记录 |
| TestFlight 上传或管理 | pilot 支持 |
上传、分发和测试者管理是不同操作 |
| 其他发布步骤 | 取决于对应工具 | 对照支持矩阵和目标 action 文档 |
deliver 是 upload_to_app_store 的别名，可处理截图、预览视频、元数据和二进制；TestFlight 工作流则由 pilot 等工具处理。配置发布 lane 时，把这些操作拆开核对。元数据更新成功，不代表二进制上传或测试者分发也使用了相同认证方式。(fastlane deliver action 文档)
例如，upload_app_privacy_details_to_app_store 使用的 API 不在官方 App Store Connect API 中，因此该 action 不能使用 API Key。把这类步骤作为单独的兼容性例外处理，不必因此放弃整条发布流程中的 API Key。(fastlane 隐私详情 action 说明)
02 API Key 权限边界：Key 类型、角色和 App 范围
Apple 区分 Team Key 与 Individual Key。Team Key 可按角色授予权限，但访问范围涵盖团队下的所有 App，不能限制为单个 App。Individual Key 继承关联用户的角色和 App 访问范围；它不能访问 Provisioning 端点、Sales、Finance 和 notaryTool。(Apple API Key 创建、类型与权限说明)
选择 Key 时，先核对发布任务需要哪些操作，再判断团队是否接受 Team Key 覆盖所有 App。如果要求按 App 隔离，应检查关联用户的 Individual Key 是否适用；不要把 Team Key 当成可按单个 App 限权的凭据。
角色也要按任务核对。构建上传所需角色包括 Account Holder、Admin、App Manager 或 Developer。上传权限不等于所有元数据管理操作都已获授权。遇到权限错误时，逐项检查 Key 类型、角色、用户或 App 访问范围，以及当前 fastlane action 是否支持 API Key。(Apple 的上传构建角色要求)
03 私钥和 Apple ID 凭据的保管差异
API Key 的认证材料包括 .p8 私钥与 Key ID；Team Key 还使用 Issuer ID。私钥用于签署 JWT，Key ID 标识对应密钥，Issuer ID 用于 Team Key 的令牌信息。Individual Key 的令牌字段不同，不要照搬 Team Key 配置。Apple 说明私钥只能下载一次，并要求像密码一样保护；不要提交到代码仓库，也不要放进客户端代码。创建 Key 时应遵循 Apple 的密钥保管说明，尤其要控制私钥的存取范围。
Apple ID 认证则涉及账号凭据、双重认证和会话维护。fastlane 文档说明，CI 可通过环境变量 FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD 提供应用专用密码用于二进制上传；但如果操作包含更新元数据或向测试者分发，这种密码不能替代相应认证方式。(fastlane 认证与应用专用密码说明)
两类凭据都应与代码和日志隔离。把凭据放入 CI 秘密变量或受控密钥存储，并限制可读取凭据的账号。人员交接或怀疑泄露时，撤销旧凭据并替换；不要把真实值复制到工单、示例配置或聊天记录。示例中只保留占位符：
key_id: "<KEY_ID>"
issuer_id: "<ISSUER_ID>"
key_filepath: "<PATH_TO_P8>"
⚠️ 不要把真实
.p8内容、Apple ID 密码或应用专用密码写进Fastfile、仓库文件或日志。用占位符检查配置样例，发布前再由受控环境注入真实凭据。
04 无人值守任务的认证稳定性
对持续运行的发布任务，如果目标 action 支持 API Key，通常应先采用它。API Key 可减少自动化流程对双重认证交互的依赖；但这不会让未接入 API Key 的 action 自动获得兼容性。fastlane 支持矩阵、action 文档和实际 lane 必须逐项对得上。
Apple 对大多数请求拒绝有效期超过 20 分钟的 JWT。fastlane 的 API Key 配置示例把 duration 上限设为 1200 秒。令牌有效期与 .p8 私钥是否泄露是不同问题：按需生成短期令牌，仍须妥善保管私钥。不要为了减少令牌刷新而无限延长有效期，也不要把令牌到期与私钥生命周期混为一谈。
如果某一步必须使用 Apple ID，先确认是否需要处理双重认证、会话更新和 CI 环境中的秘密变量。应用专用密码只适用于 fastlane 文档说明的二进制上传场景，不能据此推断它可以更新元数据、分发测试版或执行所有 App Store Connect 操作。
05 发布验收要分开看认证、上传与处理状态
终端显示认证成功，只能说明认证这一步通过。发布验收还要分别确认二进制已传输、Apple 已处理构建，以及版本是否进入 TestFlight 或审核流程。Apple 说明，上传后的构建需要经过系统处理后才会显示在 App Store Connect 中。
上传方式也需单独检查。Apple 列出 Transporter 命令行工具等二进制上传方式，并说明上传后要在 App Store Connect 查看构建状态。使用 JWT 完成上传，不代表元数据更新、测试者分发或审核提交也已完成。(Apple 上传构建与处理状态说明)
06 迁移认证前逐项验收
- [ ] 列出 lane 中的实际操作：构建上传、元数据和截图更新、TestFlight 分发、提交审核，以及额外的签名或隐私相关 action。
- [ ] 对照 fastlane 支持矩阵，为每个 action 标注 API Key、Apple ID 或待验证；不支持 API Key 的步骤单独处理。
- [ ] 按实际任务选择最低所需角色，并确认 Team Key 的全 App 访问范围是否符合团队要求。
- [ ] 将
.p8、Key ID、Issuer ID 或 Apple ID 认证材料放入受控秘密存储；检查代码仓库和日志，确保没有真实凭据。 - [ ] 用脱敏项目或非正式发布任务运行目标 lane，确认执行环境可以读取凭据，且目标 action 确实可执行。
- [ ] 在 App Store Connect 核对上传记录、构建处理状态及 TestFlight 或审核状态；分别记录结果，不以终端成功信息代替交付验收。
远程 Mac 发布容易遗漏的不是认证选项，而是执行环境能否读取秘密变量、lane 是否覆盖所有目标 action，以及上传后是否有人核验构建状态。如果你依赖个人 Mac，可能遇到机器不在线、交互式验证难以无人值守、凭据与日常开发环境混放等问题；非 macOS 主机也无法直接替代 Xcode 发布环境。
需要临时补齐 macOS 发布环境时，先根据实际 lane 验证权限和交付边界，再了解 CALMVPS 的远程 Mac 环境与套餐计费信息。如果你需要长期稳定占用专用设备，或依赖本地物理接口，自购 Mac 可能更合适；租赁更适合按需获得远程 Mac 环境的发布与测试任务。