Cargo metadata 怎么只导出工作区包信息

如果 CI 只需要知道一个 Rust workspace 有哪些包，直接读取完整的 cargo metadata 结果往往会把依赖解析图也带进脚本。更稳妥的做法是固定 JSON 输出版本，再加上 --no-deps，让本次任务只围绕工作区成员展开。

官方地址：https://doc.rust-lang.org/cargo/commands/cargo-metadata.html

cargo metadata --format-version 1 --no-deps 是本文的最小命令：--format-version 1 固定机器可读格式，--no-deps 把输出边界收窄到 workspace members；结果中的 resolve 不再提供完整依赖解析图。

先把任务入口定成“工作区元数据”

这个命令适合给 CI、发布脚本或工程工具读取 workspace 的包清单。它输出的是面向机器的 JSON，不是给人浏览的 Cargo.toml 摘要。实际操作时，可以把任务在自己的工具界面中命名为“工作区元数据”，再把输出方式设为“JSON”。

本文后面的界面图是原创操作示意图，用来帮助理解配置和结果状态，不是 Cargo、Rust、IDE 或 CI 平台的真实截图。真正执行时，仍以项目目录中的 Cargo 配置和命令行返回值为准。

固定输出格式再开始读取字段

官方文档建议显式传入 --format-version，这样脚本不会把 Cargo 的默认输出变化当成自己的数据契约。当前命令文档列出的可用格式版本是 1，因此最小配置可以写成：

# 固定 Cargo 元数据 JSON 的格式版本，避免脚本依赖未声明的默认值
cargo metadata --format-version 1

# 需要指定 workspace manifest 时，用 --manifest-path 明确入口文件
cargo metadata --format-version 1 --manifest-path path/to/Cargo.toml

这一步只固定“输出长什么样”，还没有收窄“输出哪些对象”。如果脚本下一步只想枚举 workspace 包，还要继续加上 --no-deps。

打开 no-deps，只导出工作区包信息

把配置面板中的“只导出工作区包”打开，对应的命令就是：

# 只读取工作区成员的机器可读元数据，不把完整依赖解析图带入本次结果
cargo metadata --format-version 1 --no-deps

这里的“只导出工作区包”指 packages 数组不再把外部依赖包作为本次包清单展开，输出重点转向 workspace members。它不是把每个工作区包的 Cargo.toml 字段全部删掉；工作区包自身的依赖声明仍可能作为包定义的一部分出现。脚本要区分“包定义里的依赖声明”和“完整的依赖解析图”。

如果项目存在虚拟 workspace，当前工作目录不一定对应某一个根 package，但 workspace_members 仍然可以作为成员边界使用。需要调用某个 manifest 时，优先给出显式的 --manifest-path，减少 CI 工作目录变化带来的歧义。

按四个字段核对导出结果

配置完成后，不要只看命令是否退出成功，还要确认 JSON 的关键字段符合任务边界。可以把结果验收拆成四个屏幕区域：

1. packages：查看当前导出的包定义，确认它服务于工作区包清单。
2. workspace_members：查看成员 Package ID 列表，这是判断 workspace 成员范围的核心字段。
3. workspace_root：记录 workspace 根目录，避免脚本把别的项目当成当前项目。
4. resolve：使用 --no-deps 时不把它当成完整解析结果；文档所描述的依赖解析对象会是 null。

# 先导出固定版本的工作区元数据，再提取包名和成员 ID
cargo metadata --format-version 1 --no-deps \
  | jq '{packages: [.packages[].name], workspace_members, workspace_root, resolve}'

上面的 jq 只是在结果上做字段投影，不改变 Cargo 的输出。对于严格 JSON 的下游脚本，应该按真实 JSON 解析，不要用正则去截取包名。还要允许未来出现新增字段，因为格式版本相同并不意味着字段永远不会增加。

把命令接到 CI 时保留错误边界

在 CI 中，建议把元数据命令当成一个有明确退出码的输入步骤：命令成功后再解析 JSON，命令失败时保留错误并停止后续包处理。不要因为输出为空就直接把它判断成“没有工作区包”，先区分命令错误、JSON 解析错误和确实没有匹配成员。

# 让 shell 在命令失败或管道中任一步失败时停止，避免把错误当成空清单
set -o errexit
set -o pipefail

# 固定输出版本和工作区边界，供后续脚本读取
cargo metadata --format-version 1 --no-deps > workspace-metadata.json

# 只打印工作区包名；解析失败会让 CI 步骤返回非零状态
jq -r '.packages[].name' workspace-metadata.json

如果 CI 在多个子目录运行，最好统一使用 --manifest-path，并在日志中记录 workspace_root。这样包数量变化时，可以回到同一个 workspace 根目录判断是成员变更，还是工作目录选错。

几个容易混淆的边界

常见问题

为什么必须写 --format-version 1？

因为脚本需要知道自己按照哪个 JSON 格式读取。显式传入版本可以减少对默认行为的依赖，也便于未来在升级 Cargo 时检查兼容边界。

--no-deps 会不会让 workspace 包自身的依赖声明消失？

不要把它理解成删除所有依赖字段。它主要收窄被输出的包范围，并且不提供完整的依赖解析图；工作区包自身的 manifest 信息仍可能含有依赖声明。

为什么 workspace_members 不是包名数组？

它保存的是 Package ID。脚本若需要展示名称，应根据 ID 与 packages 中的包定义建立关联，不要靠字符串截取路径或版本。

只导出工作区包后还能做依赖拓扑分析吗？

本文的命令不适合这个目标。依赖拓扑需要完整的解析信息，应单独设计输入和执行边界，不要把 --no-deps 的结果当成完整依赖图。

最终可以把配置路径记成：固定 format-version，开启 --no-deps，再按 packages、workspace_members、workspace_root 和 resolve 四处核对。这样 Cargo metadata 才真正成为 CI 可以稳定消费的工作区包信息入口。