2026 年 iTMSTransporter Windows 上传发布 IPA 教程

2026 年 iTMSTransporter Windows 上传发布 IPA 教程

Windows 上用 Apple 官方的 iTMSTransporter 上传 IPA，2026 年的正确命令是这样的：

iTMSTransporter -m upload -assetFile App.ipa -assetDescription AppStoreInfo.plist -u dev@example.com -p abcd-efgh-ijkl-mnop

注意里面那个 -assetDescription AppStoreInfo.plist——在 Windows 和 Linux 上它是必填的，而这份文件按官方说法只能从 Xcode 导出。我当初就卡在这一步，下面会讲怎么在 Windows 上直接把它生成出来。

先搞清楚 2026 年变了什么

如果你照着几年前的老教程操作，多半会失败。有三处变化：

1. -f 不能再用来上传 App 了。 Apple 已经明确：上传或校验 App 必须改用 -assetFile，-f 只保留给其他内容类型。老教程里的 -m upload -f App.ipa 这种写法现在会直接报错。
2. .itmsp 包投递已经废弃。 过去要先手工造一个 <vendor_id>.itmsp 目录、往里塞 metadata.xml 和 IPA，现在直接用 -assetFile 指向 IPA 就行，简单了很多。
3. Windows / Linux 上必须带 -assetDescription。 Apple 官方用户指南里写得很直白：这个参数 “required for Linux and Windows App uploads, but not for macOS App uploads”。macOS 上不用给，因为 Transporter 会自己调 Xcode 里的工具现生成一份；Windows 上没有 Xcode，所以得你自己准备好交给它。

第 3 条最要命，下面单独用一步来解决。

第一步：安装 iTMSTransporter

Transporter 目前的版本是 4.2，Windows 版是一个自解压安装包。

下载地址（Apple 官方直链）：

https://itunesconnect.apple.com/WebObjects/iTunesConnect.woa/ra/resources/download/public/Transporter__Windows/bin

下载下来是 iTMSTransporterToolInstaller_4.2.0.<build>.exe。双击运行，接受许可协议，安装目录默认是：

C:\Program Files\itms

安装完会在里面生成一个 iTMSTransporter.woa 子目录。命令行入口在安装目录下，官方文档写作 .\iTMSTransporter（Windows 上实际是同名的批处理脚本）。如果不确定在哪，在安装目录里搜一下 iTMSTransporter 就能找到。

先验证能跑起来：

cd "C:\Program Files\itms\bin"
iTMSTransporter -version

能打印出版本号就说明装好了。为了后面命令好写，建议把这个 bin 目录加进系统 PATH：设置 → 系统 → 关于 → 高级系统设置 → 环境变量 → 选中 Path → 编辑 → 新建，粘贴目录路径，然后重开一个命令行窗口才生效。

第二步：准备 AppStoreInfo.plist（关键一步）

这一步是 Windows 用户真正卡住的地方，先说清楚它是什么。

AppStoreInfo.plist 不是你工程里的配置文件，而是对你这个包的一份描述清单：包的类型、平台、里面各个 bundle 的结构、图标、签名信息等等，苹果收包时要靠它来核对。文件里苹果自己写了一行说明：

This App Store Information can be used with iTMSTransporter and App Store Connect Developer API.

问题在于，这份清单正常由 Xcode 工具链里的工具生成，那个工具只跑在 macOS 上。于是 Windows 用户就撞上了一个死结：Transporter 有 Windows 版，可它在 Windows 上偏偏要求你提供一份只能在 Mac 上生成的文件。

网上常见的绕法是找台 Mac 生成好再拷过来，或者租云 Mac——为了一个几十 KB 的文件专门搞一台机器，显然不划算。

用「开心上架（AppUploader）」的命令行工具可以直接在 Windows 上生成这份文件，一条命令：

appuploader-cli info -u dev@example.com App.ipa -o AppStoreInfo.plist

• appuploader-cli.exe 在开心上架的安装目录里，装好主程序就有，不用另外下载；
• -u 填你的 Apple ID 邮箱；
• 最后 -o 指定输出文件名。

跑完会打印一行结果，带上文件大小和包的 Bundle ID，顺手核对一下传的是不是想要的那个包：

asset description written to AppStoreInfo.plist (93613 bytes, xml plist, bundle id com.example.app)

把 IPA 和 plist 放在同一个目录里。 这是实践中踩坑较多的一点：两个文件分散在不同路径时，上传容易出问题。放一起最省事。

第三步：准备账号凭据

iTMSTransporter 支持两种登录方式。

方式一：Apple ID + App 专用密码。 去 https://account.apple.com/account/manage 生成一个 App 专用密码，形如 abcd-efgh-ijkl-mnop，只显示一次，当场存好。命令里用 -u 和 -p 传。

方式二：App Store Connect API 密钥（更推荐）。 去 https://appstoreconnect.apple.com/access/api 生成，拿到密钥 ID、Issuer ID 和 .p8 文件。iTMSTransporter 对 .p8 的存放位置有讲究：它不接受你传一个路径，而是按固定文件名去几个固定目录里找：

./private_keys/AuthKey_<密钥ID>.p8

也就是在你执行命令的当前目录下建一个 private_keys 文件夹，把文件按 AuthKey_密钥ID.p8 的名字放进去。除了当前目录，它还会依次找 ~/private_keys、~/.private_keys、~/.appstoreconnect/private_keys，也可以用环境变量 API_PRIVATE_KEYS_DIR 指定目录。

顺带提醒：Transporter 还有一个 -jwt 参数可以直接传令牌，但从 2025 年 9 月底开始，-jwt 配合 -assetDescription 出现过服务端拒收的问题，报 No value present。用 -apiKey / -apiIssuer 这组参数就没有这个毛病，能不用 -jwt 就别用。

第四步：先校验，再上传

正式传之前建议先跑一次校验，能提前发现包本身的问题，省得传了半天被打回：

iTMSTransporter -m verify -assetFile App.ipa -assetDescription AppStoreInfo.plist -u dev@example.com -p abcd-efgh-ijkl-mnop

校验通过再上传，把 -m verify 换成 -m upload：

iTMSTransporter -m upload -assetFile App.ipa -assetDescription AppStoreInfo.plist -u dev@example.com -p abcd-efgh-ijkl-mnop

用 API 密钥的话（记得先建好 private_keys 目录）：

iTMSTransporter -m upload -assetFile App.ipa -assetDescription AppStoreInfo.plist -apiKey UK29KBAX9X -apiIssuer 69a6de78-4459-47e3-e053-5b8c7c11a4d1

参数说明：

排查问题时加上 -v eXtreme，输出会详细很多：

iTMSTransporter -m upload -v eXtreme -assetFile App.ipa -assetDescription AppStoreInfo.plist -apiKey UK29KBAX9X -apiIssuer 69a6de78-4459-47e3-e053-5b8c7c11a4d1

传完之后，苹果那边还要处理几分钟到几十分钟，处理完构建版本才会出现在 App Store Connect 的「构建版本」列表里，那之后才能选来提交审核。刚传完看不到是正常的。

常见报错

说 -f 不能用于上传 App

老写法。改成 -assetFile。

提示缺少 asset description，或者干脆没提示就失败

Windows 上 -assetDescription 是必填的，检查有没有漏掉，以及路径对不对。另外确认 IPA 和 plist 放在同一个目录下。

报 No value present

用 -jwt 传令牌时的已知问题，换成 -apiKey / -apiIssuer 这组参数。

API 密钥认证失败，提示找不到密钥

.p8 的位置和文件名不对。必须是 private_keys/AuthKey_<密钥ID>.p8 这个格式，放在你执行命令的当前目录下，文件名里的密钥 ID 要和 -apiKey 参数完全一致。

版本号或构建号重复

同一个版本号 + 构建号组合已经传过了，苹果不允许覆盖，改构建号重新打包。

Java 相关的报错

Transporter 自带运行环境，一般不需要你另外装 Java。如果报了 Java 相关的错，通常是安装不完整，卸载重装一遍。

顺带一提：其实可以不用这么麻烦

上面这一整套流程——装 Transporter、生成 plist、配 private_keys 目录、拼一长串参数——如果你的目的只是"把 IPA 传上去"，其实有更短的路：生成 plist 用的那个 appuploader-cli，本身就能直接上传：

appuploader-cli upload -f App.ipa -u dev@example.com -p abcd-efgh-ijkl-mnop

一条命令传完，不需要 AppStoreInfo.plist，也不需要装 Transporter，失败时退出码非 0，直接能写进构建脚本。

什么时候仍然值得走 iTMSTransporter：公司流程明确要求用 Apple 官方工具、或者你的流水线已经围绕 Transporter 搭好了别的环节。这两种情况下，用 appuploader-cli info 补上 AppStoreInfo.plist 这一环就行，剩下的照旧。

参考

• Apple 官方 Transporter 用户指南：https://help.apple.com/itc/transporteruserguide/

整套配下来最麻烦的其实就是 AppStoreInfo.plist 那一步，剩下的都是照着参数拼。生成 plist 用的是开心上架（AppUploader）自带的命令行工具，它在 Windows 上还能签证书、建 Bundle ID、生成描述文件。