Windows 怎么把 iOS App 上架 App Store？kxstore 命令行上架全流程

kxstore 命令的用法是 kxstore <命令> [参数]，负责 App Store Connect 这一侧的全部工作：用 API 密钥登录，注册 Bundle ID、签发证书和描述文件，上传 ipa，导入元数据和截图，提交审核，TestFlight 分发，内购与定价；release 一条命令按顺序跑完整个上架流程。它随 KXBuild 一起安装（kxbuild doctor 会装好），在 Windows、Linux、macOS 上用法相同。工程与构建由 kxbuild 负责，手机由 kxdevice 负责。每条命令都有 --help；全局参数 --json 输出一个固定结构的 JSON，供脚本和 AI 代理使用。

kxstore 有哪些命令？

有三件事 Apple 的 App Store Connect API 没有提供接口，每个 App 在网页上做一次即可：在 App Store Connect 新建 App 记录、填写 App 隐私（隐私标签）、接受协议（如付费应用协议）。App Clip 的 Bundle ID 也只能在开发者网站注册。遇到这些步骤时命令返回 capability_not_supported（退出码 5）并说明去哪里做，做完后重跑同一条命令即可，之后每个版本都不再需要人工操作。

kxstore login 怎么登录 App Store Connect？

kxstore login --api-key-file <AuthKey.json> [--alias 别名] · kxstore login --api-key-id <Key ID> --api-issuer-id <Issuer ID> --api-key-path <AuthKey.p8>

在 App Store Connect 的「用户和访问 → 集成 → 团队密钥」生成一把 API 密钥（角色选 App 管理或管理），下载 AuthKey_<Key ID>.p8，记下页面上的 Issuer ID。登录一次即可：密钥通过校验后加密保存在本机，之后每条命令自己完成认证，没有 Apple ID 密码，也没有双重认证，脚本、CI 和 AI 代理都能无人值守运行。

• --api-key-file 接受 JSON 密钥文件（key_id、issuer_id、key 三个字段）。
• CI 里不想先登录时，设置环境变量 KXSTORE_API_KEY_ID、KXSTORE_API_ISSUER_ID、KXSTORE_API_KEY_PATH（或 KXSTORE_API_KEY_P8 直接放 .p8 内容，或 KXSTORE_API_KEY_FILE 指向 JSON），任何命令在需要时自动登录。
• 多个账号用 --alias 起名，之后用 --account <别名> 或环境变量 KXSTORE_ACCOUNT 选择；account list 列出已登录账号，logout 删除当前账号和它的密钥。
• whoami 显示密钥所属的 Apple ID、团队名和团队 ID；team list 同样。

kxstore init 和 doctor 怎么用？

kxstore init --bundle-id <Bundle ID> --name <App 名> [--from-app] · kxstore doctor [--for-release]

在工程目录执行 init，生成 kxstore.yaml：App 的 Bundle ID、名称、主语言，要准备的证书和描述文件类型，版本号、ipa 路径、元数据目录、是否提审等。之后的命令从当前目录向上查找这个文件，省掉大部分参数；--from-app 同时把线上已有的元数据导出到本地。doctor 只读不写，逐项检查账号、团队、Bundle ID、App 记录、ipa（版本号、签名团队、描述文件类型）和元数据目录，--for-release 按上架的要求检查，失败项都带修复建议。

kxstore release 怎么一键上架？

kxstore release [--dry-run] [--no-submit] [--skip 步骤,…] [--only 步骤,…] [--from 步骤]

按 kxstore.yaml 依次执行：preflight → bundle → certs → profiles → app → version → upload → metadata → screenshots → build-wait → compliance → review-info → submit，配置了 TestFlight、内购、定价、Game Center 的还会执行对应步骤。每步幂等：Bundle ID、App、版本已存在就跳过，证书有效就复用，同编号构建已上传就不再传，已提交审核就不再提。进度写在工程下的 .kxstore/release-state.json，中途失败后重跑同一条命令从失败的那一步继续。

• --dry-run 只读，报告每一步「会做什么」；--no-submit 做完提审之前的全部步骤，构建已挂到版本上，之后手动 review submit 或在网页上提审。
• 发布不在流水线里：release_type 为 MANUAL 时，审核通过后执行 kxstore version publish 1.2.0 才会上线。
• --json 时每个步骤输出一行 JSON 事件，失败行带 retryable 和可直接执行的 next_action。

怎么在 Windows 上生成证书和描述文件？

kxstore bundle create · kxstore cert create · kxstore device add · kxstore profile create · kxstore signing

私钥和 CSR 在本机生成，Apple 签发后 .p12 保存到 --out 指定的目录；描述文件自动挑选证书和设备，已有且匹配的直接复用，过期的重建。把生成的 .p12、密码文件和 .mobileprovision 放进工程的 keychain 文件夹，kxbuild 就能签名，详见 Windows 给 iOS App 签名。

• 证书类型：IOS_DEVELOPMENT 真机调试，IOS_DISTRIBUTION 上架与 Ad Hoc；描述文件类型：IOS_APP_DEVELOPMENT、IOS_APP_STORE、IOS_APP_ADHOC。cert types 列出全部类型。
• .p12 密码从环境变量 KXSTORE_P12_PASSWORD 读取，或用 --p12-password-env 指定变量名，不会出现在命令行里。
• device import devices.txt 批量注册测试设备；bundle capabilities 查看和开启推送、iCloud 等权限。
• kxstore signing 按 kxstore.yaml 里 signing 段的配置把 Bundle ID、证书、描述文件一次准备好，并写出 signing/manifest.json。

怎么上传 ipa 并等待处理？

kxstore build upload <ipa> [--wait] [--timeout 30m] · kxstore build list / wait / compliance · kxstore app list / get · kxstore version create / set / publish

上传走 Apple 的构建上传接口，不需要 Transporter，也不需要 AppStoreInfo.plist。Apple 在上传过程中校验包，签名不对或构建号重复会当场报错，构建号 CFBundleVersion 每次上传前要递增。上传完成后 Apple 继续处理几分钟，--wait 等到处理完成再返回，之后构建出现在 TestFlight 页。

• --app 接受 Bundle ID 或 App Store Connect 的 App ID，缺省取 kxstore.yaml 的 app.bundle_id；上传时从 ipa 里读 Bundle ID 自动找 App。
• build compliance --encryption no 回答出口合规问题；version set --build 42 把某个构建挂到版本上；version publish 手动发布已通过审核的版本。
• App 记录只能在 App Store Connect 网页新建；app list、app get 查看，app set 修改内容版权声明。

怎么导入文案和截图？

kxstore metadata export / import / validate · kxstore screenshot upload --locale <语言> <目录> · kxstore preview upload · kxstore asset place

元数据是一个目录：config.yaml 放分类、年龄分级和审核信息，metadata/<语言>/ 下每个字段一个文本文件（name.txt、subtitle.txt、description.txt、keywords.txt、release_notes.txt、privacy_url.txt 等），截图按机型放在子目录。先 export 拿到线上现状，改好文件再 import；import 只写目录里存在且非空的字段，没改的字段识别为未变化直接跳过。截图按像素尺寸自动归入 6.7 英寸、6.5 英寸、iPad 等槽位，--replace 先传新图再删旧图。

• metadata validate 离线检查字数上限、语言代码、截图尺寸和文件名，不联网。
• asset upload、asset place 用素材库：一张图只上传一次，再放到任意语言、自定产品页面或产品页面测试上；iPhone Duo 截图和产品页标题、搜索结果素材也从这里传。
• custom-page 管理自定产品页面，page-test 管理产品页面 A/B 测试。

怎么提审和分发 TestFlight？

kxstore review submit / status / cancel · kxstore review info set · kxstore testflight distribute --build <构建号> --group <分组>

review submit 把当前版本连同草稿里的内购、排行榜等一起送审，幂等，已提交的不会重复提交；Apple 拒绝提交时把原因逐条列出（缺截图、缺隐私政策链接、隐私标签未发布等），补齐后重跑。review status 看版本和提交的状态，review cancel 在等待审核时撤回。testflight distribute 把构建分发给某个测试组，testflight group、testflight tester 管理分组和测试员。

内购、定价和 Game Center 怎么管？

kxstore iap list / create / set / export / import · kxstore pricing get / set / territories · kxstore game-center status / sync

内购项目和它们的多语言文案、审核截图同样以目录形式导出导入；pricing set --free 或 --price 0.99 设定价，--territories 设可售地区；game-center sync 按 kxstore.yaml 同步排行榜及其多语言名称。首次上架时价格和内购必须和版本一起提交，release 流水线已把它们排在 submit 之前。

怎么让 AI 代理用 kxstore 上架？

kxstore skill --install user · kxstore exit-codes

skill 子命令生成一份技能文件，写明使用规则（必须加 --json、密钥不进命令行、哪些操作不得自行执行）、退出码与重试策略、常用流程和完整命令索引：--install user 装到 ~/.claude/skills 供所有项目使用，--install project 只装到当前项目，--format agents 输出可追加到 AGENTS.md 的说明。用 kxbuild project create 新建的工程，AGENTS.md 里已经写好了上传和 release 的用法。

• 给代理的约定：始终加 --json --yes；密钥只通过 --api-key-file 或环境变量传入；status 为 skipped、reused 一律视为成功；retryable 为 true 时退避后重跑 next_action；capability_not_supported 时把网页操作交给人。
• 让代理先跑 doctor --for-release 和 release --dry-run，确认计划后再 release --no-submit；是否提审由你决定。

常见问题

kxstore 和 Transporter 有什么区别？

Transporter 只上传包。kxstore 除了上传，还管证书、描述文件、元数据、截图、提审、TestFlight、内购和定价，在 Windows、Linux、macOS 上用法相同，并且每条命令都能由脚本和 AI 代理调用。

哪些步骤必须在 App Store Connect 网页上做？

新建 App 记录、填写 App 隐私（隐私标签）、接受协议，以及注册 App Clip 的 Bundle ID。这些 Apple 的 API 没有提供接口，每个 App 做一次，之后的每个版本都能全程用命令完成。

上传时提示构建号重复怎么办？

App Store Connect 不接受同一版本号下重复的构建号。递增工程里的 CFBundleVersion（或用 kxbuild build 的 -D CURRENT_PROJECT_VERSION=<新号> 覆盖）重新构建后再上传；release 流水线遇到已上传的构建号会直接跳过上传这一步。

kxstore 需要授权吗？

需要，和 kxbuild 用同一个授权，在这台电脑上执行过 kxbuild license activate 或 kxbuild license trial 即可；exit-codes、skill、help 不需要授权。