ipatool：用命令行在 App Store 上搜索并下载 i…

一、它到底做了什么：把 App Store 搬进终端

README 第一句定义写得很克制：ipatool is a command line tool that allows you to search for iOS, iPadOS, tvOS, visionOS, and macOS apps on the App Store, and download .ipa or macOS .pkg app packages. 仓库的 description 更短：Command-line tool that allows searching and downloading app packages (known as ipa files) for iOS, iPadOS, tvOS, and visionOS from the App Store。

两句话有个细微差别值得指出：仓库简介里没有提 macOS，README 里提到了，并且明确说 macOS 应用下载下来的是 .pkg 而不是 .ipa。这类差异通常意味着能力是后加的、简介没同步。使用时以 README 为准。

它的价值在于把 App Store 这套原本只存在于 App Store 客户端内部的流程，翻译成了可以被脚本调用的命令。为什么有人需要这个？场景其实很具体：安全研究需要拿到某个版本的包体做静态分析；测试同学需要在真机上装回上一个版本复现问题；企业内部分发需要归档自己买过的应用；CI 流水线要自动拉包。这些事在图形界面里要么做不了，要么只能手动点。

仓库的 topics 也侧面印证了它的定位：reverse-engineering、research、security、itunes、ipa。数据方面，11020 个 Star、920 次 Fork、30 个未关闭 Issue，主语言 Go，MIT 许可，2021 年 5 月 22 日建仓，最近一次提交推送在 2026 年 9 月 3 日——一个维护了五年、体量不大但一直活着的工具。

二、两条前置要求，第二条才是门槛

README 的 Requirements 只有两条，短到可以整段抄下来：

• Supported operating system：Windows、Linux 或 macOS 都可以；
• Apple ID set up to use the App Store：一个已经能正常用于 App Store 的 Apple ID。

第一条几乎不构成限制——它是 Go 写的静态二进制，三个平台都有发布包。真正决定你能不能用起来的是第二条，而且是「已设置好可用于 App Store」这个限定语：一个刚注册、没绑定支付方式、没在 App Store 登录过的 Apple ID，通常是走不通后续流程的。换句话说，这个工具的权限边界，就是你那个 Apple ID 在 App Store 里的权限边界——它不会给你更多，只是把已有的权限暴露成了命令。

三、安装：brew 一行，或者 releases 里拖一个二进制

macOS 上最直接的方式是 Homebrew：

$ brew install ipatool

Windows 与 Linux 用户没有包管理器可选，README 的说法是从 GitHub releases 页面手动取最新版本。好处是不需要 Go 环境，坏处是没有自动更新，升级要自己再来一遍。

四、auth：登录、查看、吊销三个动作

所有操作的前提是鉴权，用 auth 命令完成。它下面有三个子命令，分工非常清楚：

• login：Login to the App Store，登录并保存凭据；
• info：Show current account info，查看当前登录的账号信息；
• revoke：Revoke your App Store credentials，吊销凭据。

这三个动作里，revoke 是最容易被忽略、但在共享机器上最重要的一个。凭据是存在系统钥匙串里的，换机器、交接设备、怀疑泄露时，跑一次 revoke 比删文件靠谱得多。

值得注意的是，后续几个命令（purchase、list-purchases、list-versions、download、get-version-metadata）的全局参数里都有 –keychain-passphrase，说明工具在需要读取钥匙串时支持显式传入口令。而 auth 与 search 的全局参数列表里没有这一项——它们不碰钥匙串。

五、search：五个平台，以及一个 12 条的硬上限

search 用来在 App Store 里搜应用。它的参数很少，但每个都有讲究：

• -l, –limit int：最多返回多少条结果，默认 5；
• –platform string：搜索的平台，可选 iphone（iOS）、ipad（iPadOS）、appletv（tvOS）、visionos、macos。

README 里藏了一句很实在的限制：visionOS supports up to 12。也就是说 visionOS 平台最多只能拿到 12 条结果，–limit 填再大也没用。这是 App Store 服务端的行为，不是工具的 bug。做批量采集时如果目标平台是 visionOS，得提前接受这个天花板。

搜索结果里最关键的产出是应用的 app id 与 bundle identifier，后面所有命令都靠这两个值定位目标。这也解释了为什么 download 里 -b/–bundle-identifier 的描述是 overrides the app ID——bundle id 是更稳定的那个标识。

六、从授权到落包：一条完整的动作链

把 README 的 Usage 一节按顺序读完，会发现它其实是一条设计得很紧的流水线，每一步的产物都是下一步的输入。这条链的严格顺序，本身就是这个工具最重要的设计语言。

第一步不用多说。第二步 search 拿到定位信息。第三步 purchase，README 的原话是 Obtain a license for the app from the App Store——注意这里是「获取授权」，不是「付款」。对免费应用，这一步就是把应用挂到你的账号名下；-b, –bundle-identifier 是必需参数，–platform 指定平台。

第四步 list-purchases，列出当前账号已拥有的应用，README 明确说了排序规则：Results are ordered by purchase date, newest first。默认每页 10 条（-l, –max-results），页码从 1 开始（-p, –page）。这一步常被当成可有可无的查询，实际上它是验证前一步是否成功的最快手段——purchase 报没报错是一回事，账号下到底有没有这个应用是另一回事。

第五步 download，终于取包。它接受 -i, –app-id（必需）、-b, –bundle-identifier（覆盖 app id）、-o, –output（落盘路径）、–platform，以及两个很关键的开关：–external-version-id（不指定就取最新版）与 –purchase（Obtain a license for the app if needed，需要时自动补一次授权）。

–purchase 这个参数把第三步和第五步合并了：如果你确定目标应用已经在账号下，直接 download；如果不确定，加上它让工具自己判断是否需要先取授权。日常用起来，大多数人会习惯性地带上这个参数。

七、list-versions 与 external-version-id：版本考古的关键

如果想拿的不是最新版，链条里还要插两步。list-versions 列出某个 iOS 应用的可用版本，-i, –app-id 必需，-b, –bundle-identifier 可覆盖；它的输出里会出现一串 external version identifier，这就是 –external-version-id 要填的东西。

拿到这个 id 之后，get-version-metadata 可以查某一个具体版本的元数据，两个必需参数是 -i, –app-id 与 –external-version-id。README 对它的描述是 Retrieves the metadata for a specific version of an app。

这套设计的意义在于可回溯。做安全研究时经常需要对比两个版本之间改了什么，做兼容性测试时需要装回用户报告出问题的那个版本，而 App Store 客户端本身是不让你选版本的。有了 external version id，历史版本变成了一个可以被精确指定的坐标——这是这个工具最接近「不可替代」的能力。

八、两个全局开关：–format json 与 –non-interactive

所有命令共享三个全局参数，其中两个直接决定了它能不能进自动化流水线：

• –format format：设置命令输出格式，可选 text 或 json，默认 text；
• –non-interactive：在非交互式会话中运行；
• –verbose：打开详细日志。

README 在 Usage 末尾专门补了一句：the tool runs in interactive mode by default. Use the –non-interactive flag if running in an automated environment。这条提示很关键——默认交互模式意味着它会等你输入密码、等你确认，在 CI 里会直接挂住。而 –format json 则让输出可以被 jq 之类的工具解析，这才是「命令行工具」真正的用法：不只看，还要接。

把三个全局开关和 –keychain-passphrase 放在一起看，会发现作者是认真考虑过无人值守场景的：口令可以从参数传、输出可以是 JSON、交互可以关掉。但也正因为如此，凭据管理成了使用者自己的责任——把 passphrase 写进脚本或 CI 变量之前，先想清楚谁能读到它。

九、编译与测试：一个标准 Go 项目

想改代码或者自己打包，用 Go 工具链即可：

$ go build -o ipatool

跑单元测试前需要先生成代码，README 给的两行是：

$ go generate ./...
$ go test -v ./...

先 go generate 再 go test 这个顺序不能反——前者会生成测试所需的桩代码。对一个 1429 KB 的小仓库来说，这套流程意味着你不需要什么特殊构建环境，装好 Go 就能从源码跑到测试。

十、合规边界与总结

必须把话说清楚：ipatool 的能力边界，严格等于你那个 Apple ID 在 App Store 里的授权边界。它不绕过付费、不破解应用、不提供你没买过的东西——它只是把「登录、搜索、获取授权、下载」这几个你本来就能在 App Store 里手动完成的动作，变成了可以在终端里执行、可以被脚本编排的命令。README 的 purchase 写的是 Obtain a license，是取得授权，不是取得破解包。

也正因为如此，它天然带有被误用的风险：批量下载、代他人账号取包、把下载下来的包二次分发，这些都已经越过了「自己账号、自己已购、自己使用」的线。工具本身是 MIT 许可的中立代码，责任在使用方式上。

从工程角度看，它值得学习的地方是把一条私有协议流程拆解成了一组职责单一、可组合、可脚本化的命令：鉴权归 auth，检索归 search，授权归 purchase，版本查询归 list-versions 与 get-version-metadata，取包归 download，每个命令都支持 JSON 输出和非交互模式。五年、11020 个 Star，靠的就是这种「把一件事做到能被脚本调用」的克制。如果你需要在终端或者 CI 里操作 App Store 的包，它基本是这个领域绕不开的一个选项。

在撰写本文的过程中，我主要参考了以下来源：GitHub 仓库 majd/ipatool 的 README（Requirements、Installation、Usage 中 auth / search / purchase / list-purchases / list-versions / download / get-version-metadata 各命令的帮助文本、Compiling、License）与仓库 meta 数据，以及官方 Wiki FAQ 入口。文中命令、参数与数据均取自官方公开信息，可能随版本更新而变化。