掌握 Swift Package Manager：管理你的项目依赖

2025-4-1

掌握 Swift Package Manager：管理你的项目依赖

在现代软件开发中，代码复用和模块化是提高效率和维护性的关键。无论是构建 iOS 应用、macOS 软件，还是进行服务器端 Swift 开发，我们都不可避免地需要依赖外部代码库（或称为“包”、“库”、“框架”）来加速开发进程、利用社区的智慧结晶。Swift Package Manager (SPM) 作为 Apple 官方推出并深度集成到 Swift 生态系统中的依赖管理工具，正迅速成为 Swift 开发者的首选。它不仅简化了依赖的获取、集成和管理，还推动了 Swift 代码的共享和复用。本文将深入探讨 Swift Package Manager 的方方面面，助你全面掌握这个强大的工具，高效地管理你的项目依赖。

什么是 Swift Package Manager (SPM)？

Swift Package Manager（简称 SPM）是一个用于管理 Swift 代码分发和源代码依赖的工具。它与 Swift 构建系统紧密集成，能够自动化处理依赖项的下载、编译和链接过程。SPM 的核心目标是提供一种简单、一致且强大的方式来管理项目中的 Swift 代码依赖。

与 CocoaPods 或 Carthage 等第三方依赖管理工具相比，SPM 具有以下显著优势：

  1. 官方支持与深度集成：SPM 是 Apple 官方开发并维护的，与 Xcode 和 Swift 编译器无缝集成。这意味着更稳定、更可靠的体验，以及与 Apple 平台和工具链演进的同步更新。
  2. 基于约定优于配置：SPM 遵循特定的目录结构和命名约定，减少了配置的复杂性。一个标准的 SPM 包结构清晰易懂。
  3. 去中心化：SPM 包可以直接托管在 Git 仓库（如 GitHub, GitLab, Bitbucket）或其他支持 Git 协议的服务器上，无需中央仓库索引（尽管有 Package Collections 等特性来辅助发现）。这使得发布和获取包更加灵活直接。
  4. 基于 Swift 的清单文件：SPM 的配置文件 Package.swift 本身就是用 Swift 编写的，类型安全且具有强大的表达能力，允许进行更复杂的配置和逻辑控制。
  5. 跨平台潜力：SPM 不仅限于 Apple 平台开发，它也是服务器端 Swift 和跨平台 Swift 工具开发的核心组成部分。

SPM 的核心概念

要深入理解 SPM，首先需要掌握几个核心概念：

  1. 包 (Package)：一个包由 Swift 源代码、资源文件和一个清单文件 (Package.swift) 组成。清单文件定义了包的名称、目标（Targets）、产品（Products）以及它的依赖关系。一个包可以包含一个或多个目标。
  2. 模块 (Module)：在 Swift 中，模块是代码分发的基本单元。通常，SPM 中的一个目标（Target）会编译成一个模块。其他代码可以通过 import 语句来使用这个模块的功能。
  3. 目标 (Target)：目标指定了如何构建源代码。一个包可以包含多种类型的目标：
    • 常规目标 (Regular Target)：包含可以直接编译的 Swift 源代码（以及可能的其他语言如 C/C++/Objective-C）。
    • 测试目标 (Test Target)：包含用于测试包内其他目标代码的单元测试或集成测试代码。通常依赖于 XCTest 框架。
    • 系统库目标 (System Library Target)：用于封装系统提供的库，允许其他目标通过 SPM 链接到这些库，而无需 SPM 编译它们。通常用于包装 C 库。
    • 二进制目标 (Binary Target)：引用预编译好的二进制框架 (.xcframework)，而不是源代码。这对于分发闭源代码或大型框架很有用。
  4. 产品 (Product)：产品定义了包构建完成后可供外部使用的产物。主要有两种类型：
    • 库 (Library)：包含可被其他 Swift 代码导入和使用的模块。库可以是静态的（代码被复制到客户端）或动态的（在运行时加载）。
    • 可执行文件 (Executable)：一个可以独立运行的程序。
  5. 依赖 (Dependency)：一个包可以依赖于其他包。SPM 负责解析整个依赖图谱，下载并构建所有必需的依赖项。依赖关系在 Package.swift 文件中声明。
  6. 清单文件 (Package.swift)：这是 SPM 的核心配置文件。它是一个用 Swift 编写的脚本，描述了包的结构、内容、依赖关系以及如何构建。

Package.swift 清单文件详解

Package.swift 是理解和使用 SPM 的关键。它使用 Swift 语法定义了包的所有元数据和构建指令。一个典型的 Package.swift 文件结构如下：

```swift
// swift-tools-version:5.7
// The swift-tools-version declares the minimum version of Swift required to build this package.

import PackageDescription // 导入 PackageDescription 模块以访问相关 API

let package = Package(
name: "MyAwesomeLibrary", // 包的名称
platforms: [ // 指定支持的最低平台版本
.macOS(.v10_15),
.iOS(.v13),
.watchOS(.v6),
.tvOS(.v13)
],
products: [ // 定义包对外提供的产品
// 库产品：其他包或应用可以依赖和导入
.library(
name: "MyAwesomeLibrary", // 产品名称
type: .dynamic, // 可以是 .static 或 .dynamic (可选，默认为自动选择)
targets: ["MyAwesomeLibraryCore", "MyAwesomeLibraryUI"]), // 该产品包含的目标
// 可执行文件产品：可以独立运行
.executable(
name: "my-tool",
targets: ["MyTool"])
],
dependencies: [ // 声明外部依赖
// 依赖于另一个 SPM 包，指定 Git URL 和版本要求
.package(url: "https://github.com/Alamofire/Alamofire.git", .upToNextMajor(from: "5.6.0")),
// 可以指定分支、特定 commit hash 或本地路径
// .package(url: "../AnotherLocalPackage", .branch("develop")),
// .package(path: "../SiblingPackage"),
// .package(name: "SomeOtherName", url: "https://example.com/repo.git", .exact("1.2.3")) // 可以指定包名（如果与仓库名不同）
],
targets: [ // 定义包内的目标
// 常规目标：包含源代码
.target(
name: "MyAwesomeLibraryCore", // 目标名称 (通常对应 Sources/ 下的子目录)
dependencies: [
// 依赖于外部包的产品
"Alamofire",
// 依赖于包内的其他目标
.target(name: "InternalHelper"),
// 条件依赖 (示例，更常用于代码内 #if)
// .target(name: "SomeFeature", condition: .when(platforms: [.iOS]))
],
path: "Sources/Core", // 可选：指定源代码路径 (默认为 Sources/TargetName)
resources: [ // 处理资源文件
.process("Assets/Images.xcassets"), // 处理资源目录（如编译 Asset Catalogs）
.copy("Assets/data.json") // 直接复制文件或目录
],
swiftSettings: [ // Swift 编译器设置
.define("ENABLE_FEATURE_X")
],
linkerSettings: [ // 链接器设置
.linkedFramework("AuthenticationServices", .when(platforms: [.iOS, .macOS]))
]
),
.target(
name: "MyAwesomeLibraryUI",
dependencies: ["MyAwesomeLibraryCore"]
),
.target(
name: "InternalHelper" // 一个内部使用的目标，不包含在任何 library product 中
),
// 可执行文件目标
.target(
name: "MyTool",
dependencies: ["MyAwesomeLibraryCore"]
),
// 测试目标
.testTarget(
name: "MyAwesomeLibraryTests", // 目标名称 (通常对应 Tests/ 下的子目录)
dependencies: ["MyAwesomeLibraryCore", "MyAwesomeLibraryUI"]), // 依赖于要测试的目标
// 二进制目标
// .binaryTarget(
// name: "MyPrecompiledFramework",
// url: "https://example.com/MyPrecompiledFramework.xcframework.zip",
// checksum: "..." // 校验和，确保下载文件的完整性
// )
],
swiftLanguageVersions: [.v5], // 指定支持的 Swift 语言版本
cLanguageStandard: .c11, // C 语言标准
cxxLanguageStandard: .cxx14 // C++ 语言标准
)
```

关键点解读：

  • // swift-tools-version:5.7：必须放在文件顶部，声明了解析此文件所需的最低 SPM 工具版本，这间接决定了可用的 PackageDescription API。
  • platforms：明确包或其产品支持的最低操作系统版本。省略则表示支持所有平台的基础版本。
  • products：定义了包的公共接口。只有在这里声明的 library 或 executable 才能被其他包或应用程序使用。
  • dependencies：列出了项目所需的外部 Swift 包。SPM 支持多种版本约束：
    • .exact("1.2.3")：精确版本。
    • .upToNextMajor(from: "1.2.0")：允许从 1.2.0 到 < 2.0.0 的任何版本（推荐）。
    • .upToNextMinor(from: "1.2.0")：允许从 1.2.0 到 < 1.3.0 的任何版本。
    • .branch("main")：跟踪特定分支的最新提交。
    • .revision("commit-hash")：固定到某个特定的 commit。
    • .package(path: "../MyLocalPackage")：依赖本地文件系统中的另一个包，非常适合 monorepo 或本地开发调试。
  • targets：定义了源代码的组织和构建方式。每个 target 通常对应 Sources/TargetName 或 Tests/TargetName 目录。可以精细控制每个目标的依赖（包括外部包的产品或内部其他目标）、资源处理、编译器和链接器设置。
  • resources：允许将非代码文件（如图片、JSON、XIB、Storyboard、CoreData 模型等）包含在包中。.process 会进行平台相关的优化（如编译 .xcassets），.copy 则直接复制。
  • swiftSettings, linkerSettings 等：提供了更高级的构建配置选项。

在 Xcode 中使用 SPM

对于大多数 iOS、macOS、watchOS 和 tvOS 开发者来说，Xcode 是与 SPM 交互的主要界面。Xcode 对 SPM 的集成非常完善：

1. 添加包依赖：

  • 打开你的 Xcode 项目或工作区。
  • 选择项目导航器中的项目文件。
  • 选择你的 App Target 或 Project，然后切换到 "Package Dependencies" 标签页。
  • 点击 "+" 按钮。
  • 在弹出的窗口中，你可以：
    • 搜索 Apple 提供的包或你最近使用过的包。
    • 在右上角的搜索框中粘贴包的 Git URL（例如 https://github.com/Alamofire/Alamofire.git）。
  • Xcode 会解析包的清单文件。
  • 选择所需的版本规则（通常推荐 "Up to Next Major Version"）。
  • 选择要将包产品链接到的目标（Target）。
  • 点击 "Add Package"。

Xcode 会自动下载包的源代码，解析其依赖关系（递归进行），并将它们添加到你的项目中。你可以在项目导航器的 "Package Dependencies" 部分看到所有已添加的包及其源代码。

2. 管理包依赖：

  • 在 "Package Dependencies" 标签页中，你可以：
    • 查看所有已添加的包及其解析到的具体版本。
    • 右键点击包，选择 "Update Package" 来更新到满足版本规则的最新版本。
    • 右键点击包，选择 "Resolve Package Versions" 来重新解析所有包的版本（通常在遇到冲突或修改 Package.swift 文件后使用）。
    • 修改包的版本规则或移除包。

3. Package.resolved 文件：

当 Xcode（或 SPM 命令行）成功解析依赖关系后，会在项目的 .xcodeproj 或 .xcworkspace 的 project.xcworkspace/xcshareddata/swiftpm/ 目录下（对于独立包项目则在根目录）生成一个 Package.resolved 文件。这个文件锁定了每个依赖项的确切版本（commit hash）。强烈建议将 Package.resolved 文件提交到版本控制系统（如 Git）。这能确保团队中的每个成员以及 CI/CD 系统在构建项目时都使用完全相同的依赖版本，保证了构建的可复现性。

4. 使用包中的代码：

添加包依赖并将其链接到目标后，只需在你的 Swift 代码文件中使用 import ModuleName（ModuleName 通常是包的产品名或其包含的目标名）即可开始使用包提供的功能。

使用 SPM 命令行

SPM 不仅仅是 Xcode 的一部分，它也是一个强大的命令行工具，尤其对于服务器端 Swift 开发、创建可复用库或自动化构建流程至关重要。

打开终端，导航到包含 Package.swift 文件的目录，然后可以使用以下常用命令：

  • swift package init: 在当前目录初始化一个新的 Swift 包。可以指定类型，如 swift package init --type library（库）或 swift package init --type executable（可执行文件）。
  • swift build: 编译包中的所有目标。默认构建调试版本，使用 -c release 构建优化后的发布版本。
  • swift run [executable_name]: 编译并运行包中的可执行产品。如果只有一个可执行文件，可以省略名称。
  • swift test: 编译并运行包中的测试目标。
  • swift package update: 更新所有依赖项到满足 Package.swift 中版本约束的最新版本，并更新 Package.resolved 文件。
  • swift package resolve: 仅解析依赖关系并生成或更新 Package.resolved 文件，不进行下载或编译。
  • swift package describe: 以 JSON 或文本格式输出包的结构和依赖信息。
  • swift package clean: 清除构建产物（.build 目录）。
  • swift package reset: 清除构建产物并删除所有已下载的依赖项缓存。
  • swift package generate-xcodeproj: （已不推荐，但有时仍用于兼容旧系统）生成一个 Xcode 项目文件，用于在 Xcode 中打开和编辑包。现在 Xcode 可以直接打开包含 Package.swift 的目录。

命令行工具对于自动化脚本、CI/CD 集成以及不依赖 Xcode 的开发环境（如 Linux 上的服务器端 Swift）非常有用。

创建和发布你自己的 Swift 包

SPM 让创建和分享可复用的 Swift 代码变得异常简单：

  1. 初始化包：使用 swift package init --type library 创建一个标准的库包结构。这会生成 Package.swift, Sources/YourPackageName/YourPackageName.swift, Tests/YourPackageNameTests/YourPackageNameTests.swift 等文件和目录。
  2. 编写代码：在 Sources/YourPackageName 目录下实现你的库代码。确保代码是模块化的，并提供清晰的公共 API（使用 public 访问控制符）。
  3. 编写测试：在 Tests/YourPackageNameTests 目录下编写单元测试，确保代码的正确性。使用 swift test 运行测试。
  4. 配置 Package.swift：
    • 设置包名、支持的平台。
    • 在 products 部分定义一个 .library 产品，并将你的源代码目标（如 YourPackageName）添加到其 targets 数组中。
    • 如果你的库依赖其他 SPM 包，在 dependencies 部分声明它们，并在你的 target 中添加对应的依赖。
  5. 版本控制 (Git)：
    • 将你的包目录初始化为 Git 仓库 (git init)。
    • 添加 .gitignore 文件（通常忽略 .build/ 和 Package.resolved，但 Package.resolved 是否忽略取决于项目策略，对于库来说通常忽略）。
    • 提交你的代码 (git add ., git commit -m "Initial commit")。
    • 打标签 (Tagging)：这是发布包的关键步骤。SPM 使用 Git 标签来确定版本。遵循 语义化版本控制 (Semantic Versioning) 是最佳实践（例如 1.0.0, 1.1.0, 2.0.0）。使用 git tag 1.0.0 创建标签，然后 git push origin 1.0.0 将标签推送到远程仓库。
  6. 发布：将你的 Git 仓库推送到公共（如 GitHub）或私有 Git 服务器。用户现在可以通过在他们的 Package.swift 文件中添加你的 Git URL 和版本要求来依赖你的包了。

SPM 的高级特性

随着 SPM 的不断发展，它也引入了许多高级特性：

  • 二进制依赖 (binaryTarget)：允许包依赖于预编译的 .xcframework 二进制文件。这对于分发闭源库或加速大型依赖的构建非常有用。需要在 Package.swift 中指定二进制文件的 URL 和 SHA256 校验和。
  • 插件 (Plugins)：
    • 构建工具插件 (Build Tool Plugins)：可以在构建过程中运行，执行代码生成、资源处理等任务。例如，可以用插件基于 Protobuf 定义生成 Swift 代码。
    • 命令插件 (Command Plugins)：提供可以从 Xcode 菜单或 swift package 命令行触发的自定义命令。例如，用于代码格式化、文档生成等。
  • 资源处理 (resources)：如前所述，提供了 .process 和 .copy 两种方式来包含和处理非代码资源文件，使其能在运行时被访问。
  • 本地包依赖：使用 path: 语法依赖本地文件系统中的其他包，极大地促进了大型项目内的模块化开发（Monorepo 风格）和本地调试。
  • 条件化目标依赖 (condition)：允许基于平台或构建配置来决定是否包含某个目标依赖（虽然更常见的是在代码内部使用 #if 编译指令）。
  • 包集合 (Package Collections)：一种发现和分享 Swift 包的方式。组织或个人可以创建包含一组精选包的集合文件（JSON 格式），用户可以将这些集合添加到 Xcode 或 swift package-collection 命令行工具中，方便搜索和添加这些包作为依赖。

最佳实践与技巧

  • 遵循语义化版本控制 (SemVer)：为你的包打标签时严格遵守 SemVer 规范，这对于依赖你包的用户至关重要，能让他们安全地更新依赖。
  • 优先使用 .upToNextMajor：在声明依赖时，这是最推荐的版本约束，因为它允许自动获取补丁和次要版本更新（通常包含 bug 修复和非破坏性新特性），同时避免了可能引入破坏性更改的主版本更新。
  • 提交 Package.resolved：对于应用程序或最终产品项目，务必将 Package.resolved 文件纳入版本控制，以确保构建的可复现性。对于要被其他项目依赖的库，是否提交 Package.resolved 则有争议，通常不提交，让下游项目自己解析和锁定版本。
  • 定期更新依赖 (swift package update)：保持依赖项更新有助于获取最新的功能、性能改进和安全修复。但在更新前最好查看变更日志，并进行充分测试。
  • 利用本地包进行开发：当需要同时修改应用和其依赖的本地库时，使用 path: 依赖可以极大简化开发和调试流程。
  • 保持 Package.swift 清晰：对于复杂的包，可以使用 Swift 的特性（如变量、函数、注释）来组织和说明清单文件的内容。
  • 注意依赖图谱复杂度：过多的依赖或深层次的依赖嵌套可能导致解析时间变长、构建时间增加，甚至版本冲突。审慎选择依赖，并定期审视项目的依赖关系。
  • 理解依赖冲突解决：当项目的不同依赖项需要同一个包的不同（且不兼容）版本时，SPM 会尝试解决冲突。如果无法解决，你需要手动调整项目的直接依赖版本要求，或寻找替代方案。

SPM vs. CocoaPods vs. Carthage

虽然 SPM 是 Apple 的官方解决方案且发展迅速，但了解它与另外两个流行的 iOS/macOS 依赖管理工具 CocoaPods 和 Carthage 的主要区别仍然有益：

  • 集成度：SPM > CocoaPods > Carthage。SPM 与 Xcode 和 Swift 构建系统深度集成，体验最无缝。CocoaPods 需要通过修改 Xcode 项目文件（.xcworkspace）工作，集成度也相当高。Carthage 则相对独立，它只负责构建二进制框架，需要开发者手动将其集成到项目中。
  • 中心化 vs. 去中心化：CocoaPods 依赖一个中心化的 Spec 仓库。SPM 和 Carthage 都是去中心化的，直接从 Git 仓库获取。
  • 构建产物：SPM 主要处理源代码（虽然支持二进制），编译集成由 Xcode 完成。CocoaPods 也可以处理源代码或预编译库。Carthage 专注于构建预编译的二进制框架 (.framework 或 .xcframework)。
  • 配置：SPM 使用 Swift (Package.swift)。CocoaPods 使用 Ruby (Podfile)。Carthage 使用一种简单的文本格式 (Cartfile)。
  • 生态系统：CocoaPods 拥有最庞大、最成熟的库生态系统，尤其是一些较老的 Objective-C 库。SPM 的生态正在快速增长，并且是新 Swift 库的首选。Carthage 的库数量相对较少。
  • 未来趋势：SPM 作为 Apple 的官方工具，无疑是未来的发展方向，预计将获得持续的投入和改进，生态系统也将越来越完善。

选择哪个工具取决于项目需求、团队熟悉度和特定的库支持情况。但对于新项目和纯 Swift 项目，SPM 通常是最佳选择。

结语

Swift Package Manager 已经从一个最初主要面向服务器端 Swift 的工具，演变成了 Apple 生态系统中强大、灵活且深度集成的依赖管理解决方案。它简化了依赖管理流程，促进了代码共享，并通过其 Swift 编写的清单文件提供了强大的配置能力。无论是使用 Xcode 添加依赖，还是通过命令行管理复杂的包结构，亦或是创建和发布自己的 Swift 库，掌握 SPM 都已成为现代 Swift 开发者的必备技能。

随着 SPM 的不断成熟和生态系统的日益繁荣，它将继续在简化 Swift 开发工作流程、提高代码质量和复用性方面发挥核心作用。花时间深入理解其核心概念、Package.swift 的语法以及各种使用场景，无疑会为你的 Swift 开发之旅带来巨大的便利和效率提升。开始拥抱 Swift Package Manager，让它成为你管理项目依赖的得力助手吧！

版权声明：
作者：admin
链接：https://hostlocvps.com/2025/04/01/%e6%8e%8c%e6%8f%a1-swift-package-manager%ef%bc%9a%e7%ae%a1%e7%90%86%e4%bd%a0%e7%9a%84%e9%a1%b9%e7%9b%ae%e4%be%9d%e8%b5%96/
文章版权归作者所有，未经允许请勿转载。
THE END
RStudio 是什么？ 给 R 语言初学者的全面介绍
<<上一篇
Another Redis Desktop Manager 下载与快速入门
下一篇>>
相关推荐
STM32Cube常见问题及解决方案
Scala 2.12 升级指南
Q绑查询工具：在线版使用教程
设置 Python 环境变量：一步一步的指导
C# SortedList：如何进行高效的排序和查找
HTTP 错误 503：故障排除指南
UniApp实战项目案例分享
正则表达式在线测试工具：实时输出结果
什么是 503 错误以及如何修复它？
解读 SSH Keygen 的输出：快速上手密钥生成