Swift Package Manager 包集合搜索完全指南：swift package-collection search 关键词与模块检索实战

swift package-collection search 是 Swift Package Manager（SwiftPM）提供的子命令，用于在已导入的包集合（Package Collections）中按关键词或模块名检索包。本文将基于 PackageCollectionSearch.md 官方文档，并结合仓库源码深入讲解两种搜索模式的用法、--json 输出集成、底层匹配与存储原理，以及完整命令行参数说明。读完本文，你将能熟练用该命令在本地缓存的包集合中精准定位目标包，并把它接入自己的脚本与工具链。

一、命令定位与使用前提

package-collection search 属于 swift package-collection 命令族。在源码 PackageCollectionsCommand.swift 中，PackageCollectionsCommand 通过 ArgumentParser 注册了六个子命令：add、describe、list、refresh、remove 和 search，其中 search 的抽象描述正是 "Search for packages by keywords or module names."。

该子命令自 Swift 5.5 起可用（文档元数据 @Available("Swift", introduced: "5.5")）。

使用前提：搜索作用于"已导入（imported）的集合"，即搜索的是本地已添加并缓存的集合数据，而不是直接访问网络。因此在搜索之前，通常需要先用 swift package-collection add <collection-url> 添加集合、用 swift package-collection refresh 刷新集合内容。若本地没有任何已配置的集合，搜索会直接返回空结果——源码 PackageCollections.swift 中，findPackages 先通过 storage.sources.list() 读取已配置集合，过滤后 identifiers 为空即返回空结果集。

二、两种搜索模式

search 子命令通过 --keywords 或 --module 两个互斥标志选择搜索方式，二者都接收一个位置参数 search-query 作为查询词。对应源码中的 SearchMethod 枚举与 Search 命令结构（PackageCollectionsCommand.swift）：

enum SearchMethod: String, EnumerableFlag {
    case keywords
    case module
}

2.1 关键词字符串搜索（--keywords）

--keywords 模式对查询词做字符串匹配，返回所有命中包：

$ swift package-collection search [--json] --keywords yaml
https://github.com/jpsim/yams: A sweet and swifty YAML parser built on LibYAML.
...

从源码看，该模式调用 collections.findPackages(searchQuery, collections: nil)，命中后逐条打印 "\($0.package.identity): \($0.package.summary ?? "")"，即 包身份标识（identity）加摘要（summary）。上例中 https://github.com/jpsim/yams 就是该包的 identity（包身份由仓库 URL 推导），冒号后是包描述。

字符串搜索的匹配范围很广。在存储层 SQLitePackageCollectionsStorage.swift 的 searchPackages 实现中，当没有可用搜索索引时，会遍历每个集合内的包，对以下字段做大小写不敏感的包含匹配（任意一个命中即算匹配）：

• 包身份 identity
• 包位置/仓库地址 location
• 包摘要 summary
• 包关键词 keywords
• 每个版本的 manifest 中的 packageName、产品名 products、目标名 targets

也就是说，用 --keywords 不仅能搜包名，还能搜到仓库地址、简介文字、标签关键词，甚至包内模块/目标名称。

2.2 模块名搜索（--module）

--module 模式针对模块（target/module）名做精确匹配：

$ swift package-collection search [--json] --module yams
Package Name: Yams
Latest Version: 4.0.0
Description: A sweet and swifty YAML parser built on LibYAML.
--------------------------------------------------------------
...

源码中该模式调用 collections.findTargets(searchQuery, searchType: .exactMatch, collections: nil)，随后对命中结果用 Set 做包去重（同一包可能在不同版本/集合中反复命中同一模块）。需要说明的是：文档中的示例输出是早期版本的展示格式；当前源码实际输出格式为 "\($0.identity): \($0.summary ?? "")"（PackageCollectionsCommand.swift），即打印包身份与摘要，若需查看包名、最新版本、模块列表等完整元数据，可配合 swift package-collection describe <package-url> 命令获取。

与字符串搜索不同，模块搜索的默认匹配类型是 exactMatch（精确匹配），支持的大小写不敏感比较。TargetSearchType 在 Search.swift 中定义为两种：

public enum TargetSearchType {
    case prefix      // 前缀匹配
    case exactMatch  // 精确匹配
}

搜索命令固定使用 exactMatch；prefix 类型保留给库的编程 API 使用。

2.3 JSON 输出与工具链集成

两种模式都支持 --json，将结果以 JSON 形式输出，便于接入其他工具。--json 标志定义于 JSONOptions（PackageCollectionsCommand.swift），输出时使用 JSONEncoder.makeWithDefaults() 编码并打印（PackageCollectionsCommand.swift）。

以 --keywords 为例，JSON 输出的是 PackageSearchResult.Item 数组，每个元素包含：

• package：命中的包（含版本、manifest、许可证、作者等元数据）
• collections：包含该包的集合标识列表
• indexes：包含该包的包索引 URL 列表

对应结构体定义见 Search.swift。--module 模式的 JSON 输出则是去重后的包对象列表。

三、底层实现原理

3.1 数据流：从命令到本地存储

search 命令的运行链路可概括为：

Search.run()
  └─ withState() 构造 PackageCollections 实例
       ├─ --keywords: findPackages(query)  → storage.collections.searchPackages(...)
       └─ --module:   findTargets(query, .exactMatch) → storage.collections.searchTargets(...)

PackageCollections 是命令背后统一的编程接口（PackageCollections.swift），其初始化只依赖 configurationDirectory 与 cacheDirectory 两个本地路径——这也解释了为什么搜索完全离线进行：集合内容在导入时被持久化到本地存储（默认 SQLite 数据库），搜索操作只读取本地缓存，不产生网络请求。只有在执行 add/refresh 时才会联网拉取集合源。

存储层的 searchPackages/searchTargets 均有两条执行路径（SQLitePackageCollectionsStorage.swift）：

1. 降级路径（无搜索索引）：直接读取本地集合数据，在内存中对各字段做包含/精确匹配；
2. 索引路径（FTS 全文索引）：当 SQLite 中存在全文搜索索引时，searchPackages 会执行一条对 name、summary、keywords、products、targets、repository_url、id 七个字段统一做 LIKE '%query%' 的 SQL 查询，随后只反查包含命中包的集合，避免加载全部数据（源码注释标注了"Optimization: fetch only those collections that contain matching packages"）。

3.2 模块搜索的 Trie 加速

对于目标（模块）搜索，仓库实现了一个基于 Trie（字典树） 的数据结构 Trie.swift 来加速精确与前缀匹配。模块名按字符逐层插入 Trie，每个终止节点记录出现该模块的（集合、包、包地址）文档集合；查询时：

• find(word:) 精确查找模块名对应的文档集合；
• findWithPrefix(prefix:) 收集所有以该前缀开头的模块词及其文档集合。

Trie 内部对节点的子节点与文档集合均加了 NSLock 保护，支持并发读写，并在集合刷新时同步维护（见 SQLitePackageCollectionsStorage.swift 中 targetTrie 的使用：索引就绪时优先走 Trie，否则退化为全量内存遍历）。

3.3 平台与包索引（Package Index）扩展

PackageCollections 对运行平台有限制：isSupportedPlatform 仅在 macOS、Linux、Windows、Android 上为 true（PackageCollections.swift），其他平台调用搜索会抛出 PackageCollectionError.unsupportedPlatform。

此外，仓库还实现了可选的 Package Index（包索引）支持：通过环境变量 SWIFTPM_ENABLE_PACKAGE_INDEX=1 启用（PackageIndex+Configuration.swift）。启用后，PackageIndexAndCollections.swift 的 findPackages 支持 SearchIn 指定仅在索引、仅集合或两者中搜索。不过 package-collection search 命令当前固定走集合搜索路径，索引能力通过 PackageIndexAndCollections 的编程 API 暴露。

四、完整命令行参数详解

下面是 swift package-collection search 的完整用法与全部参数说明（完整继承自官方文档 PackageCollectionSearch.md）。其中大部分为 SwiftPM 全局通用选项，search 特有的是前三项。

package-collection search [--json] --keywords --module
  <search-query> [--package-path=<package-path>]
  [--cache-path=<cache-path>] [--config-path=<config-path>]
  [--security-path=<security-path>]
  [--scratch-path=<scratch-path>]
  [--swift-sdks-path=<swift-sdks-path>]
  [--toolset=<toolset>...]
  [--pkg-config-path=<pkg-config-path>...]
  [--enable-dependency-cache] [--disable-dependency-cache]
  [--enable-build-manifest-caching]
  [--disable-build-manifest-caching]
  [--manifest-cache=<manifest-cache>]
  [--enable-experimental-prebuilts]
  [--disable-experimental-prebuilts] [--verbose]
  [--very-verbose|vv] [--quiet] [--color-diagnostics]
  [--no-color-diagnostics] [--disable-sandbox] [--netrc]
  [--enable-netrc] [--disable-netrc]
  [--netrc-file=<netrc-file>] [--enable-keychain]
  [--disable-keychain]
  [--resolver-fingerprint-checking=<resolver-fingerprint-checking>]
  [--resolver-signing-entity-checking=<resolver-signing-entity-checking>]
  [--enable-signature-validation]
  [--disable-signature-validation] [--enable-prefetching]
  [--disable-prefetching]
  [--force-resolved-versions|disable-automatic-resolution|only-use-versions-from-resolved-file]
  [--skip-update] [--disable-scm-to-registry-transformation]
  [--use-registry-identity-for-scm]
  [--replace-scm-with-registry]
  [--default-registry-url=<default-registry-url>]
  [--configuration=<configuration>] [--=<Xcc>...]
  [--=<Xswiftc>...] [--=<Xlinker>...] [--=<Xcxx>...]
  [--triple=<triple>] [--sdk=<sdk>] [--toolchain=<toolchain>]
  [--swift-sdk=<swift-sdk>] [--sanitize=<sanitize>...]
  [--auto-index-store] [--enable-index-store]
  [--disable-index-store]
  [--enable-parseable-module-interfaces] [--jobs=<jobs>]
  [--use-integrated-swift-driver]
  [--explicit-target-dependency-import-check=<explicit-target-dependency-import-check>]
  [--build-system=<build-system>] [--=<debug-info-format>]
  [--enable-dead-strip] [--disable-dead-strip]
  [--disable-local-rpath] [--version] [--help]

4.1 搜索核心选项

参数	说明
--json	以 JSON 格式输出结果，便于其他工具集成解析
--keywords / --module	选择搜索方式：--keywords 为字符串匹配搜索，--module 为模块名精确搜索，二者互斥必选其一
<search-query>	搜索查询词（位置参数）

4.2 路径与目录选项

参数	说明
--package-path=<package-path>	指定操作的包路径（默认当前目录），会在其他操作前切换工作目录
--cache-path=<cache-path>	指定共享缓存目录路径
--config-path=<config-path>	指定共享配置目录路径
--security-path=<security-path>	指定共享安全目录路径
--scratch-path=<scratch-path>	指定自定义 scratch（构建临时）目录，默认 .build
--swift-sdks-path=<swift-sdks-path>	已安装 Swift SDK 所在目录路径
--toolset=<toolset>	指定构建目标平台时使用的 toolset JSON 文件；可多次指定，多个 toolset 按指定顺序合并为最终 toolset
--pkg-config-path=<pkg-config-path>	指定搜索 pkg-config .pc 文件的替代路径；可多次指定多个路径

4.3 缓存与依赖解析选项

参数	说明
--enable-dependency-cache / --disable-dependency-cache	是否使用共享缓存获取依赖
--enable-build-manifest-caching / --disable-build-manifest-caching	是否启用构建 manifest 缓存
--manifest-cache=<manifest-cache>	Package.swift manifest 的缓存模式，合法值：shared（共享缓存）、local（包的构建目录）、none（禁用）
--enable-experimental-prebuilts / --disable-experimental-prebuilts	是否对宏使用预编译的 swift-syntax 库
--enable-prefetching / --disable-prefetching	是否启用依赖预取
--skip-update	解析时跳过从远程更新依赖
--force-resolved-versions / --disable-automatic-resolution / --only-use-versions-from-resolved-file	仅使用 Package.resolved 文件中的版本，若文件过期则解析失败
--disable-scm-to-registry-transformation	禁用源代码控制（SCM）到注册表（Registry）的转换
--use-registry-identity-for-scm	在注册表中查找 SCM 依赖并尽量使用注册表身份，帮助跨两种来源去重
--replace-scm-with-registry	在注册表中查找 SCM 依赖，并尽可能改用注册表获取而非源代码控制
--default-registry-url=<default-registry-url>	默认注册表 URL，代替 registries.json 配置文件

4.4 安全与凭据选项

参数	说明
--disable-sandbox	执行子进程时禁用沙箱
--netrc	即使有其他更优先的凭据存储，也使用 netrc 文件
--enable-netrc / --disable-netrc	是否从 netrc 文件加载凭据
--netrc-file=<netrc-file>	指定 netrc 文件路径
--enable-keychain / --disable-keychain	是否在 macOS 钥匙串中搜索凭据
--resolver-fingerprint-checking=<resolver-fingerprint-checking>	解析器指纹检查策略
--resolver-signing-entity-checking=<resolver-signing-entity-checking>	解析器签名实体检查策略
--enable-signature-validation / --disable-signature-validation	是否校验从注册表下载的已签名包发布的签名

4.5 编译与工具链选项

参数	说明
--configuration=<configuration>	以指定配置构建
--=<Xcc>	将参数透传给所有 C 编译器调用
--=<Xswiftc>	将参数透传给所有 Swift 编译器调用
--=<Xlinker>	将参数透传给所有链接器调用
--=<Xcxx>	将参数透传给所有 C++ 编译器调用
--triple=<triple>	指定目标三元组
--sdk=<sdk>	指定 SDK
--toolchain=<toolchain>	指定工具链
--swift-sdk=<swift-sdk>	筛选用于构建的特定 Swift SDK
--sanitize=<sanitize>	开启运行时错误行为检查，可选值：address、thread、undefined、scudo
--auto-index-store / --enable-index-store / --disable-index-store	是否启用边构建边索引（indexing-while-building）特性
--enable-parseable-module-interfaces	生成可解析的模块接口
--jobs=<jobs>	构建过程中并行产生的任务数
--use-integrated-swift-driver	使用集成的 Swift driver
--explicit-target-dependency-import-check=<explicit-target-dependency-import-check>	构建时检查目标是否只导入其显式声明的依赖
--build-system=<build-system>	指定构建系统
--=<debug-info-format>	使用的调试信息格式
--enable-dead-strip / --disable-dead-strip	是否启用链接器死代码剥离
--disable-local-rpath	禁用默认将 $ORIGIN/@loader_path 加入 rpath

4.6 输出与信息选项

参数	说明
--verbose	提高冗长级别，包含信息性输出
--very-verbose / -vv	提高冗长级别，包含调试输出
--quiet	降低冗长级别，仅输出错误
--color-diagnostics / --no-color-diagnostics	输出到 TTY 时启用/禁用彩色诊断；默认连接 TTY 时启用，否则禁用
--version	显示版本号
--help	显示帮助信息

五、实战建议与注意事项

1. 搜索前先导入与刷新集合：search 只查本地已导入集合。首次使用建议先 swift package-collection add <url> 添加官方或第三方集合（添加时可使用 --trust-unsigned 信任未签名集合、--skip-signature-check 跳过签名校验，对应逻辑见 PackageCollectionsCommand.swift），再用 swift package-collection refresh 拉取最新内容，最后执行搜索。

2. 匹配大小写不敏感：无论字符串搜索还是模块搜索，底层都会先 lowercased() 再比较（见 SQLitePackageCollectionsStorage.swift），因此查询 YAML、yaml、Yaml 结果一致。

3. --keywords 范围广、--module 更精确：--keywords 会对包名、仓库地址、摘要、关键词、模块名、产品名做包含匹配，适合"模糊回忆"场景；--module 只对模块名精确匹配，适合"我知道这个库导出哪个模块"的场景（例如想 import Yams 前确认集合里是否有该模块）。

4. 离线可用、无网络开销：搜索读取的是本地 SQLite 存储与 Trie 索引（SQLitePackageCollectionsStorage.swift、Trie.swift），构建脚本或 CI 中可以放心高频调用，不必担心网络访问。

5. 结果为空时的排查：若搜索无结果，先确认集合确实已导入（swift package-collection list），再确认集合内确实包含含该关键词/模块的包（可 swift package-collection describe <collection-url> 查看集合内的完整包列表）。注意命令在非受支持平台会直接抛错。

6. 配合 describe 获取详情：search 只输出 identity 与摘要；需要查看包的最新版本、可用版本列表、许可、作者、语言等信息时，用 swift package-collection describe <package-url>，该命令的 printVersion 实现见 PackageCollectionsCommand.swift。

六、小结

swift package-collection search 是 SwiftPM 包集合生态中面向开发者的检索入口：--keywords 提供覆盖身份、摘要、关键词、模块与产品名的宽泛字符串搜索，--module 提供基于 Trie 的精确模块定位，--json 让结果可以无缝进入其他自动化工具。从命令层（PackageCollectionsCommand.swift）到接口层（API.swift、PackageCollections.swift）再到存储层（SQLitePackageCollectionsStorage.swift、Trie.swift），整个链路清晰且完全离线，是了解 SwiftPM 包集合子系统设计的一个绝佳切入点。更多命令（如 add、describe、list、refresh、remove）的说明可参考 PackageCollections 文档目录下的其他页面。