入门 The Cargo Team 2026-09-13 15:48:22 · 0 阅读

第52章 Cargo Metadata：以机器可读形式输出包元数据

名称

cargo-metadata — 以机器可读的形式输出当前包的元数据

概要

cargo metadata [options]

描述

向标准输出打印 JSON，内容包含当前包所在 workspace 的成员及已解析的依赖信息。

输出格式在未来版本的 Cargo 中可能会变化。建议在代码中始终带上 --format-version 参数，以确保输出符合你预期的格式，避免未来出现兼容问题。详见“兼容性”。

如果需要用 Rust API 来读取这些元数据，可以参考 cargo_metadata crate。

输出格式

兼容性

在同一个输出格式版本内，兼容性是保持不变的，但以下场景除外。下面列出的改动不算不兼容变更（并非穷举）：

新增字段 — 有需要时就会添加新字段。保留这种自由度可以让 Cargo 持续演进，而不必频繁提升格式版本。
为类枚举字段新增取值 — 同新增字段一样，这样元数据才能持续发展而不会停滞。
变更不透明的表示形式 — 某些字段的内部表示属于实现细节。例如，与“Source ID”相关的字段被视为不透明的标识符，仅用于区分不同的包或来源。除非有明确说明，使用者不应依赖这些内部表示。

JSON 格式

JSON 输出格式如下：

{
    /* 工作区中所有包的数组。
       默认还包括所有启用 feature 的依赖项，除非使用 --no-deps。
    */
    "packages": [
        {
            /* 包名。 */
            "name": "my-package",
            /* 包的版本。 */
            "version": "0.1.0",
            /* 包标识符（Package ID），用于在文档中引用该包，以及作为许多命令的 --package 参数。 */
            "id": "file:///path/to/my-package#0.1.0",
            /* 清单中的 license 值，或 null。 */
            "license": "MIT/Apache-2.0",
            /* 清单中的 license-file 值，或 null。 */
            "license_file": "LICENSE",
            /* 清单中的 description 值，或 null。 */
            "description": "Package description.",
            /* 包的源 ID（Source ID），一个不透明的标识符，表示包的获取来源。
               稳定性保证见上文“兼容性”部分。

               对于路径依赖和工作区成员，此值为 null。

               对于其他依赖项，它是一个字符串，格式如下：
               - 基于 registry 的依赖项使用 "registry+URL"。
                 示例："registry+https://github.com/rust-lang/crates.io-index"
               - 基于 Git 的依赖项使用 "git+URL"。
                 示例："git+https://github.com/rust-lang/cargo?rev=5e85ba14aaa20f8133863373404cb0af69eeef2c#5e85ba14aaa20f8133863373404cb0af69eeef2c"
               - 来自 sparse registry 的依赖项使用 "sparse+URL"
                 示例："sparse+https://my-sparse-registry.org"

               `+` 后的值没有明确定义，可能随 Cargo 版本变化，也不直接对应配置文件中的 registry 定义。
               未来可能会添加新的源类型，使用不同的 `+` 前缀标识符。
            */
            "source": null,
            /* 包清单中声明的依赖项数组。 */
            "dependencies": [
                {
                    /* 依赖项名称。 */
                    "name": "bitflags",
                    /* 依赖项的源 ID。可能为 null，参见包 source 的描述。 */
                    "source": "registry+https://github.com/rust-lang/crates.io-index",
                    /* 依赖项的版本要求。
                       没有版本要求的依赖项，值为 "*"。
                    */
                    "req": "^1.0",
                    /* 依赖项类型。
                       "dev"、"build"，或普通依赖项为 null。
                    */
                    "kind": null,
                    /* 如果依赖项重命名，此项为新名称。未重命名则为 null。 */
                    "rename": null,
                    /* 是否为可选依赖项。 */
                    "optional": false,
                    /* 是否启用默认 features。 */
                    "uses_default_features": true,
                    /* 已启用 features 的数组。 */
                    "features": [],
                    /* 依赖项的目标平台。
                       非目标特定依赖项则为 null。
                    */
                    "target": "cfg(windows)",
                    /* 本地路径依赖项的文件系统路径。
                       非路径依赖项则不包含此项。
                    */
                    "path": "/path/to/dep",
                    /* 该依赖项所属 registry 的 URL 字符串。
                       如果未指定或为 null，则表示来自默认 registry（crates.io）。
                    */
                    "registry": null,
                    /* （不稳定）布尔标志，指示是否为公共依赖项。
                       仅当启用 `-Zpublic-dependency` 时存在此字段。
                    */
                    "public": false
                }
            ],
            /* Cargo 目标数组。 */
            "targets": [
                {
                    /* 目标类型数组。
                       - lib 目标列出清单中的 `crate-type` 值，如 "lib"、"rlib"、"dylib"、"proc-macro" 等（默认 ["lib"]）
                       - binary 为 ["bin"]
                       - example 为 ["example"]
                       - 集成测试为 ["test"]
                       - benchmark 为 ["bench"]
                       - 构建脚本为 ["custom-build"]
                    */
                    "kind": [
                        "bin"
                    ],
                    /* Crate 类型数组。
                       - lib 和 example 库列出清单中的 `crate-type` 值，如 "lib"、"rlib"、"dylib"、"proc-macro" 等（默认 ["lib"]）
                       - 其他所有目标类型均为 ["bin"]
                    */
                    "crate_types": [
                        "bin"
                    ],
                    /* 目标名称。
                       对于 lib 目标，连字符将替换为下划线。
                    */
                    "name": "my-package",
                    /* 目标根源文件的绝对路径。 */
                    "src_path": "/path/to/my-package/src/main.rs",
                    /* 目标的 Rust edition。
                       默认继承包的 edition。
                    */
                    "edition": "2018",
                    /* 必需 features 数组。
                       如果未设置必需 features，则不包含此属性。
                    */
                    "required-features": ["feat1"],
                    /* 目标是否应由 `cargo doc` 生成文档。 */
                    "doc": true,
                    /* 此目标是否启用了 doc tests，且目标兼容 doc 测试。 */
                    "doctest": false,
                    /* 此目标是否应使用 `--test` 构建和运行。 */
                    "test": true
                }
            ],
            /* 包定义的 features 集合。
               每个 feature 映射到一个数组，包含它启用的 features 或依赖项。
            */
            "features": {
                "default": [
                    "feat1"
                ],
                "feat1": [],
                "feat2": []
            },
            /* 指向此包清单的绝对路径。 */
            "manifest_path": "/path/to/my-package/Cargo.toml",
            /* 包元数据。
               如果未指定元数据，则为 null。
            */
            "metadata": {
                "docs": {
                    "rs": {
                        "all-features": true
                    }
                }
            },
            /* 此包可发布的 registry 列表。
               如果为 null，则发布不受限制；如果为空数组，则禁止发布。 */
            "publish": [
                "crates-io"
            ],
            /* 清单中的作者数组。
               如果未指定作者，则为空数组。
            */
            "authors": [
                "Jane Doe <user@example.com>"
            ],
            /* 清单中的分类数组。 */
            "categories": [
                "command-line-utilities"
            ],
            /* 可选字符串，为 `cargo run` 选择的默认二进制文件。 */
            "default_run": null,
            /* 可选字符串，为最低支持 Rust 版本。 */
            "rust_version": "1.56",
            /* 清单中的关键词数组。 */
            "keywords": [
                "cli"
            ],
            /* 清单中的 readme 值，未指定则为 null。 */
            "readme": "README.md",
            /* 清单中的 repository 值，未指定则为 null。 */
            "repository": "https://github.com/rust-lang/cargo",
            /* 清单中的 homepage 值，未指定则为 null。 */
            "homepage": "https://rust-lang.org",
            /* 清单中的 documentation 值，未指定则为 null。 */
            "documentation": "https://doc.rust-lang.org/stable/std",
            /* 包的默认 edition。
               注意单个目标可能有不同的 edition。
            */
            "edition": "2018",
            /* 可选字符串，为包链接的原生库名称。 */
            "links": null,
        }
    ],
    /* 工作区成员数组。
       每个条目为包的 Package ID。
    */
    "workspace_members": [
        "file:///path/to/my-package#0.1.0",
    ],
    /* 工作区默认成员数组。
       每个条目为包的 Package ID。
    */
    "workspace_default_members": [
        "file:///path/to/my-package#0.1.0",
    ],
    // 整个工作区解析后的依赖图。启用的 features 基于“当前”包启用的 features。
    // 未激活的可选依赖项不在列表中。
    //
    // 如果指定了 --no-deps，此值为 null。
    //
    // 默认情况下，这包括所有目标平台的所有依赖项。
    // 可以使用 `--filter-platform` 标志将范围缩小到特定的目标 triple。
    "resolve": {
        /* 依赖图中节点的数组。
           每个节点是一个包。
        */
        "nodes": [
            {
                /* 此节点的 Package ID。 */
                "id": "file:///path/to/my-package#0.1.0",
                /* 此包的依赖项，Package ID 数组。 */
                "dependencies": [
                    "https://github.com/rust-lang/crates.io-index#bitflags@1.0.4"
                ],
                /* 此包的依赖项。这是 "dependencies" 的替代方案，包含额外信息。
                   特别地，它处理重命名的依赖项。
                */
                "deps": [
                    {
                        /* 依赖项库目标的名称。
                           如果是重命名的依赖项，这是新名称。
                        */
                        "name": "bitflags",
                        /* 依赖项的 Package ID。 */
                        "pkg": "https://github.com/rust-lang/crates.io-index#bitflags@1.0.4"
                        /* 依赖项类型数组。在 Cargo 1.40 中添加。 */
                        "dep_kinds": [
                            {
                                /* 依赖项类型。
                                   "dev"、"build"，或普通依赖项为 null。
                                */
                                "kind": null,
                                /* 依赖项的目标平台。
                                   非目标特定依赖项则为 null。
                                */
                                "target": "cfg(windows)"
                            }
                        ]
                    }
                ],
                /* 在此包上启用的 features 数组。 */
                "features": [
                    "default"
                ]
            }
        ],
        /* 当前工作目录中的包（如果未提供 --manifest-path）。
           如果是虚拟工作区，则为 null。否则为包的 Package ID。
        */
        "root": "file:///path/to/my-package#0.1.0",
    },
    /* Cargo 输出所在目标目录的绝对路径。 */
    "target_directory": "/path/to/my-package/target",
    /* Cargo 中间构建产物所在构建目录的绝对路径。（不稳定） */
    "build_directory": "/path/to/my-package/build-dir",
    /* 此元数据结构架构的版本。
       如果进行不兼容变更，此值会更改。
    */
    "version": 1,
    /* 工作区根目录的绝对路径。 */
    "workspace_root": "/path/to/my-package"
    /* 工作区元数据。
       如果未指定元数据，则为 null。 */
    "metadata": {
        "docs": {
            "rs": {
                "all-features": true
            }
        }
    }
}

说明：

关于"id"字段的语法，请参阅参考文档中的Package ID 规范。

选项

输出选项

--no-deps

仅输出工作区成员的信息，不获取依赖项。

--format-version version

指定输出格式的版本。目前仅支持1。

--filter-platform triple

过滤resolve的输出，使其仅包含指定目标三元组的依赖项。可以使用字面量"host-tuple"，内部将替换为宿主机的目标架构。如果不提供此标志，resolve 将包含所有目标架构的依赖。

请注意，“packages”数组中列出的依赖项仍包含所有依赖。每个包的定义旨在作为Cargo.toml中信息的未修改副本。

特性选择

特性标志可用于控制启用的特性。如果不提供特性选项，将为每个选中的包激活default特性。

更多详情，请参阅特性文档。

-F features
--features features: 要启用的 feature 列表，以空格或逗号分隔。workspace 成员的 feature 可通过 package-name/feature-name 语法启用。该选项可以多次指定，所有指定的 feature 都会被启用。
--all-features: 启用所选包的所有可用 feature。
--no-default-features: 不启用所选包的 default feature。