CocoaPods Trunk：是什么、通过Trunk发布库

什么是CocoaPods Trunk？

CocoaPods Trunk — 是一个于2015年启动的服务器基础设施，用于集中发布Pod库。在Trunk出现之前，每个Pod都通过Git仓库分发：开发人员需要创建公共仓库、添加podspec文件、并向中央仓库CocoaPods/Specs提交Pull Request。这种方法需要手动审核，并在发布更新时造成延迟。

Trunk通过提供统一的API来发布、更新和删除Pod，解决了这些问题。该服务包括四个关键组件：

• 身份验证 — 通过电子邮件确认注册和管理会话令牌。每个开发人员都会收到一个与其帐户和设备绑定的唯一令牌。
• 验证 — 发布前自动检查podspec，包括语法分析、依赖项lint检查和平台兼容性检查。
• 托管 — 在CocoaPods服务器上存储Pod的元数据和版本。源代码仍保留在开发人员的Git仓库中，而Trunk仅存储podspec文件和链接。
• 访问管理 — 添加和删除Pod所有者、转让发布权限、将Pod标记为已弃用的功能。

Trunk的架构基于Ruby on Rails技术栈和PostgreSQL数据库。该服务使用HTTP API和JSON格式进行所有操作，CLI客户端pod trunk是CocoaPods发行版的一部分，与主gemcocoapods一起安装。

目前，通过Trunk已发布超过10万个Pod，总下载量超过500亿次。该服务每天处理来自全球开发人员的数千个库发布和更新请求。

注册和身份验证

在发布Pod之前，您需要在Trunk中注册。过程只需一步——pod trunk register命令：

pod trunk register your@email.com 'Your Name' --description='MacBook Pro，iOS开发'

命令执行后，一封包含确认链接的邮件将发送到指定邮箱。点击链接激活帐户并创建会话令牌，该令牌保存在系统密钥链中（macOS上的Keychain、Linux上的gnome-keyring或等效工具）。令牌会自动用于所有后续的pod trunk操作。

--description参数是可选的，但建议使用——它有助于在通过pod trunk me查看活动会话时识别会话。如果您在多台机器上工作（工作站、CI服务器），描述可以让您区分不同会话。

要检查身份验证状态，请使用以下命令：

pod trunk me

输出显示电子邮件、姓名、您的Pod列表（如果您已发布过）以及活动会话。示例结果：

  - Name: Your Name
  - Email: your@email.com
  - Since: 2024-03-15 10:30 UTC
  - Pods:
    - MyLibrary
    - AnotherPod
  - Sessions:
    - 2024-03-15 10:30 UTC - MacBook Pro, iOS 开发

在CI服务器上（GitHub Actions、GitLab CI、Jenkins），身份验证通过环境变量COCOAPODS_TRUNK_TOKEN传递的令牌进行。可以使用以下命令获取令牌：

pod trunk me --token-only

该令牌作为秘密变量保存在CI设置中，在发布阶段无需重新注册即可使用。GitHub Actions示例：

env:
  COCOAPODS_TRUNK_TOKEN: ${{ secrets.COCOAPODS_TRUNK_TOKEN }}

重要提示：令牌提供对帐户关联Pod管理的完全访问权限。切勿将其发布到公共仓库或提供给第三方。如果令牌泄露，可以通过pod trunk remove-session撤销，或通过CocoaPods网站上的管理面板删除所有会话。

准备podspec

Podspec文件（.podspec或.podspec.json）——是包含元数据、依赖项、平台信息和源代码的库清单。Trunk使用此文件进行Pod的验证和注册。用于发布的最小podspec如下所示：

Pod::Spec.new do |s|
  s.name         = 'MyLibrary'
  s.version      = '0.1.0'
  s.summary      = '库的简要描述'
  s.description  = '带功能说明的详细描述'
  s.homepage     = 'https://github.com/username/MyLibrary'
  s.license      = { :type => 'MIT', :file => 'LICENSE' }
  s.author       = { 'Your Name' => 'your@email.com' }
  s.source       = { :git => 'https://github.com/username/MyLibrary.git', :tag => s.version.to_s }
  s.source_files = 'Sources/**/*.{swift,h,m}'
  s.platform     = :ios, '12.0'
  s.swift_version = '5.7'
end

Podspec的关键字段：

• name — Pod的名称，在Trunk注册表中必须唯一。名称按照「先到先得」原则注册——如果名称已被占用，发布将被拒绝。
• version — 语义版本，格式为MAJOR.MINOR.PATCH。Trunk不接受重新发布相同版本——您需要增加版本号。
• source — Git仓库和标签的链接。Trunk不存储源代码，因此仓库必须可访问以进行克隆。
• platform — 目标平台（iOS、macOS、tvOS、watchOS）和最低SDK版本。
• license — 许可证类型。建议指定MIT、Apache-2.0、BSD或其他开源许可证。

发布前，需要使用linter检查podspec的正确性：

pod lib lint MyLibrary.podspec

Linter检查语法、必填字段的存在、文件路径的正确性以及依赖项的可解析性。如果在lint过程中使用私有源（private specs），则添加--sources标志。要跳过网络下载（仅本地检查），使用--local-only标志。

通过pod trunk push发布

发布Pod的主要命令——pod trunk push。它将podspec文件发送到Trunk服务器，在那里经过完全验证并注册到公共注册表。语法：

pod trunk push MyLibrary.podspec

--allow-warnings标志允许在存在警告时发布。默认情况下，任何警告都会阻止发布。如果库有不影响功能的已知警告，可以使用此标志。重要提示：无论标志如何，错误始终阻止发布。

--synchronous标志使请求同步——终端等待服务器上验证完成。默认情况下，命令在发送后立即返回控制权，服务器异步处理发布。在CI/CD中，当下一个管道步骤取决于发布成功时，同步模式很有用。

--skip-import-validation标志跳过检查库导入测试项目。这加快了发布速度，但不能保证库实际能编译。只有在您确定构建正确的情况下才使用此标志。

使用典型选项发布的示例：

pod trunk push MyLibrary.podspec \
  --allow-warnings \
  --synchronous \
  --skip-import-validation

成功发布后，Trunk返回包含详细信息的JSON：

  Congrats

  MyLibrary (0.1.0) successfully published

  Pod URL: https://cocoapods.org/pods/MyLibrary

库可通过任何iOS或macOS项目的Podfile进行安装。通常，CocoaPods搜索索引中的数据会在几分钟内更新，但在极少数情况下，索引可能需要长达一小时。

重要限制：一旦发布的Pod版本无法删除。这是为了防止对已经使用该版本的项目造成损害。如果发布出错，您可以发布下一个带修正的版本，但无法回滚。例外情况——pod trunk delete，仅CocoaPods员工可用，并在极端情况下使用（许可证违规、恶意代码）。

管理版本和访问

CocoaPods Trunk提供了几个用于管理已发布Pod的命令：

添加所有者

要将Pod的发布权限转让给其他开发人员，请使用以下命令：

pod trunk add-owner MyLibrary developer@email.com

执行后，新所有者获得对Pod的完全管理权限：发布新版本、添加和删除其他所有者、将Pod标记为已弃用。所有者可以是任何已注册的Trunk用户——预先注册是必须的。

删除所有者

如果开发人员离开项目或不再应该拥有对Pod的访问权限：

pod trunk remove-owner MyLibrary developer@email.com

只有当前所有者才能删除所有者。不能删除Pod的最后一个所有者——需要先添加一个新所有者。这可以防止Pod变成无人拥有的状态。

将Pod标记为已弃用

如果库不再受支持，可以将其标记为已弃用（deprecated）。这不会从注册表中删除该Pod，但会在安装时向用户添加警告：

pod trunk deprecate MyLibrary

可选地，可以指定替代Pod：

pod trunk deprecate MyLibrary --in-favor-of=NewLibrary

安装已弃用的Pod时，CocoaPods在终端中显示警告并建议切换到指定的替代品。这是在不破坏现有项目构建的情况下结束库支持的正确方法。

查看Pod信息

Pod的信息可通过pod trunk info命令获取：

pod trunk info MyLibrary

该命令显示Pod的所有版本、发布日期、所有者列表和状态（活动/已弃用）。要查看特定版本的详细信息，请使用pod spec cat MyLibrary 0.1.0。

错误及其解决方法

在使用Trunk时，开发人员经常遇到典型错误。让我们看看最常见的：

身份验证错误

症状： [!] Authentication failed. You need to register a session first.
原因： 会话令牌缺失或已过期。令牌有有限的有效期（默认30天无活动）。
解决方法： 重新运行pod trunk register your@email.com 'Your Name'。如果使用CI，请检查COCOAPODS_TRUNK_TOKEN变量的时效性，并在必要时生成新令牌。

版本冲突

症状： [!] You have already pushed version 0.1.0 for MyLibrary.
原因： 尝试重新发布已存在的版本。Trunk不允许覆盖版本。
解决方法： 根据语义版本控制增加podspec中的版本号。如果您在podspec中犯了错误，请发布下一个带修正的版本。

Podspec验证错误

症状： [!] The spec did not pass validation. ERROR | [iOS] file patterns: Source files did not match any file.
原因： source_files字段中源文件的路径指定不正确。
解决方法： 检查podspec中的路径，本地运行pod lib lint直到所有错误消失，然后重复发布。使用glob模式：Classes/**/*.{h,m}、Sources/MyLibrary/**/*.swift。

连接超时

症状： [!] Connection to trunk.cocoapods.org failed. Timeout.
原因： 网络问题或Trunk服务器暂时不可用。
解决方法： 检查服务器可用性：curl -I https://trunk.cocoapods.org。如果服务器响应，几分钟后重试命令。可能是您的IP被封锁——尝试其他连接或通过VPN。

无法访问Pod

症状： [!] You do not have permission to push to MyLibrary.
原因： 您不是该Pod的所有者。如果某人已经注册了同名Pod，就会发生这种情况。
解决方法： 联系当前Pod所有者（可以通过pod trunk info MyLibrary找到），请求通过pod trunk add-owner添加您。如果Pod名称已被占用，请考虑替代名称。