Swift Package Manager 的 `swift package` 命令完全指南：创建、编辑、检查与维护 Swift 包

开发工具构建工具【免费下载链接】swift-package-managerThe Package Manager for the Swift Programming Language项目地址https://gitcode.com/gh_mirrors/sw/swift-package-manager点击查看免费下载swift package是 Swift Package ManagerSwiftPM提供的核心命令行工具集用于创建、更新、检查、编辑与维护 Swift 包。本指南以仓库内 SwiftPackageCommands.md 的官方命令清单为骨架逐条讲解每个子命令的作用、语法与关键参数并结合 Sources/Commands/PackageCommands 下的真实实现源码说明命令背后的解析与执行机制。读完本文你将能够熟练使用swift package init创建各类包、用update/resolve管理依赖版本、用add-*系列命令免手写修改 Package.swift、用describe/show-dependencies等命令检查包结构以及完成清理缓存、归档打包、配置镜像、生成 SBOM 等日常维护工作。swift package命令总览swift package是一个命令命名空间namespace自身并不直接执行操作而是通过一系列子命令完成更新和检查你的 Swift 包update and inspect your Swift package的工作。在源码中这一命名空间由 SwiftPackageCommand.swift 定义public struct SwiftPackageCommand: AsyncParsableCommand { public static var configuration CommandConfiguration( commandName: package, _superCommandName: swift, abstract: Perform operations on Swift packages., discussion: SEE ALSO: swift build, swift run, swift test \n(Run this command without --help to see possible dynamic plugin commands.), version: SwiftVersion.current.completeDisplayString, subcommands: Self.subcommands, defaultSubcommand: DefaultCommand.self, helpNames: [] ) }从源码可以看到两个关键点它基于 Apple 的ArgumentParser框架构建子命令列表在subcommands数组中静态注册它有一个隐藏的DefaultCommand当你直接运行swift package something而没有匹配到任何内建子命令时SwiftPM 会把something当作**命令插件command plugin**来查找并执行这就是swift package与swift plugin插件生态衔接的入口见 SwiftPackageCommand.swift。官方文档将全部子命令划分为以下主题对应 SwiftPackageCommands.md 的 Topics 章节主题子命令创建包init更新与解析依赖update、resolve编辑包add-dependency、add-product、add-target、add-target-dependency、add-setting、edit、unedit、migrate使用包管理器插件plugin、diagnose-api-breaking-change检查包describe、show-dependencies、show-executables、show-traits、tools-version、dump-package、dump-symbol-graph清理构建产物与缓存clean、reset、purge-cache归档包archive-source、compute-checksum集成到 Shellcompletion-tool配置镜像config set-mirror、config unset-mirror、config get-mirror生成 SBOMgenerate-sbom实验性命令experimental-install、experimental-uninstall通用选项几乎所有子命令共享的全局参数在阅读每个子命令之前需要先理解一组贯穿所有子命令的通用选项。无论init、update还是resolve它们都接受如下公共参数以下参数说明均取自 PackageInit.md 等各子命令文档中完全一致的定义路径与目录类--package-pathpackage-path指定要操作的包路径默认是当前目录。该选项会在任何其他操作之前先切换工作目录。--cache-pathcache-path指定共享缓存目录路径。--config-pathconfig-path指定共享配置目录路径。--security-pathsecurity-path指定共享安全目录路径。--scratch-pathscratch-path指定自定义构建中间目录scratch directory默认.build。--swift-sdks-pathswift-sdks-path包含已安装 Swift SDK 的目录路径。--toolsettoolset...指定构建目标平台时要使用的 toolset JSON 文件可多次传入以指定多个 toolset多个 toolset 会按指定顺序合并成最终的一个 toolset。--pkg-config-pathpkg-config-path...指定搜索 pkg-config.pc文件的备选路径可多次指定。缓存与预编译类--enable-dependency-cache/--disable-dependency-cache是否在获取依赖时使用共享缓存。--enable-build-manifest-caching/--disable-build-manifest-caching构建清单缓存的开关。--manifest-cachemanifest-cachePackage.swift 清单的缓存模式合法值为shared共享缓存、local包的构建目录与none禁用。--enable-experimental-prebuilts/--disable-experimental-prebuilts是否使用预编译的 swift-syntax 库来加速宏macro编译实验性。输出与诊断类--verbose提高详细程度输出信息性informational内容。--very-verbose/--vv进一步提高详细程度输出调试debug内容。--quiet降低详细程度只输出错误error内容。--color-diagnostics/--no-color-diagnostics是否在输出到 TTY 时启用彩色诊断。默认在连接 TTY 时启用、否则禁用。安全与凭据类--disable-sandbox执行子进程时禁用沙箱。--netrc即使有其他更受青睐的凭据存储也强制使用 netrc 文件。--enable-netrc/--disable-netrc是否从 netrc 文件加载凭据。--netrc-filenetrc-file指定 netrc 文件路径。--enable-keychain/--disable-keychain是否在 macOS keychain 中搜索凭据。--resolver-fingerprint-checkingresolver-fingerprint-checking依赖解析器指纹检查策略。--resolver-signing-entity-checkingresolver-signing-entity-checking依赖解析器签名实体检查策略。--enable-signature-validation/--disable-signature-validation是否校验从 registry 下载的已签名包发布版本。依赖解析类--enable-prefetching/--disable-prefetching依赖预取开关。--force-resolved-versions/--disable-automatic-resolution/--only-use-versions-from-resolved-file只使用 Package.resolved 文件中的版本如果文件过期则解析失败。--skip-update解析过程中跳过从远端更新依赖。--disable-scm-to-registry-transformation禁用源码控制到 registry的转换。--use-registry-identity-for-scm在 registry 中查找源码控制依赖并在可能时使用其 registry 身份帮助跨两种来源去重。--replace-scm-with-registry在 registry 中查找源码控制依赖并在可能时用 registry 代替源码控制来获取它们。--default-registry-urldefault-registry-url指定默认 registry URL取代registries.json配置文件。编译与构建类--configurationconfiguration以指定配置构建。--Xcc...将标志透传给所有 C 编译器调用。--Xswiftc...将标志透传给所有 Swift 编译器调用。--Xlinker...将标志透传给所有链接器调用。--Xcxx...将标志透传给所有 C 编译器调用。--tripletriple指定目标三元组。--sdksdk指定 SDK。--toolchaintoolchain指定工具链。--swift-sdkswift-sdk过滤器选择要使用的特定 Swift SDK 进行构建。--sanitizesanitize...开启运行时错误行为检查可选值address、thread、undefined、scudo。--auto-index-store/--enable-index-store/--disable-index-store启用或禁用边构建边索引indexing-while-building功能。--enable-parseable-module-interfaces启用可解析的模块接口。--jobsjobs构建过程中并行生成的任务数。--use-integrated-swift-driver使用集成式 Swift 驱动。--explicit-target-dependency-import-checkexplicit-target-dependency-import-check指示本次构建检查目标是否只 import 其显式声明的依赖。--build-systembuild-system选择构建系统。--debug-info-format要使用的调试信息格式Debug Information Format。--enable-dead-strip/--disable-dead-strip启用/禁用链接器的死代码剥离。--disable-local-rpath禁用默认向 rpath 添加$ORIGIN/loader_path。--version显示 SwiftPM 版本。--help显示帮助信息。创建包swift package initswift package init用于初始化一个新的包。它除了上述通用选项外还独有三个关键参数--typetype包的模板类型。文档明确列出了以下取值library—— 含库的包executable—— 含可执行文件的包tool—— 使用 Swift Argument Parser 的可执行包如果你计划设计一套丰富的命令行参数选这个模板build-tool-plugin—— 提供构建工具插件的包command-plugin—— 提供命令插件的包macro—— 提供宏的包empty—— 只有 Package.swift 清单的空包。--enable-xctest/--disable-xctest是否启用 XCTest 支持。--enable-swift-testing/--disable-swift-testing是否启用 Swift Testing 支持。--namename提供自定义包名。典型用法# 在当前目录创建库包 swift package init --type library # 创建命令行工具包基于 Swift Argument Parser swift package init --type tool --name my-cli # 创建宏包 swift package init --type macro # 创建空的、只有清单的包 swift package init --type empty对应的实现位于 Sources/Commands/PackageCommands/Init.swift它会调用Workspace层的InitPackage逻辑生成目录结构、Package.swift 清单与模板源文件。更新与解析依赖update与resolveswift package updateswift package update用于更新包依赖把依赖刷新到符合约束的最新版本。除了通用选项它有两个特有参数--dry-run只显示可以更新哪些依赖的列表不真正执行更新。packages...要更新的包名列表可传多个限定只更新这些包。# 更新所有依赖 swift package update # 只看有哪些依赖可以更新不实际更新 swift package update --dry-run # 只更新指定的包 swift package update MyLibraryswift package resolveswift package resolve用于解析包依赖把 Package.swift 中的版本约束解析成具体版本并写入 Package.resolved。与update不同的是resolve默认不主动升级到新版本而是保持已解析的状态。它特有如下参数--versionversion解析到指定版本。--branchbranch解析到指定分支。--revisionrevision解析到指定修订commit。package-name要解析的包名。--traitstraits启用包的指定 traits。多个 trait 用逗号分隔例如--traits Trait1,Trait2。注意启用特定 traits 时需要显式传入defaults以同时启用默认 traits。--enable-all-traits启用包的全部 traits。--disable-default-traits禁用包的全部默认 traits。# 按 Package.swift 约束重新解析所有依赖 swift package resolve # 将某依赖固定解析到指定版本 swift package resolve MyLibrary --version 1.2.3 # 解析到指定分支 swift package resolve MyLibrary --branch main # 强制只使用 Package.resolved 中的版本过期则报错 swift package resolve --force-resolved-versions # 启用特定 trait同时需要显式启用 defaults swift package resolve MyLibrary --traits defaults,TraitA从源码结构看update与resolve的实现分别位于 Update.swift 和 Resolve.swift二者最终都驱动Workspace层WorkspaceDependencies.swift的依赖解析器完成版本求解--force-resolved-versions等选项对应的仅使用 Package.resolved策略即是让解析器跳过对远端版本目录的重新获取。编辑包add-*系列与edit/unedit/migrateSwiftPM 提供了一组直接修改 Package.swift 清单的命令让你不必手写清单语法即可添加依赖、产品、目标、目标依赖与编译设置。这一组命令的实现都位于 Sources/Commands/PackageCommands 下并依赖 PackageModel/ManifestSourceGeneration.swift 中的清单源码生成逻辑——它们会解析现有清单、在内存中修改模型、再重新生成 Package.swift 文件。swift package add-dependency向清单添加包依赖。位置参数dependency是包的 URL 或本地目录。版本约束通过以下互斥选项表达--exactexact依赖精确版本。--revisionrevision依赖特定修订commit。--branchbranch依赖指定分支。--fromfrom依赖某版本允许升到下一个大版本之前。--up-to-next-minor-fromup-to-next-minor-from依赖某版本允许升到下一个次要版本之前。--toto指定版本范围的上界不含该上界。--typetype指定依赖类型。# 依赖精确版本 swift package add-dependency https://example.com/repos/MyLib.git --exact 2.0.0 # 从 1.5.0 起允许升级到 2.0.0 之前的版本即 1.5.0 2.0.0 swift package add-dependency https://example.com/repos/MyLib.git --from 1.5.0 # 允许升级到下一个 minor 版本之前 swift package add-dependency https://example.com/repos/MyLib.git --up-to-next-minor-from 1.5.0 # 限制版本上界不含 swift package add-dependency https://example.com/repos/MyLib.git --from 1.0.0 --to 2.0.0 # 依赖指定分支 swift package add-dependency https://example.com/repos/MyLib.git --branch main # 使用本地目录作为依赖 swift package add-dependency ../MyLocalLib --from 1.0.0swift package add-product向清单添加新产品。位置参数name是新产品名特有参数--typetype产品类型库、可执行文件等。--targetstargets...属于该产品的目标列表可多次传。swift package add-product MyLibrary --type library --targets MyLibrary MyLibraryUtilsswift package add-target向清单添加新目标。位置参数name是目标名特有参数--typetype要添加的目标类型。--dependenciesdependencies...目标依赖名列表。--urlurl远程二进制目标的 URL。--pathpath本地二进制目标的路径。--checksumchecksum远程二进制目标的校验和。--testing-librarytesting-library生成测试目标时使用的测试库可选xctest、swift-testing或none。# 添加一个依赖其他目标的常规目标 swift package add-target MyModule --dependencies MyLib # 添加一个远程二进制目标 swift package add-target MyBinary --url https://example.com/binary.zip --checksum sha256 # 添加一个测试目标使用 Swift Testing swift package add-target MyModuleTests --type test --testing-library swift-testingswift package add-target-dependency向清单添加目标依赖给指定目标声明一个依赖。位置参数dependency-name是要新增的依赖名target-name是要更新的目标名另有--packagepackage依赖所属的包。# 让 MyModule 依赖同包内的 MyLib 目标 swift package add-target-dependency MyLib MyModule # 让 MyModule 依赖外部包 OtherPackage 中的目标 swift package add-target-dependency MyLib MyModule --package OtherPackageswift package add-setting向清单添加编译设置。特有参数--targettarget必需要添加设置的目标。--swiftswift...必需可多次要添加的 Swift 语言设置。文档明确列出支持的值experimentalFeature、upcomingFeature、languageMode、strictMemorySafety。# 为目标启用 upcoming feature swift package add-setting --target MyModule --swift upcomingFeature MemberImportVisibility # 为目标设置语言模式 swift package add-setting --target MyModule --swift languageMode v6swift package edit与swift package uneditswift package edit package-name [--revisionrevision]把某个依赖检出到本地进行临时编辑调试对应实现见 EditCommands.swift 与 WorkspaceEditing.swift。编辑期间该依赖的版本固定为你检出的状态改动可立即参与本包构建。swift package unedit package-name [--force]结束编辑状态让依赖回到正常的版本解析流程若本地编辑有未提交改动通常需要--force才能放弃改动恢复托管。# 开始编辑某个依赖 swift package edit MyLib # 结束编辑并恢复托管 swift package unedit MyLib --forceswift package migrateswift package migrate用于执行迁移操作例如把旧版清单迁移到新版语法或进行available/existential any等 Swift 语言层面的自动迁移对应实现见 Migrate.swift相关测试位于 Tests/FunctionalTestsFixtures 可参考 Fixtures/SwiftMigrate 目录下的ExistentialAnyMigration、UpdateManifest等场景。使用插件swift package plugin与diagnose-api-breaking-changeswift package pluginswift package plugin [--allow-writing-to-package-directory] command [arguments...]用于执行包内声明的命令插件command plugin。如果直接运行swift package command且命令名能匹配到某个插件SwiftPM 也会自动路由到插件见前文DefaultCommand的实现。命令插件的声明方式、权限模型与执行流程可参考 Documentation/Design 下的插件设计文档以及 Sources/Commands/PackageCommands/PluginCommand.swift 和 Fixtures/Plugins 中的大量插件示例。swift package diagnose-api-breaking-changeswift package diagnose-api-breaking-change baseline-version-or-path用于诊断 API 破坏性变更把当前包的 API 与指定基线版本或路径比较输出可能破坏兼容性的变化清单。它底层复用swift-api-digesterSwiftPM 侧的实现见 Sources/Commands/PackageCommands/APIDiff.swift仓库自带的 API 对比测试夹具位于 Fixtures/Miscellaneous/APIDiff。# 与已打 tag 的 1.2.3 版本对比 swift package diagnose-api-breaking-change 1.2.3 # 与本地某个目录对比 swift package diagnose-api-breaking-change /path/to/baseline检查包describe、show-dependencies、dump-* 等这一组命令用于读取并输出包的信息是 CI 脚本与调试时最常用的工具swift package describe [--typejson|text]以文本或 JSON 形式描述包的完整结构目标、产品、依赖、路径等实现见 Describe.swift。swift package show-dependencies [--formattext|json|dot]输出包的依赖图支持文本、JSON 与 Graphviz dot 三种格式实现见 ShowDependencies.swift。swift package show-executables列出包提供的可执行目标实现见 ShowExecutables.swift。swift package show-traits列出包声明的 traits条件特性实现见 ShowTraits.swift。swift package tools-version [--set version] [--set-current]查看或设置包的 Swift tools 版本对应实现见 ToolsVersionCommand.swift更完整的说明见 SettingSwiftToolsVersion.md。swift package dump-package输出 Package.swift 清单解析后的 JSON 表示DumpPackage对应 DumpCommands.swift。swift package dump-symbol-graph输出包的符号图symbol graph供文档生成工具使用同样位于 DumpCommands.swift。# 以 JSON 输出包结构 swift package describe --type json # 以 dot 格式导出依赖图可配合 Graphviz 渲染 swift package show-dependencies --format dot # 查看当前 tools 版本 swift package tools-version # 设置 tools 版本 swift package tools-version --set 6.0清理构建产物与缓存clean、reset、purge-cacheswift package clean清理构建产物删除.build目录中的构建中间文件实现见 ResetCommands.swift 中的Clean。swift package reset彻底重置构建状态删除整个.build目录下次构建将全量重建。swift package purge-cache清空 SwiftPM 的共享缓存目录依赖缓存、清单缓存等对应PurgeCache。# 清理本次构建产物保留缓存 swift package clean # 完全重置构建目录 swift package reset # 清空共享缓存 swift package purge-cache归档与校验archive-source、compute-checksumswift package archive-source [--outputpath]把当前包归档为 zip 源码包通常用于发布实现见 ArchiveSource.swift。swift package compute-checksum path计算某个归档文件的 SHA-256 校验和注册二进制目标时Package.swift 的checksum:参数需要这个值实现见 ComputeChecksum.swift。# 打包源码 swift package archive-source --output /tmp/MyPackage.zip # 计算校验和用于在清单中声明远程二进制目标 swift package compute-checksum /tmp/MyPackage.zip集成到 Shellcompletion-toolswift package completion-tool用于生成命令补全脚本生成 bash/zsh/fish 的补全配置便于把swift package的子命令与选项补全集成进你的 Shell对应实现见 CompletionCommand.swift更完整的用法见 UsingShellCompletion.md。配置镜像config set-mirror / unset-mirror / get-mirror镜像mirror用于把某个 Git 仓库 URL 重定向到替代地址例如公司内网镜像实现位于 Config.swiftswift package config set-mirror original-url --mirror-url mirror-url [--scope scope]为原始 URL 设置镜像。swift package config unset-mirror original-url [--scope scope]移除镜像。swift package config get-mirror original-url [--scope scope]查询某 URL 的镜像地址。# 为 https://example.com/repos/MyLib.git 设置镜像 swift package config set-mirror https://example.com/repos/MyLib.git --mirror-url https://mirror.internal/MyLib.git # 查询镜像 swift package config get-mirror https://example.com/repos/MyLib.git # 移除镜像 swift package config unset-mirror https://example.com/repos/MyLib.git镜像配置的底层持久化与解析逻辑可参考 PackageGraph/DependencyMirrors.swift。生成 SBOMgenerate-sbomswift package generate-sbom [--output-pathpath] [--formatspdx|cyclonedx]用于生成当前包依赖的软件物料清单SBOM支持 SPDX 与 CycloneDX 两种格式实现见 GenerateSBOM.swift格式模型位于 Sources/SBOMModel含 SPDX 与 CycloneDX 的编码/校验实现。更完整的说明见 GeneratingSBOMs.md。# 生成默认格式SPDX的 SBOM 到当前目录 swift package generate-sbom # 指定输出路径与格式 swift package generate-sbom --output-path /tmp/sbom.json --format cyclonedx实验性命令experimental-install / experimental-uninstallswift package experimental-install executable-target [--prefixpath]把包中的可执行目标安装到指定前缀目录默认安装到usr/local风格的目录实现见 Install.swift。swift package experimental-uninstall name [--prefixpath]卸载之前安装的可执行文件。# 安装可执行目标 swift package experimental-install my-tool --prefix /usr/local # 卸载 swift package experimental-uninstall my-tool --prefix /usr/local这两个命令被标记为 experimental接口与行为可能随版本演进而变化生产环境使用前建议先在测试环境验证。深入命令是如何被解析与执行的最后从源码层面梳理swift package的完整调用链帮助你理解上述命令的共同机制入口是 Sources/swift-package/Entrypoint.swift它把命令行交给SwiftPackageCommandSwiftPackageCommand.swift。ArgumentParser根据第一个位置参数匹配subcommands数组中的子命令类型AddDependency.self、Update.self、Describe.self等。每个子命令通过OptionGroup携带GlobalOptions即上文通用选项通过各自的Option/Argument/Flag声明特有参数。参数校验通过后run(_ swiftCommandState:)被调用最终驱动Workspace层Sources/Workspace完成依赖解析、清单加载与构建等实际工作。若子命令名未匹配任何内建命令DefaultCommand会尝试把该名称解析为包内的命令插件并执行——这解释了为什么swift package plugin-command能直接工作。官方文档对每个子命令的完整语法与参数定义都对应着仓库中的子命令页面Package 目录下的PackageInit.md、PackageUpdate.md、PackageResolve.md、PackageAddDependency.md等文档需要查看某个具体命令的完整参数清单时直接运行swift package subcommand --help是最可靠的来源。赞分享开发工具构建工具【免费下载链接】swift-package-managerThe Package Manager for the Swift Programming Language项目地址https://gitcode.com/gh_mirrors/sw/swift-package-manager点击查看免费下载相关推荐Swift Package Manager 依赖编辑实战swift package edit 命令完全指南Swift Package Manager 依赖编辑实战swift package edit 命令完全指南 swift package edit 是 Swif开发工具构建工具Swift Package Manager swift package add-setting 命令完全指南通过命令行向 Manifest 添加 Swift 编译设置Swift Package Manager swift package add setting 命令完全指南通过命令行向 Manifest 添加 Swift开发工具构建工具Swift Package Manager 的 swift package-collection list 命令完全指南列出已配置的 Package CollectionsSwift Package Manager 的 swift package collection list 命令完全指南列出已配置的 Package Coll开发工具构建工具上一篇Ice用三个分区管好 macOS 菜单栏下一篇Terragrunt安全最佳实践保护基础设施代码的10个技巧创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考