Apple App Store

Apple App Store 是 iOS 应用的官方分发渠道。Flu CLI 支持三种发布模式：正式版上架、TestFlight 测试分发、Ad Hoc 安装包导出。

✨ 平台特点

• 三种模式：App Store 正式版、TestFlight 测试、Ad Hoc 内部分发
• 双认证方式：Apple ID + App Password（简单）或 API Key（推荐自动化）
• 自动化发行说明：通过 API Key 可自动更新 App Store Connect 中的发行说明
• TestFlight 分发：支持自动通知测试员、多语言测试信息

🔑 获取凭证

方式 1：Apple ID + App-specific Password（简单快速）

1. 登录 Apple ID 管理页面
2. 进入 登录与安全 → App 专用密码
3. 点击 生成 App 专用密码，输入标签（如 "flu-cli"）
4. 复制生成的密码（格式如 xxxx-xxxx-xxxx-xxxx）

方式 2：API Key（推荐用于自动化和 TestFlight）

1. 登录 App Store Connect
2. 进入 用户与访问 → 密钥 → App Store Connect API
3. 点击 生成 API 密钥，选择「Admin」角色
4. 记录：
   • Key ID（10 位字母数字）
   • Issuer ID（UUID 格式）
5. 下载 .p8 私钥文件（仅能下载一次！）

⚠️ .p8 私钥文件只能下载一次，请妥善保管。丢失后只能重新生成。

📝 配置示例

App Store 正式版

publish:
  app_store:
    enable: true
    mode: 'app_store'
    appId: '123456789'
    auth:
      appleId: '${APPLE_ID}'
      appPassword: '${APPLE_APP_PASSWORD}'

App Store + 自动更新发行说明

publish:
  app_store:
    enable: true
    mode: 'app_store'
    appId: '123456789'
    auth:
      appleId: '${APPLE_ID}'
      appPassword: '${APPLE_APP_PASSWORD}'
      # API Key 用于自动更新发行说明
      apiKeyId: '${APPLE_API_KEY_ID}'
      apiIssuerId: '${APPLE_API_ISSUER_ID}'
      privateKeyPath: './AuthKey_ABC123.p8'

TestFlight 测试分发

publish:
  app_store:
    enable: true
    mode: 'testflight'
    auth:
      apiKeyId: '${APPLE_API_KEY_ID}'
      apiIssuerId: '${APPLE_API_ISSUER_ID}'
      privateKeyPath: './AuthKey_ABC123.p8'
    testflight:
      betaTesters:
        - 'tester1@example.com'
        - 'tester2@example.com'
      betaBuildLocalization:
        - locale: 'zh-Hans'
          description: '修复已知问题，优化性能'
        - locale: 'en-US'
          description: 'Bug fixes and performance improvements'
      autoNotify: true

Ad Hoc 内部分发

publish:
  app_store:
    enable: true
    mode: 'adhoc'
    adhoc:
      teamId: 'ABCDE12345'
      exportOptions:
        method: 'ad-hoc'
        signingStyle: 'automatic'

配置字段

基础字段

字段	类型	必填	说明
enable	boolean	是	是否启用
mode	'app_store' | 'testflight' | 'adhoc'	是	发布模式
appId	string	否	App Store Connect 中的应用 ID（数字）

认证字段

字段	类型	说明
auth.appleId	string	Apple ID（邮箱）
auth.appPassword	string	App 专用密码
auth.apiKeyId	string	API Key ID（10 位）
auth.apiIssuerId	string	API Issuer ID（UUID）
auth.privateKeyPath	string	.p8 私钥文件路径
auth.privateKeyContent	string	.p8 私钥内容（PEM 格式，与 path 二选一）

TestFlight 字段（仅 mode: 'testflight'）

字段	类型	说明
testflight.betaTesters	string[]	测试员邮箱列表
testflight.betaBuildLocalization	object[]	多语言测试信息
testflight.betaBuildLocalization[].locale	string	语言代码（如 zh-Hans、en-US）
testflight.betaBuildLocalization[].description	string	该语言的版本说明
testflight.autoNotify	boolean	是否自动通知测试员（默认 true）

Ad Hoc 字段（仅 mode: 'adhoc'）

字段	类型	说明
adhoc.teamId	string	Apple Team ID
adhoc.provisioningProfileSpecifier	string	Provisioning Profile 名称
adhoc.signingIdentity	string	签名证书名称
adhoc.exportOptions.method	string	导出方式（ad-hoc）
adhoc.exportOptions.signingStyle	'automatic' | 'manual'	签名方式

📦 支持的文件类型

文件类型	说明
.ipa	iOS 安装包

❓ 常见问题

Q: App Store 和 TestFlight 可以同时启用吗？ A: 不能在同一次上传中同时使用两种模式，但你可以分两次运行，分别指定不同的 mode。

Q: 使用 Apple ID 方式上传提示认证失败？ A: 请确认：1) 使用的是「App 专用密码」而非 Apple ID 登录密码；2) 如果开启了双重认证，必须使用 App 专用密码。

Q: .p8 文件丢失了怎么办？ A: .p8 私钥文件只能下载一次。丢失后需要在 App Store Connect 中撤销旧密钥并创建新密钥。

Q: 上传成功但在 TestFlight 中看不到？ A: 上传后需要等待 Apple 处理（通常几分钟到几十分钟），处理完成后会出现在 TestFlight 中。如果长时间未出现，请检查 App Store Connect 中的构建状态。

Q: Ad Hoc 模式需要什么前提？ A: 需要有效的 Apple Developer 账号、Ad Hoc Provisioning Profile，且测试设备的 UDID 已注册在 Profile 中。