Carthage

定义

Carthage是一款面向Cocoa应用的去中心化依赖管理工具，官方将其定位为把框架加入Cocoa应用的最简单途径^[1]。它同时服务于Swift和Objective-C项目，主要用途是替开发者获取并编译项目所需的第三方框架，最终产出可直接嵌入应用的二进制框架文件^[2]。

所谓去中心化，指它不依赖一个集中维护的库索引，也不需要框架作者提交专门的规格文件；依赖的来源由开发者在工程里自行声明^[3]。它与CocoaPods的关键差别在于介入程度：Carthage只负责构建二进制框架，工程结构与构建设置的控制权仍留在开发者手中，不会自动修改工程文件^[3]。

工具由Swift语言编写，输入是纯文本的依赖声明文件，输出是存放在工程目录固定位置的框架产物^[4]。

原理

Carthage的工作流围绕一个名为Cartfile的依赖清单展开：开发者在该文件中逐行写出所需框架的仓库地址与版本约束，支持的来源包括GitHub仓库、Git地址以及只提供二进制产物的框架^[2]。执行更新命令后，工具解析这份清单，解析出各依赖的兼容版本，再把结果写进Cartfile.resolved这一锁定文件^[5]。

解析阶段的版本约束语法与常见的语义化版本写法接近，例如$\sim>$表示取兼容区间、$==$表示锁定某个确切版本、$>=$表示不低于某版本^[4]。锁定文件记录的是实际参与编译的版本号，因此官方建议把它提交到版本库，保证协作者能复现同一套依赖^[3]。

源码会被检出到工程的Checkouts目录，随后由xcodebuild调用Xcode完成编译，产物写入Build目录^[3]。整体过程可概括为下图：

flowchart LR

A[Cartfile 声明依赖] --> B[解析版本

生成 Cartfile.resolved]

B --> C[Git 拉取源码

到 Carthage/Checkouts]

C --> D[xcodebuild 编译

生成框架]

D --> E[Carthage/Build 产物]

E --> F[开发者手动

集成到 Xcode 工程]

编译产物需要由开发者手动拖入Xcode工程完成集成，iOS项目通常还要补充脚本，把选定架构的框架复制进应用包，以规避包含模拟器架构的通用二进制在提交应用商店时被拒的问题^[6]。自0.37.0版本起，工具可通过参数改为产出XCFramework——这种结构允许同一个框架内含多个面向不同平台的框架包，从而绕开把多种架构合并成一个通用二进制所带来的冲突^[7]。

发展历程

Carthage的版权声明自2014年起归属Carthage贡献者，许可方式为MIT^[8]。它由GitHub开发，主要作者为Justin Spahr-Summers，其设计目标被概括为“尽可能地简单”，尽量把任务交给开发者已经熟悉的Xcode与Git处理^[9]。

该工具产生的背景，是当时Cocoa生态中已有的几种代码复用方式各有短板：手动拷贝源码无法管理版本，Git子模块在多个依赖共享同一底层依赖时容易出问题，而CocoaPods虽然成为事实标准，却要求每个项目提供spec文件并接管工程的生成过程^[9]。

2021年1月发布的0.37.0版本引入XCFramework构建能力，被视为应对Xcode 12与Apple Silicon机型的重要调整：在此之前，iOS设备与模拟器都使用arm64架构，用lipo合并出的通用二进制会因此产生冲突，而XCFramework按平台分别存放框架包，不再需要这类合并^[7]。同年有开发者记录了从该版本迁移到XCFramework的实践，迁移后可省去复制框架的构建脚本阶段^[10]。

工具的版本号维持在0.40.0一带，2025年9月项目仓库仍有更新记录^[1]。首页数据显示其稳定版为0.40.0，安装需Xcode 10.0以上版本与macOS环境^[11]。

应用

Carthage的使用场景是向Xcode工程引入第三方开放源代码框架，覆盖iOS、macOS、tvOS与watchOS平台；使用前需先完成安装，常见方式为通过Homebrew安装，也可以使用打包好的安装程序^[4]。

典型流程分3步：创建Cartfile列出需要的框架，运行更新命令让工具拉取并编译这些框架，最后把编译出的框架二进制拖入Xcode工程^[3]。对于iOS工程，还需在构建阶段加入运行脚本，把框架复制进应用包，以绕开通用二进制触发的应用商店提交问题^[6]。

除应用本体外，它也可服务于单元测试目标或其他框架目标的依赖管理，差别在于非应用目标缺少嵌入二进制的设置项，需要改用链接构建阶段来完成关联^[3]。在持续集成环境中，它可以作为构建步骤执行指定的Carthage命令，例如运行bootstrap来拉取并编译依赖^[12]。

有企业级项目记录了将其从Carthage迁移到SwiftPM后构建时间变长的情况，说明在同一工程中选择依赖管理方式需要权衡构建耗时与集成方式^[13]。

局限

只支持动态框架是最主要的功能边界。动态框架要到iOS 8才可用，因此它无法用于面向更早iOS版本的应用；官方文档也明确说明了这一限制^[3]。静态框架的支持直到0.30.0版本才加入^[2]。

由于不维护集中索引，项目的可发现性较差，开发者往往需要借助代码托管平台的趋势榜单或类似渠道自行寻找可用的框架^[3]。集成步骤也需要开发者亲自完成，相比能够自动生成工作区的方案更费人工^[3]。

关于Mac Catalyst应用，该工具目前并不提供支持，需要这类能力的项目只能改用其他方案或手动集成^[14]。此外，用它引入的框架偶尔会因Xcode版本不一致而出现Swift版本不兼容的报错，通常的应对办法是让构建环境使用同一版本的工具链^[14]。

在0.37.0引入XCFramework之后，仍有若干已知限制：当依赖只提供二进制产物时，该参数不会为其生成XCFramework，需要改用从源码重建的方式绕开；归档命令也不支持归档已生成的XCFramework^[7]。随着苹果官方包管理方案日趋成熟，部分第三方库已停止对Carthage的官方支持，建议使用者转向Swift Package Manager或手动安装预编译的XCFramework^[15]。

工具本身在设计上主动选择比同类方案更少的功能，以简单和小巧为取舍方向^[16]。

参见

• CocoaPods —— 面向Cocoa的集中式依赖管理工具，为该词条的主要对照方案。

• Swift Package Manager —— 苹果官方提供的依赖管理工具，部分库建议由该词条迁移至它。

• XCFramework —— 苹果自Xcode 11起支持的框架分发结构，该词条自0.37.0版本起支持构建。

• Xcode —— 苹果的集成开发环境，该词条借助其命令行工具编译依赖。

• Git —— 分布式版本控制系统，该词条以其仓库作为依赖来源。

• Homebrew —— 面向macOS的包管理器，是该词条的一种常见安装方式。