注册中心

Cargo 从“注册中心”安装板条箱并获取依赖项。默认注册中心是 crates.io。注册中心包含一个“索引”,其中包含可搜索的可用板条箱列表。注册中心还可以提供 Web API 来支持直接从 Cargo 发布新板条箱。

注意:如果您有兴趣镜像或供应商现有注册中心,请查看 源代码替换

如果您正在实现注册中心服务器,请查看 运行注册中心 以获取有关 Cargo 和注册中心之间协议的更多详细信息。

如果您使用的是需要身份验证的注册中心,请查看 注册中心身份验证。如果您正在实现凭据提供者,请查看 凭据提供者协议 以获取详细信息。

使用备用注册中心

要使用除 crates.io 之外的注册中心,必须将注册中心的名称和索引 URL 添加到 .cargo/config.toml 文件 中。registries 表为每个注册中心都有一个键,例如

[registries]
my-registry = { index = "https://my-intranet:8080/git/index" }

index 键应为指向包含注册中心索引的 Git 存储库的 URL 或带有 sparse+ 前缀的 Cargo 稀疏注册中心 URL。

然后,板条箱可以通过在 Cargo.toml 中的依赖项条目中指定 registry 键和注册中心名称的值来依赖于来自另一个注册中心的板条箱

# Sample Cargo.toml
[package]
name = "my-project"
version = "0.1.0"
edition = "2021"

[dependencies]
other-crate = { version = "1.0", registry = "my-registry" }

与大多数配置值一样,索引可以使用环境变量而不是配置文件来指定。例如,设置以下环境变量将与定义配置文件的效果相同

CARGO_REGISTRIES_MY_REGISTRY_INDEX=https://my-intranet:8080/git/index

注意:crates.io 不接受依赖于来自其他注册中心的板条箱的包。

发布到备用注册中心

如果注册中心支持 Web API 访问,则可以直接从 Cargo 将包发布到注册中心。Cargo 的几个命令(例如 cargo publish)接受 --registry 命令行标志来指示要使用的注册中心。例如,要发布当前目录中的包

  1. cargo login --registry=my-registry

    这只需要执行一次。您必须输入从注册中心网站检索的秘密 API 令牌。或者,可以将令牌直接传递到 publish 命令,使用 --token 命令行标志或使用注册中心名称的环境变量(例如 CARGO_REGISTRIES_MY_REGISTRY_TOKEN)。

  2. cargo publish --registry=my-registry

而不是始终传递 --registry 命令行选项,可以在 .cargo/config.toml 中使用 registry.default 键设置默认注册中心。例如

[registry]
default = "my-registry"

Cargo.toml 清单中设置 package.publish 键会限制允许将包发布到的注册中心。这对于防止意外将闭源包发布到 crates.io 很有用。该值可以是注册中心名称列表,例如

[package]
# ...
publish = ["my-registry"]

publish 值也可以是 false,以限制所有发布,这与空列表相同。

cargo login 保存的身份验证信息存储在 Cargo 主目录(默认情况下为 $HOME/.cargo)中的 credentials.toml 文件中。它为每个注册中心都有一个单独的表,例如

[registries.my-registry]
token = "854DvwSlUwEHtIo3kWy6x7UCPKHfzCmy"

注册中心协议

Cargo 支持两种远程注册中心协议:gitsparse。如果注册中心索引 URL 以 sparse+ 开头,Cargo 将使用稀疏协议。否则,Cargo 将使用 git 协议。

git 协议将索引元数据存储在 Git 存储库中,并要求 Cargo 克隆整个存储库。

sparse 协议使用普通 HTTP 请求获取单个元数据文件。由于 Cargo 只下载相关板条箱的元数据,因此 sparse 协议可以节省大量时间和带宽。

crates.io 注册中心支持这两种协议。crates.io 的协议通过 registries.crates-io.protocol 配置键控制。