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

第67章 Cargo publish：将包发布至注册表

名称

cargo-publish — 将包上传到注册表

用法

cargo publish [选项]

描述

该命令会将当前目录下的包源代码打包为可分发的压缩 .crate 文件，并上传至注册表。默认注册表为 https://crates.io。其执行流程如下：

执行若干检查，包括：
- 检查 manifest 中的 package.publish 键，确认允许发布到哪些注册表。
按照 cargo-package(1) 中的步骤创建 .crate 文件。
将 crate 上传至注册表，服务器会对其执行额外的校验。
客户端会轮询等待包出现在索引中，此过程可能会超时。若超时，需手动检查是否完成，但这不影响上传操作本身。

执行该命令前，需通过 cargo-login(1) 进行身份认证，或设置 registry.token 及 registries.<name>.token 等环境变量。

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

选项

发布选项

--dry-run: 执行所有检查但不上传。
--no-verify: 不通过构建来验证内容。
--allow-dirty: 允许将包含未提交 VCS 变更的工作目录进行打包。
--index index: 要使用的 registry index 的 URL。
--registry registry: 要发布到的 registry 名称。Registry 名称定义在 Cargo 配置文件中。如果未指定该选项，且 Cargo.toml 中的 package.publish 字段只包含一个 registry，则发布到该 registry。否则使用默认 registry，即由 registry.default 配置项定义的 registry，默认值为 crates-io。

包选择

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

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

-p spec…
--package spec…: 只发布指定的包。SPEC 格式参见 cargo-pkgid(1)。该参数可以多次指定，并支持 *、? 和 [] 等常见的 Unix glob 模式。不过，为避免 shell 在 Cargo 处理之前意外展开 glob 模式，每个模式都必须用单引号或双引号包裹。
--workspace: 发布工作区中的所有成员。
--all: 已弃用，作为 --workspace 的别名。
--exclude SPEC…: 排除指定的包。必须与 --workspace 标志配合使用。该标志可以多次指定，并支持常见的 Unix 通配符模式，如 *、? 和 []。但为了防止 Shell 在 Cargo 处理之前意外展开这些通配符模式，你必须为每个模式添加单引号或双引号。

编译选项

--target triple

为指定的目标架构发布。该标志可以多次指定。默认为主机架构。三元组的一般格式为 <arch><sub>-<vendor>-<sys>-<abi>。

可能的值：

rustc --print target-list 中列出的任何受支持的目标。
"host-tuple"，内部会替换为主机的目标。这在跨编译某些 crates 时特别有用，如果你不想将主机机器指定为目标（例如，在一个多人协作的共享项目中，不同主机运行的 xtask）。
自定义目标规格的路径。更多信息请参阅自定义目标查找路径。

也可以通过配置值中的 build.target 来指定。

注意：指定此标志会让 Cargo 运行在另一种模式，目标产物会生成到独立目录。详见构建缓存文档。

--target-dir directory

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

特性选择

特性标志用于控制启用哪些特性。若未提供特性选项，会为每个选中的包激活 default 特性。

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

-F features
--features features: 用空格或逗号分隔的特性列表，用于激活这些特性。工作区成员的特性可使用 package-name/feature-name 语法启用。可多次指定该标志以激活所有列出的特性。
--all-features: 激活所有选中包的全部可用特性。
--no-default-features: 不激活所选包的 default 特性。

清单选项

--manifest-path path

指定 Cargo.toml 文件的路径。默认情况下，Cargo 会在当前目录及其所有上级目录中查找 Cargo.toml 文件。

--locked

断言依赖及其版本与已有 Cargo.lock 文件最初生成时完全一致。出现以下任一情况时，Cargo 会报错退出：

lock 文件不存在。
由于依赖解析结果不同，Cargo 试图修改 lock 文件。

该选项适用于需要确定性构建的场景，比如 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，而不是在第一个构建失败的 crate 处终止构建。

例如，如果当前包依赖于 fails 和 works，且其中一个构建失败，cargo publish -j1 可能构建也可能不构建那个成功的（取决于 Cargo 选择先运行哪一个），而 cargo publish -j1 --keep-going 则肯定会运行这两个构建，即使先运行的那个失败了。