14.4 发布 crate Pt.2

14.4.1 创建并设置 crates.io 账号

在发布任何 crate 之前，你需要拥有一个 crates.io 账号并获取 API 令牌。为此，请访问 crates.io 主页并使用 GitHub 帐户登录。目前只支持 GitHub 登录。如果已登录，打开帐户设置：https://crates.io/me/，并找到 API 密钥。然后在本地使用 cargo login 命令，并在出现提示时粘贴你的 API 密钥：

$ cargo login
just1a1nexample

此命令会告诉 Cargo 你的 API 令牌，并将其本地存储在 ~/.cargo/credentials.toml。要注意的是，此令牌不能与其他任何人共享。如果你泄露了，应该撤销它并在 crates.io 上生成一个新令牌。

14.4.2 将元数据添加到 crate

在发布 crate 之前，还需要在 Cargo.toml 文件里的 [package] 区域添加一些元数据：

• 首先你要确保项目名称在网站上是独一无二的。
• 其次还需要写 description，也就是简短介绍，不需要太长，一两句话就可以。description 的内容会出现在 crate 搜索结果里。
• 你需要提供这个 crate 使用的许可证标识值（可以到 spdx.org/licenses/ 中查找）；可以指定多个许可证，用 OR 隔开，写在 license。
• 语义版本 信息写在 version。

当然可以写的信息不止这些，具体可以参阅 Cargo 手册。

整个 [package] 区域的写法应该如下：

[package]
name = "guessing_game"
version = "0.1.0"
edition = "2021"
description = "A fun game where you guess what number the computer has chosen."
license = "MIT OR Apache-2.0"

14.4.3 使用命令发布 crate

使用命令 cargo publish 即可发布 crate，但前提是元数据完整且项目名唯一。此外，你的 crates.io 账号还必须先完成邮箱验证，才允许发布。

如果出现问题，cargo publish 会报错：

$ cargo publish
    Updating crates.io index
warning: manifest has no description, license, license-file, documentation, homepage or repository.
See https://doc.rust-lang.org/cargo/reference/manifest.html#package-metadata for more info.
......
error: failed to publish to registry at https://crates.io

Caused by:
  the remote server responded with an error: missing or empty metadata fields: description, license. Please see https://doc.rust-lang.org/cargo/reference/manifest.html for how to upload metadata

中间我省略了一部分。看 Caused by 这部分说是缺少元数据导致的错误。

crate 一旦发布就是永久性的：该版本无法覆盖，代码除了某些有限情形外无法删除。 这样做是为了让依赖于该版本的项目可以继续正常工作。

14.4.4 发布新版本的 crate

如果你需要为已经存在的 crate 发布更新版本，可以在修改 crate 源代码后，把 Cargo.toml 中的 version 值按照语义化版本规范修改，再重新发布。

14.4.5 撤回版本

撤回版本会使新项目不能依赖于这个版本，但是已经基于这个版本构建的项目仍然可以使用并可下载。

其指令是 cargo yank --vers 指定的版本。例如要撤回 1.0.1 版本，就写：

cargo yank --vers 1.0.1

如果你撤回之后又改了主意，想要取消撤回，写：

cargo yank --vers 1.0.1 --undo

yank 意味着：

• 所有已经生成 Cargo.lock 的项目都不会因版本被撤回而中断。
• 所有将来生成的 Cargo.lock 文件都不会使用被撤回的版本。