appuploader 命令行教程

摘要

appuploader-cli 是开心上架（Appuploader）的命令行工具，可以在 Windows、Linux、macOS 上通过命令完成 iOS 上架的全部工作：登录账号、注册 Bundle ID、签发证书、生成描述文件、在 App Store Connect 新建 App、上传 IPA、导入元数据与截图、提交审核和 TestFlight 分发。本文介绍它的安装位置、登录方式、常用命令和一键发布流程，以及在 CI 和 AI agent 中的用法。全部命令的完整说明见 appuploader-cli 命令手册。

🔑 推荐登录方式：Apple ID + App 专用密码

用 App 专用密码登录不会触发双重验证，功能最全，还能随时单独吊销。脚本、CI 和 AI agent 都推荐这样登录。生成方法见第三节。

一、在哪里找到 appuploader-cli

appuploader-cli 随开心上架主程序一起分发，不需要单独下载。装好主程序后，它就在安装目录里：

系统 路径
macOS AppUploader.app/Contents/Resources/appuploader-cli
Windows 主程序 AppUploader.exe 同目录下的 appuploader-cli.exe
Linux 主程序 AppUploader 同目录下的 appuploader-cli

建议把这个目录加入系统的 PATH，之后在任意目录都能直接运行 appuploader-cli。

appuploader-cli 与开心上架客户端共用数据目录 ~/appuploader-data-v6/。在客户端里登录过的账号，命令行可以直接使用，反过来也一样。

appuploader-cli 使用 appuploader 的授权，无需单独额外授权。

二、五分钟上手

 1# 1. 用 Apple ID 和 App 专用密码登录（推荐，不会触发双重验证）
 2APPLE_PW='xxxx-xxxx-xxxx-xxxx' appuploader-cli login --apple-id dev@example.com --password-env APPLE_PW --alias dev
 3
 4# 2. 在 App 工程目录生成项目配置，按需编辑
 5appuploader-cli init --bundle-id com.example.app --name "My App"
 6
 7# 3. 体检，预演，发布
 8appuploader-cli doctor --for-release
 9appuploader-cli release --dry-run
10appuploader-cli release

每条命令都有说明和示例，执行 appuploader-cli <命令> --help 即可查看。

三、登录账号

登录一次后会话保存在数据目录，后续命令直接复用。

🔑 推荐登录方式：Apple ID + App 专用密码

App 专用密码不是 Apple ID 登录密码，而是 Apple 为第三方工具单独生成的 xxxx-xxxx-xxxx-xxxx 格式密码。用它登录不会触发双重验证，新建 App、签协议、定价、隐私标签等全部操作都能做。

推荐：Apple ID + App 专用密码

推荐用它登录，原因有三点：

  • 不会触发双重验证，脚本、CI 和 AI agent 都能无人值守地登录。
  • 功能最全，新建 App、签协议、定价、隐私标签等全部操作都能做。
  • 可以随时单独吊销，泄露了也不影响 Apple ID 本身。

生成方法：

  1. 用 Apple ID 登录 account.apple.com（账号管理）。
  2. 在「登录与安全」中找到「App 专用密码」，点击生成，名称随意填写。
  3. 复制生成的密码。密码只显示一次，请立即保存。生成前账号需要已开启双重验证。

带截图的详细步骤见 生成专用密码。

登录时把密码放在环境变量里，用 --password-env 指定变量名，工具会按格式自动识别这是 App 专用密码：

1APPLE_PW='xxxx-xxxx-xxxx-xxxx' appuploader-cli login --apple-id dev@example.com --password-env APPLE_PW --alias dev

其他登录方式

账号 登录方式 说明
Apple ID + 普通密码 同上，密码填 Apple ID 登录密码 可能触发双重验证
App Store Connect API Key --api-key-file AuthKey_X.json，或 --api-key-id + --api-issuer-id + --api-key-path AuthKey_X.p8 不会遇到双重验证，但 Apple 官方 API 不支持新建 App、签协议、隐私标签等操作
免费 Apple ID 加 --free 没有付费开发者账号时使用，管理证书、Bundle ID、描述文件和设备

双重验证：用普通密码登录时，终端里会直接提示输入验证码。脚本中可以用 --2fa-code 123456 传入，或用 --2fa-from-file /tmp/code.txt 让登录进程等待另一个进程把验证码写入该文件。改用 App 专用密码就不会遇到这个问题。

常用的账号命令：

1appuploader-cli account list        # 已登录账号及会话是否有效
2appuploader-cli whoami              # 当前将以哪个账号、哪个团队执行
3appuploader-cli team list           # 列出团队
4appuploader-cli team use <team-id>  # 设定默认团队
5appuploader-cli logout              # 清除会话

四、上传 IPA

只需要上传 IPA 时，登录后一条命令即可：

1appuploader-cli build upload ./build/MyApp.ipa
2appuploader-cli build wait <构建号> --timeout 45m   # 等待 Apple 处理完成

旧版本的 appuploader-cli upload -f x.ipa -u … -p … 写法仍然可用，推荐改为先 login 再 build upload。

五、证书、描述文件与设备

1appuploader-cli bundle create com.example.app --name "My App" --cap PUSH_NOTIFICATIONS   # 注册 Bundle ID 并补齐权限
2P12_PW=… appuploader-cli cert create --type IOS_DISTRIBUTION --out ./signing --p12-password-env P12_PW   # 签发发布证书，输出 .p12
3appuploader-cli device import devices.txt                                  # 批量导入测试设备
4appuploader-cli profile create "MyApp AppStore" --type IOS_APP_STORE --out ./signing   # 生成描述文件
5appuploader-cli signing                                                    # 按项目配置一次准备好全部签名资源
  • cert create 会优先复用有效的证书，没有才签发新的，私钥在本地生成，.p12 用环境变量里的密码保护。
  • profile create 自动挑选证书和设备，已有且匹配就复用，过期则重建。

六、一键发布 release

release 按项目配置 appuploader.yaml 跑完整个上架流程：

preflight → bundle → certs → profiles → app → version → upload → metadata → screenshots → custom-pages
→ build-wait → compliance → review-info → gamecenter → iap → pricing → privacy → submit → testflight
  • 每一步都可以重复执行：已存在的跳过，有效的证书复用，已上传的构建不会重复上传。
  • 中途失败后，重新执行同一条命令就从失败的那一步继续。--restart 从头开始，--from <步骤> 指定起点。
  • --dry-run 只读不写，报告每一步会做什么。
  • --skip、--only、--from、--to 可以裁剪要执行的步骤。
  • 内购、定价、隐私标签、TestFlight 等可选步骤，只在项目配置里写了对应内容时才执行。
  • 发布不在流水线里。 发布类型为手动时，审核通过后由你自己执行 appuploader-cli version publish <版本号>。

七、元数据、截图与素材库

1appuploader-cli init --from-app                      # 把线上元数据导出到本地，方便用 git 管理
2appuploader-cli metadata import                      # 导入元数据，只写目录中存在且非空的字段
3appuploader-cli screenshot upload ./screenshots/     # 截图按像素尺寸自动归入机型
4appuploader-cli asset place --locale en-US ./duo/    # 素材库：替换该语言的 iPhone Duo 截图
5appuploader-cli custom-page create "Spring" --from-version   # 以当前版本为模板新建自定产品页面

Apple 要求 2027 年 4 月起，提交审核必须带 iPhone Duo 截图。appuploader 已经支持。

八、在 CI 中使用

CI 里推荐用 Apple ID 加 App 专用密码，不会遇到双重验证。设置好下面的环境变量后，不需要先执行 login，命令会在需要时自动登录：

  • APPUPLOADER_APPLE_ID：Apple ID
  • APPUPLOADER_PASSWORD：App 专用密码

也可以改用 API Key，对应的环境变量是 APPUPLOADER_API_KEY_ID、APPUPLOADER_API_ISSUER_ID，以及 APPUPLOADER_API_KEY_P8（.p8 的内容）或 APPUPLOADER_API_KEY_PATH（.p8 的路径）。

1appuploader-cli release --json --yes

--json 模式下每一步输出一行 JSON，失败时带有是否可重试和下一条要执行的命令，方便流水线解析。

九、交给 AI agent

appuploader-cli 可以生成给 Claude Code、Codex 等 AI agent 使用的技能文件：

1appuploader-cli skill --install user                  # 安装到 Claude Code，所有项目可用
2appuploader-cli skill --install project               # 只对当前项目生效
3appuploader-cli skill --format agents >> AGENTS.md    # 给其他 agent 的说明文件

技能文件写明了使用规则、退出码与重试策略、常用流程和完整命令索引。安装后直接用自然语言告诉 agent 要发布什么版本即可。升级工具后重新生成一次。

十、完整命令手册

本文只介绍最常用的命令。appuploader-cli 的全部命令，以及每条命令的全部参数和示例，见 appuploader-cli 命令手册。