入门 The Cargo Team 2026-09-13 15:48:23 · 1 阅读

第66章 Cargo 包管理：本地包打包与发布指南

名称

cargo-package — 将本地 package 打包为可分发的 tarball

概要

cargo package [options]

描述

该命令会把当前目录中 package 的源代码打包成一个可分发的压缩 .crate 文件，生成的文件存放在 target/package 目录下。整个过程包括以下步骤：

加载并检查当前 workspace，执行一些基础校验。
- 不允许使用 Path 依赖，除非指定了 version。发布 package 时，Cargo 会忽略依赖中的 path 字段。dev-dependencies 不受此限制。
创建压缩的 .crate 文件。
- 原始的 Cargo.toml 文件会被重写并规范化。
- manifest 中的 [patch]、[replace] 和 [workspace] 段会被移除。
- 始终包含 Cargo.lock。如果缺少该文件，会自动生成新的 lock 文件，除非使用了 --exclude-lockfile 标志。使用 --locked 标志时，cargo-install(1) 会采用打包内的 lock 文件。
- 包含一个 .cargo_vcs_info.json 文件，记录当前 VCS checkout 的 hash（如果可用），以及工作区是否有未提交修改的标志。
- 符号链接会被替换为其指向的目标文件。
- 文件和目录按照 [include] 和 [exclude] 字段中描述的规则来决定是否打包。
解压 .crate 文件并进行构建，验证其可构建。
- 这一步会从头完整重新构建 package，确保它能在干净状态下成功构建。可以使用 --no-verify 标志跳过此步骤。
检查 build scripts 是否修改了任何源文件。

可以通过 manifest 中的 include 和 exclude 字段控制打包时包含哪些文件。

更多关于打包和发布的细节，请参阅参考文档。

.cargo_vcs_info.json 格式

将生成如下格式的 .cargo_vcs_info.json 文件

{
 "git": {
   "sha1": "aac20b6e7e543e6dd4118b246c77225e3a3a1302",
   "dirty": true
 },
 "path_in_vcs": ""
}

dirty 表示构建包时 Git 工作区处于未提交状态。

若包位于版本控制仓库的子目录中，path_in_vcs 会被设置为相对于仓库根目录的路径。

该文件的兼容性维护策略与 cargo-metadata(1) 的 JSON 输出保持一致。

请注意，此文件仅提供版本控制信息的一个尽力而为的快照。包的真实来源并未经过验证，无法保证 tarball 中的源代码与版本控制信息完全匹配。

OPTIONS

Package Options

仅打印包中包含的文件列表，不实际创建包。

不通过构建来验证包内容。

忽略关于缺少人类可读元数据（如描述或许可证）的警告。

--allow-dirty

允许将包含未提交版本控制变更的工作目录打包。

--exclude-lockfile

打包时不包含锁文件。

此参数不用于常规用途。某些工具可能期望存在 lock file（例如 cargo install --locked）。使用此参数前，请先考虑其他选项。

--index index

要使用的 registry index 的 URL。

--registry registry

要为之打包的 registry 名称；有关 registry 名称配置的详细信息，请参阅 cargo publish --help。这些包不会被发布到该 registry，但如果正在打包多个相互依赖的 crate，lock file 将基于“依赖项将发布到该 registry”这一假设生成。

--message-format fmt

指定输出消息格式。目前仅与 --list 配合生效，影响文件列表的显示格式。此功能处于不稳定状态，需使用 -Zunstable-options。有效的输出格式：

human（默认）：以每行一个文件的格式显示。

json：为每个包输出机器可读的 JSON 信息。每个 JSON 对象占一行（换行分隔的 JSON）。

{
  /* The Package ID Spec of the package. */
  "id": "path+file:///home/foo#0.0.0",
  /* Files of this package */
  "files" {
    /* Relative path in the archive file. */
    "Cargo.toml.orig": {
      /* Where the file is from.
         - "generate" for file being generated during packaging
         - "copy" for file being copied from another location.
      */
      "kind": "copy",
      /* For the "copy" kind,
         it is an absolute path to the actual file content.
         For the "generate" kind,
         it is the original file the generated one is based on.
      */
      "path": "/home/foo/Cargo.toml"
    },
    "Cargo.toml": {
      "kind": "generate",
      "path": "/home/foo/Cargo.toml"
    },
    "src/main.rs": {
      "kind": "copy",
      "path": "/home/foo/src/main.rs"
    }
  }
}

包选择

默认情况下，如果没有给出包选择选项，选择哪些包取决于所选的 manifest 文件（如果未指定 --manifest-path，则基于当前工作目录）。如果 manifest 是 workspace 的根，则选择 workspace 的默认成员，否则只选择该 manifest 定义的包。

workspace 的默认成员可以在根 manifest 中通过 workspace.default-members 键显式设置。如果没有设置，虚拟 workspace 会包含所有成员（等同于传入 --workspace），而非虚拟 workspace 则只包含根 crate 本身。

-p spec…
--package spec…: 只打包指定的包。SPEC 格式参见 cargo-pkgid(1)。此标志可以指定多次，并支持 *、?、[] 等常见 Unix glob 模式。不过，为避免 shell 在 Cargo 处理之前误展开 glob 模式，每个模式都需要用单引号或双引号包裹。
--workspace: 打包 workspace 中的所有成员。
--exclude SPEC…: 排除指定的包，必须与 --workspace 标志一起使用。此标志可以指定多次，并支持 *、?、[] 等常见 Unix glob 模式。不过，为避免 shell 在 Cargo 处理之前误展开 glob 模式，每个模式都需要用单引号或双引号包裹。

编译选项

--target triple

为指定目标架构打包。该标志可多次指定。默认值为宿主架构。triple 的通用格式为 <arch><sub>-<vendor>-<sys>-<abi>。

可选值：

rustc --print target-list 中列出的任意受支持目标。
"host-tuple"，内部会替换为宿主目标。在交叉编译部分 crate 且不希望将宿主机器指定为目标时（例如共享项目中供多种宿主使用的 xtask）特别有用。
自定义 target specification 的路径。更多信息请参阅 Custom Target Lookup Path。

也可以通过 build.target 配置项指定。

注意，指定该标志会使 Cargo 以不同模式运行，目标构建产物将放置在独立目录中。详见构建缓存文档。

--target-dir directory

存放所有生成产物和中间文件的目录。也可通过环境变量 CARGO_TARGET_DIR 或 build.target-dir 配置项指定。默认为工作区根目录下的 target。

特性选择

特性标志可用于控制启用哪些特性。若未提供特性选项，则默认激活每个选定包的 default 特性。

更多细节请参阅特性文档。

-F features
--features features: 以空格或逗号分隔的特性列表，用于启用指定特性。工作区成员的特性可通过 包名/特性名 语法启用。该参数可多次指定，以启用所有列出的特性。
--all-features: 启用所有选定包的全部可用特性。
--no-default-features: 不启用选定包的 default 特性。

Manifest Options

--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。

其他选项

-j N

--jobs N

并行任务数。也可以通过 build.jobs 配置项指定，默认值为逻辑 CPU 数量。如果为负数，则最大并行任务数为逻辑 CPU 数加上该值。如果传入字符串 default，则恢复为默认值。不能设为 0。

--keep-going

尽可能多地构建依赖图中的 crate，而不是在第一个构建失败时就中止整个构建。

举例来说，假设当前包依赖于 fails 和 works 两个依赖项，其中有一个构建失败。在这种情况下，运行 cargo package -j1 时，那个成功的包可能构建也可能不构建（这取决于 Cargo 最初选择先运行哪一个），而 cargo package -j1 --keep-going 则一定会运行这两个构建任务，即使先执行的那个失败了。