第60章 Cargo 教程：使用 cargo new 创建新包

名称

cargo-new — 创建一个新的 Cargo 包

概要

cargo new [选项] 路径

描述

该命令会在指定目录下创建一个新的 Cargo 包，包括一个简单的模板：Cargo.toml 清单文件、示例源码文件以及 VCS 忽略文件。如果该目录不在任何 VCS 仓库中，还会创建一个新的仓库（参见下文的 --vcs）。

类似命令可参阅 cargo-init(1)，它可以在已有目录中创建新的清单文件。

选项

New 选项

--bin

创建一个包含二进制目标（src/main.rs）的包。这是默认行为。

--lib

创建一个包含库目标（src/lib.rs）的包。

--edition edition

指定使用的 Rust 版本（edition），默认为 2024。 可选值：2015、2018、2021、2024。

--name name

设置包名，默认使用目录名。

--vcs vcs

为指定的版本控制系统（git、hg、pijul 或 fossil）初始化新仓库，或使用 none 完全不初始化版本控制。未指定时，默认为 git 或配置项 cargo-new.vcs 的值；如果已处于某个 VCS 仓库内，则为 none。

--registry registry

将 Cargo.toml 中的 publish 字段设置为指定的 registry 名称，以此将发布限制在仅该 registry 上。

Registry 名称在 Cargo 配置文件中定义。如果未指定，则使用 registry.default 配置项定义的默认 registry。如果未设置默认 registry 且未使用 --registry，则 publish 字段将保持未设置状态，这意味着发布不会受到限制。

显示选项

-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 或 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 包：

   cargo new foo
   

另请参阅

cargo(1)、cargo-init(1)