05-cargo metadata

cargo-metadata(1) 机器可读元数据

译文 · 基于 The Cargo Book

cargo-metadata(1)

原文链接: https://doc.rust-lang.org/cargo/commands/cargo-metadata.html

名称

cargo-metadata — 关于当前包的机器可读元数据

大纲

cargo metadata [options]

描述

向 stdout 输出 JSON,其中包含当前包的工作空间成员与已解析依赖的信息。

输出格式可能在 Cargo 未来版本中变更。建议包含 --format-version 标志以使代码面向未来,并确保输出符合预期格式。关于预期,见「兼容性」。

参见 cargo_metadata crate 获取用于读取元数据的 Rust API。

输出格式

兼容性

在同一输出格式版本内,兼容性会得以保持,但某些场景除外。以下是不被视为不兼容变更的非穷尽列表:

  • 添加新字段 — 需要时会添加新字段。保留此能力有助于 Cargo 演进,而无需过于频繁地提升格式版本。
  • 为类枚举字段添加新值 — 与添加新字段相同。这使元数据能够演进而不停滞。
  • 更改不透明表示 — 某些字段的内部表示是实现细节。例如,与「Source ID」相关的字段被视为不透明标识符,用于区分包或来源。除非另有说明,消费者不应依赖这些表示。

JSON 格式

JSON 输出具有以下格式:

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
{
    /* 工作空间中所有包的数组。
       除非使用 --no-deps,否则还包括所有启用了特性的依赖。
    */
    "packages": [
        {
            /* 包的名称。 */
            "name": "my-package",
            /* 包的版本。 */
            "version": "0.1.0",
            /* 用于在文档内引用该包以及作为许多命令的 `--package` 参数的 Package ID。 */
            "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.",
            /* 包的 source ID,表示包来源的「不透明」标识符。稳定性保证见上文「兼容性」。

               路径依赖与工作空间成员为 null。

               对于其他依赖,它是如下格式的字符串:
               - 基于注册表的依赖为 "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 注册表的依赖为 "sparse+URL"。
                 示例:"sparse+https://my-sparse-registry.org"

               `+` 之后的值没有明确定义,可能在 Cargo 版本之间变化,
               且不一定与配置文件中的注册表定义等其他内容直接对应。
               未来可能添加具有不同 `+` 前缀标识符的新来源种类。
            */
            "source": null,
            /* 包清单中声明的依赖数组。 */
            "dependencies": [
                {
                    /* 依赖的名称。 */
                    "name": "bitflags",
                    /* 依赖的 source 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,
                    /* 是否启用默认特性的布尔值。 */
                    "uses_default_features": true,
                    /* 已启用的特性数组。 */
                    "features": [],
                    /* 依赖的目标平台。
                       非目标依赖时为 null。
                    */
                    "target": "cfg(windows)",
                    /* 本地路径依赖的文件系统路径。
                       非路径依赖时不存在。
                    */
                    "path": "/path/to/dep",
                    /* 此依赖所属注册表 URL 的字符串。
                       未指定或为 null 时,依赖来自默认注册表(crates.io)。
                    */
                    "registry": null,
                    /* (不稳定)是否为 public 依赖的布尔标志。
                       仅在启用 `-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",
                    /* 必需特性数组。
                       若未设置必需特性,则不包含此属性。
                    */
                    "required-features": ["feat1"],
                    /* 该目标是否应由 `cargo doc` 生成文档。 */
                    "doc": true,
                    /* 该目标是否启用了 doc 测试,且目标与 doc 测试兼容。 */
                    "doctest": false,
                    /* 该目标是否应使用 `--test` 构建并运行。 */
                    "test": true
                }
            ],
            /* 为包定义的特性集合。
               每个特性映射到它启用的特性或依赖数组。
            */
            "features": {
                "default": [
                    "feat1"
                ],
                "feat1": [],
                "feat2": []
            },
            /* 此包清单的绝对路径。 */
            "manifest_path": "/path/to/my-package/Cargo.toml",
            /* 包元数据。
               未指定元数据时为 null。
            */
            "metadata": {
                "docs": {
                    "rs": {
                        "all-features": true
                    }
                }
            },
            /* 此包可发布到的注册表列表。
               为 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",
    ],
    // 整个工作空间的已解析依赖图。启用的特性基于「当前」包启用的特性。
    // 未激活的可选依赖不会列出。
    //
    // 若指定 --no-deps,则为 null。
    //
    // 默认包含所有目标平台的所有依赖。
    // 可用 --filter-platform 标志缩小到特定目标三元组。
    "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": [
                    "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",
    /* 此元数据结构的 schema 版本。
       若做出不兼容变更,此值会改变。
    */
    "version": 1,
    /* 工作空间根的绝对路径。 */
    "workspace_root": "/path/to/my-package"
    /* 工作空间元数据。
       未指定元数据时为 null。 */
    "metadata": {
        "docs": {
            "rs": {
                "all-features": true
            }
        }
    }
}

说明:

选项

输出选项

--no-deps

仅输出工作空间成员的信息,不获取依赖。

--format-version version

指定要使用的输出格式版本。目前 1 是唯一可能的值。

--filter-platform triple

将 resolve 输出过滤为仅包含给定目标三元组的依赖。可使用字面量 "host-tuple",内部将替换为宿主目标。未使用此标志时,resolve 包含所有目标。

请注意,「packages」数组中列出的依赖仍包含所有依赖。每个包定义旨在完整再现 Cargo.toml 中的信息。

特性选择

特性标志用于控制启用哪些特性。若未指定特性选项,每个所选包都会激活 default 特性。

参见特性文档了解更多详情。

-F features
--features features

空格或逗号分隔的要激活的特性列表。工作空间成员的特性可用 package-name/feature-name 语法启用。此标志可指定多次,以启用所有指定的特性。

--all-features

激活所有所选包的全部可用特性。

--no-default-features

不激活所选包的 default 特性。

显示选项

-v
--verbose

使用详细输出。可指定两次以获得“非常详细”的输出,其中包含依赖警告与构建脚本输出等额外信息。也可通过 term.verbose 配置值 指定。

-q
--quiet

不打印 cargo 日志消息。也可通过 term.quiet 配置值 指定。

--color when

控制何时使用彩色输出。有效值:

  • auto(默认):自动检测终端是否支持颜色。
  • always:始终显示颜色。
  • never:从不显示颜色。

也可通过 term.color 配置值 指定。

清单选项

--manifest-path path

Cargo.toml 文件的路径。默认情况下,Cargo 在当前目录或任意父目录中搜索 Cargo.toml 文件。

--locked

断言使用的依赖与版本与最初生成现有 Cargo.lock 文件时完全相同。出现以下任一情况时 Cargo 将以错误退出:

  • 锁文件缺失。
  • Cargo 因不同的依赖解析而试图更改锁文件。

可用于需要确定性构建的环境,例如 CI 流水线。

--offline

阻止 Cargo 以任何理由访问网络。若未指定此标志,当 Cargo 需要访问网络而网络不可用时会以错误停止。指定此标志后,Cargo 会在可能时尝试在无网络情况下继续。

请注意,这可能导致与在线模式不同的依赖解析。Cargo 会将自身限制为本地已下载的 crate,即便本地索引副本表明可能有更新版本。可先使用 cargo-fetch(1) 命令下载依赖再离线。

也可通过 net.offline 配置值 指定。

--frozen

等价于同时指定 --locked 与 --offline。

通用选项

+toolchain

若 Cargo 通过 rustup 安装,且传给 cargo 的第一个参数以 + 开头,则会被解释为 rustup 工具链名称(例如 +stable 或 +nightly)。关于工具链覆盖如何工作,见 rustup 文档。

--config KEY=VALUE or PATH

覆盖 Cargo 配置值。参数应为 TOML 语法的 KEY=VALUE,或指向额外配置文件的路径。此标志可指定多次。更多信息见 命令行覆盖一节。

-C PATH

在执行任何指定操作之前更改当前工作目录。这会影响 Cargo 默认查找项目清单(Cargo.toml)的位置,以及用于发现 .cargo/config.toml 的目录搜索等。此选项必须出现在命令名称之前,例如 cargo -C path/to/my-project build。

此选项仅在 nightly 通道 上可用,且需要 -Z unstable-options 标志才能启用(见 #10098)。

-h
--help

打印帮助信息。

-Z flag

Cargo 的不稳定(仅 nightly)标志。运行 cargo -Z help 查看详情。

环境

关于 Cargo 读取的环境变量详情,见参考文档。

退出状态

  • 0:Cargo 成功。
  • 101:Cargo 未能完成。

示例

  1. 输出当前包的 JSON:

    cargo metadata --format-version=1
    

参见

cargo(1), cargo-pkgid(1), 包 ID 规范, JSON 消息

最后修改 August 11, 2026: 更新 (70a5af133)