05-cargo publish

译文 · 基于 The Cargo Book

cargo-publish(1)

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

名称

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

大纲

cargo publish [options]

描述

此命令会为当前目录中的包创建可分发、压缩的 .crate 文件（含源代码），并将其上传到注册表。默认注册表为 https://crates.io。执行步骤如下：

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

此命令要求你通过 cargo-login(1) 或 registry.token 与 registries.<name>.token 配置字段对应的环境变量完成身份验证。

关于打包与发布的更多细节，见参考文档。

选项

发布选项

--dry-run

执行所有检查但不实际上传。

--no-verify

不通过构建来验证内容。

--allow-dirty

允许打包含有未提交 VCS 变更的工作目录。

--index index

要使用的注册表索引 URL。

--registry registry

要发布到的注册表名称。注册表名称在 Cargo 配置文件中定义。若未指定，且 Cargo.toml 中的 package.publish 字段仅包含单个注册表，则发布到该注册表。否则使用默认注册表，由 registry.default 配置键定义，默认为 crates-io。

包选择

默认情况下，若未指定包选择选项，所选包取决于所选清单文件（若未指定 --manifest-path，则基于当前工作目录）。若清单是工作空间的根，则选择工作空间的默认成员；否则仅选择清单定义的包。

工作空间的默认成员可在根清单中通过 workspace.default-members 键显式设置。若未设置，虚拟工作空间将包含所有工作空间成员（等价于传入 --workspace），非虚拟工作空间则仅包含根 crate 本身。

-p spec…

--package spec…

仅发布指定的包。SPEC 格式见 cargo-pkgid(1)。此标志可指定多次，并支持常见的 Unix glob 模式，如 *、? 和 []。不过，为避免 shell 在 Cargo 处理之前意外展开 glob 模式，必须用单引号或双引号括住每个模式。

--workspace

发布工作空间中的所有成员。

--all

已弃用，为 --workspace 的别名。

--exclude SPEC…

排除指定的包。必须与 --workspace 标志一起使用。此标志可指定多次，并支持常见的 Unix glob 模式，如 *、? 和 []。不过，为避免 shell 在 Cargo 处理之前意外展开 glob 模式，必须用单引号或双引号括住每个模式。

编译选项

--target triple

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

可能的值：

• rustc --print target-list 中支持的任意目标。
• "host-tuple"，内部将替换为宿主目标。若你在交叉编译某些 crate，且不想将宿主机器指定为目标（例如多人协作的共享项目中的 xtask），这会特别有用。
• 自定义目标规范的路径。更多信息见 Custom Target Lookup Path。

也可通过 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 将以错误退出：

• 锁文件缺失。
• 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，而不是在第一个构建失败的 crate 处中止。

例如，若当前包依赖 fails 与 works，其中一个构建失败，cargo publish -j1 可能会也可能不会构建成功的那一个（取决于 Cargo 先运行哪一个），而 cargo publish -j1 --keep-going 则一定会运行两次构建，即便先运行的那个失败。

显示选项

-v

--verbose

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

-q

--quiet

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

--color when

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

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

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

通用选项

+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. 发布当前包：

   cargo publish
   

参见

cargo(1), cargo-package(1), cargo-login(1)