CocoaPods 与 Swift Package Manager 安装失败怎么查

打开一个 iOS 工程，终端里 pod install 走到 CDN: trunk URL couldn't be downloaded，后面带着 https://cdn.cocoapods.org/ 的地址。另一个工程没有 Podfile，Xcode 在获取软件包时提示无法解析包依赖，详情里是 GitHub 返回无效响应。两种都是「依赖没下来」，但索引、缓存和账号完全不同。

CocoaPods 先问规格索引，再按 Podfile 里的地址拉源码或二进制。Swift 包管理器按 Xcode 里添加的包地址走，经常直接访问 GitHub。下面先让这两类域名能打开，再清对应的缓存，最后才改版本号。镜像和提交要求以仓库当前说明为准。

索引、包地址和缓存各在哪

找不到规格，和索引根本没下载完，不是同一句报错。前者是 Podfile 里的名字或版本在索引中不存在，后者是 cdn 地址没打开。

从超时到能编译：分步操作

• 第一步：先把网络线路准备好，再执行 pod 或打开 Xcode。安装刺猬VPN，用自定义用户名和密码注册，不需要邮箱和手机号。连上后再访问 cdn.cocoapods.org 与 github.com，让索引和源码走同一条线路。免费节点永久免费、不限流量、不限速。
• 第二步：浏览器打开 https://cdn.cocoapods.org/ 以及你包地址里的 GitHub 仓库页。打不开就换节点。不要先改 Podfile 的版本号。
• 第三步：在工程目录执行 pod install。若原文仍是 trunk URL couldn't be downloaded，确认没有把请求改到一个失效镜像。需要指定仓库时，在 Podfile 顶部写明 source，而不是在一半失败后连续重试。
• 第四步：提示 Unable to find a specification：索引已经下来了，但名字或版本不对。对照 Podfile 的拼写、系统版本要求和锁文件。不要把这句当成超时。
• 第五步：Swift 包在 Xcode 里用文件菜单的添加包依赖，粘贴仓库地址。若提示无法解析，先看该仓库网页能否打开，再在文件菜单里重置包缓存，然后重新解析。
• 第六步：私有包要凭据。凭据弹窗被线路打断时，会显示成无效响应。先在浏览器登录 GitHub，确认账号有权限，再回 Xcode。
• 第七步：pod install 成功后打开生成的工作区，不要再开旧的工程文件。Swift 包则确认解析完成的标记出现在工程导航里，再编译。
• 第八步：准备发给测试员时，依赖必须能在一台新环境重装。上传和测试员安装见 TestFlight 与开发者账号。本机缓存能编过，不代表别人能拉到同一份包。

按原文区分索引、版本和凭据

• trunk URL couldn't be downloaded：索引主机没通。浏览器打开 cdn 地址，换节点后再 pod install。
• Unable to find a specification：名字、源或版本不在当前索引。核对 Podfile，必要时更新索引而不是改线路。
• 无法解析包依赖：仓库地址、标签或网络中断。打开该仓库网页，重置包缓存后再解析。
• Received invalid response：连接被重置或凭据页没走完。先浏览器登录，再重试，不要并行开多个解析。
• 只有某一台电脑失败：那台的缓存或旧镜像还在。在失败的机器上单独打开 cdn 与 GitHub。
• 锁文件和 Podfile 冲突：不要手改锁文件里的地址。让安装命令按 Podfile 重写，再提交锁文件。
• Xcode 能解析、命令行不能：命令行用的开发者目录不同。确认 xcode-select 指向你正在用的 Xcode。

官方索引和镜像怎么选

发布用的工程优先官方索引和仓库标签。刺猬VPN可按域名分流，让 cdn 与 GitHub 走线路、内网地址不走。实际可用性取决于当前网络环境。

缓存目录和锁文件不要一起删

CocoaPods 的缓存和工程里的 Pods 目录不是一回事。只删缓存，是为了丢掉下到一半的索引。把整个 Pods 目录删掉也可以重装，但锁文件不要手改。Swift 包缓存清掉之后，Xcode 会重新克隆，标签必须仍然存在于远程仓库。标签被作者删除时，换线路也解析不到。

团队提交锁文件，就是为了让每个人拿到同一版本。某人为了绕过超时改了镜像地址并提交，其他人会在另一天突然找不到规格。镜像地址若必须使用，写进文档并说明哪一天核对过，而不是写进每个人本地却不提交。

命令行和 Xcode 图形界面不要同时点解析。两个进程抢同一缓存时，无效响应会反复出现。等一个结束再开另一个。新同事第一天克隆仓库后，先浏览器打开索引和 GitHub，再跑安装，能少一次把权限问题当成网络问题。

和测试分发、其他语言工具的分工

依赖装好只是编译前的一步。证书、描述文件和测试员安装见 Apple 开发者与 TestFlight。Homebrew、Go 与 Rust 的代理变量不能抄进 Podfile，对照见 Homebrew、Go 与 Rust 代理。

一种语言的镜像地址不要粘贴到另一种工具。验收标准是：新目录里重新安装成功，并且锁文件没有被意外改写。

常见报错速查表

新机器、旧缓存和版本号不要混在一次修改里

新同事第一天克隆仓库，最稳的顺序是先用浏览器打开索引地址和每一个私有仓库，确认账号有权限，再在终端安装。跳过浏览器直接跑命令，超时和没有权限会写成同一句失败，你不知道该换节点还是该找管理员开权限。权限开好之后，不要立刻升级所有依赖的版本号。先让锁文件里的旧版本装上，编译通过，再单独升级一个库。一次改版本、改镜像、改线路，成功了也无法写进说明。

本机曾经用过失效镜像时，终端的环境里可能还留着旧地址。新开一个终端窗口再安装，避免上一扇窗口的变量还在。图形界面的包解析和终端不要同时点。两个进程抢缓存时，无效响应会反复出现，像是线路不稳。等其中一个结束，再开另一个。索引下载到一半被你取消，缓存里会留下不完整的文件，下次仍报下载失败。只清这一份缓存，不要把整个开发者目录删掉。

标签被上游删除之后，任何线路都解析不到那个版本。看仓库的发布页，标签还在不在，再决定是换一个仍然存在的版本，还是联系作者。把已经能编译的版本号写进说明，包括安装命令和当时用的官方索引。下次失败时先重复这一条。内网私有库走直连、公开索引走线路时，用按域名的分流分开，不要把整台电脑的流量都送进隧道，也不要写一条把所有源都改去镜像的配置。

提交之前看锁文件有没有被镜像地址改写。被改写就在官方索引下重新安装再提交。审查的人若看到陌生主机名，应退回，而不是在自己电脑上再加一条同样的镜像。这样整组人的构建才不会在某一天集体找不到规格。

安装日志要留到这次成功为止。失败那一次的原文，比口头说的「网络不行」有用。把原文里的主机名圈出来，用浏览器只打开那一个主机。能打开就回到工程看版本和锁文件。打不开就先换节点，不要改 Podfile。同一天里公开索引恢复了、私有库仍失败，就只处理私有库的账号，不要把已经恢复的索引再改去镜像。

编译通过之后做一次干净的检出。把依赖目录删掉，只保留声明文件和锁文件，重新安装。这一次若失败，说明你刚才的成功依赖了本机旧缓存，别人会装不上。这一次若成功，再把锁文件提交。说明里写上官方索引地址和安装命令，下次超时先重复，而不是重新搜索一份来路不明的镜像。别人按说明仍失败时，让对方把浏览器打不开的那个主机名发过来，不要让对方先改工程文件。干净安装在两台电脑上都成功，这份锁文件才可以交给别人。只有一台成功时，对照终端里的环境变量，删掉失败那台多余的镜像地址，不要先升级版本号。两台都通过之后，把这次用的索引地址写进项目说明的第一行，避免下次有人从搜索结果里复制一份旧镜像。说明的第二行写上成功当天的安装命令，别人失败时先原样执行这一条。

高频问答

• 问：必须二选一吗？答：同一工程可以并存，但报错要看是 pod 还是 Xcode 的包解析。不要用一个缓存命令修两个系统。
• 问：镜像能不能代替 cdn？答：能缓解索引下载，但可能落后。发布工程仍要能打开官方索引。
• 问：为什么网页能开、pod 不行？答：终端可能走了另一套环境变量或旧镜像。在同一台机器的浏览器和终端分别试。
• 问：私有库一直无效响应？答：先确认 GitHub 账号有权限。线路只负责把登录页打开。
• 问：免费节点够不够？答：够验证索引能否打开。大仓库克隆用时长套餐，期间不限流量、不限速。
• 问：客户端能按 Xcode 单独代理吗？答：没有按应用勾选的列表。用按域名的智能分流覆盖 cdn 和 GitHub。

交给别人编译之前

CocoaPods 的 CDN 超时、找不到规格、Swift 包无法解析，分别是索引、版本和仓库三件事。先连上线路打开两个域名，再安装，最后才改版本。锁文件提交前看一眼地址有没有被镜像改掉。

刺猬VPN采用 HTTPS+AES 加密传输。注册只需用户名和密码，不需要邮箱和手机号。免费节点永久免费、不限流量、不限速。时长套餐有效期内不限流量、不限速。实际可用性取决于当前网络环境。