把 Rust crate 发布到 crates.io

当你有一个想分享的库时，就可以将它发布到 crates.io。发布 crate，就是上传某个具体版本，由 crates.io 托管。

发布前应认真检查，因为发布通常是永久性的：同一个版本不能被覆盖，代码也不能通过常规版本操作删除。不过，可发布的版本数量没有上限。

首次发布前

首先需要 crates.io 账户及 API 令牌。按当前 Cargo Book 的说明，访问 crates.io 首页，通过 GitHub 账户登录，并在账户设置中填写及验证邮箱。随后创建 API 令牌并复制；离开该页面后将无法再次查看它。

运行 cargo login：

$ cargo login

然后在提示处粘贴令牌。下方是原文的占位示例，并非真实令牌：

please paste the API Token found on https://crates.io/me below
abcdefghijklmnopqrstuvwxyz012345

Cargo 会获知 API 令牌，并将其保存在本机 ~/.cargo/credentials.toml。令牌属于秘密，不应分享给其他人；如果泄露，应立即撤销。

不再需要在本机保存令牌时，可使用 cargo logout 从 credentials.toml 中移除它。

发布新 crate 前

crates.io 的 crate 名称按先到先得分配。名称一旦被占用，就不能再用于另一个 crate。

查看 Cargo.toml 支持的元数据，帮助其他人发现你的 crate。发布前填写以下字段：

• license 或 license-file
• description
• homepage
• repository
• readme

keywords 和 categories 虽非必需，也建议填写。发布库时，还可以参考 Rust API Guidelines。

打包 crate

使用 cargo publish 打包和上传。命令执行以下步骤：

1. 对包进行若干验证检查。
2. 将源代码压缩为 .crate 文件。
3. 将该文件解压到临时目录，检查它是否能编译。
4. 上传到 crates.io。
5. 注册中心再执行额外检查，检查通过后才添加该包。

建议先运行 cargo publish --dry-run，或者等效的 cargo package，检查是否有警告或错误。它们执行上面的前三步，不上传包。

$ cargo publish --dry-run

生成的 .crate 文件位于 target/package。原文给出的 crates.io 文件大小上限为 10 MB。检查大小，避免把构建时不需要的大型资产——例如测试数据、网站文档或代码生成材料——一起打包。下面的命令可以列出包内文件：

$ cargo package --list

打包时，Cargo 会自动忽略版本控制系统中忽略的文件。若要指定额外排除项，可在 manifest 中设置 exclude：

[package]
# ...
exclude = [
    "public/assets/*",
    "videos/*",
]

如果更希望显式列出需要包含的文件，可以使用 include；设置后，它会覆盖 exclude：

[package]
# ...
include = [
    "**/*.rs",
]

上传 crate

准备妥当后，运行 cargo publish，将包上传到 crates.io：

$ cargo publish

至此，你的第一个 crate 就发布了。

为已有 crate 发布新版本

修改 Cargo.toml 中的 version，并遵循 SemVer 兼容性规则。随后像前文一样运行 cargo publish。

可以把整个发布过程作为一个流程规划，并尽可能自动化。每个版本应包含更新日志条目和指向发布提交的 Git 标签。更新日志最好人工整理；自动生成的日志也好过没有。

代表不同发布流程的第三方工具包括 cargo-release、cargo-smart-release、release-plz；更多工具见 crates.io。

管理 crates.io 上的 crate

crate 的管理主要通过 Cargo 命令行完成，而不是 crates.io 网页。下面是几个常用子命令。

cargo yank

如果某个已发布版本有问题，例如语法错误或遗漏文件，可以撤回该版本，使新依赖解析不再选用它：

$ cargo yank --version 1.0.1
$ cargo yank --version 1.0.1 --undo

撤回不会删除代码。因此它不适合处理意外上传的秘密；秘密泄露后必须立即重置。

被撤回的版本不能用于建立新的依赖解析，而现有依赖仍可继续使用。crates.io 希望作为内容不随时间改变的永久档案。具体来说，已有 Cargo.lock 的包不会因撤回而损坏；新生成的 Cargo.lock 不会选取该被撤回版本。

cargo owner

crate 往往由多人开发，维护者也可能改变。只有 owner 才能发布新版本，现有 owner 可以添加其他 owner：

$ cargo owner --add github-handle
$ cargo owner --remove github-handle
$ cargo owner --add github:rust-lang:owners
$ cargo owner --remove github:rust-lang:owners

命令中的 owner ID 必须是 GitHub 用户名或 GitHub 团队。

向 --add 提供用户名时，邀请的是个人 owner，拥有完整权限：既能发布或撤回版本，也能添加及移除 owner，甚至移除邀请他的人。因此，只应邀请完全信任的人。该用户此前还必须登录过 crates.io。

向 --add 提供团队时，邀请的是团队 owner，权限更有限：可以发布及撤回版本，但不能添加或移除 owner。这种方式方便团队管理，也限制了恶意 owner 可能造成的影响。

团队名称语法为 github:org:team。邀请一个团队时，操作者必须属于该团队；移除团队没有此项要求。

GitHub 权限

GitHub 不提供无需授权的公开团队成员查询，因此处理团队时可能出现类似提示：

似乎没有权限从 GitHub 查询完成请求所需的属性。你可能需要在 crates.io 重新登录，授予读取 GitHub 组织成员信息的权限。

这类提示概括了团队查询被五个访问控制层级之一拒绝的情况；原文强调，GitHub 的团队访问控制具有企业级的复杂性。常见原因是首次登录发生在团队功能加入之前：早期 crates.io 使用 GitHub 令牌只为了登录；查询团队成员需要额外的 read:org 范围。

可以拒绝该权限，先前不涉及团队的功能仍可使用。不过，无法添加团队 owner 或以团队 owner 身份发布。尝试这些操作会出现上述错误；尝试向你并不拥有但由团队管理的 crate 发布，也可能出现此类问题。

如果需要调整授权，或者不确定 crates.io 是否有足够权限，可以在 crates.io 重新登录。权限不足时，登录流程会再次请求授权。

另一种原因是组织限制了第三方应用访问。可在相应组织的设置页面查看：

https://github.com/organizations/:org/settings/oauth_application_policy

其中 :org 是组织名称，例如 rust-lang。原文使用下面的测试组织截图说明相关位置：

原文介绍两种操作：把 crates.io 从被拒绝的应用列表中移除，或使用“Remove Restrictions”允许第三方应用访问。后者会扩大到所有第三方应用，应先按组织策略确认范围；针对 crates.io 的授权更容易保持明确的访问边界。

也可以在 crates.io 请求 read:org 时，点击组织旁的“Grant Access”，明确授予 crates.io 查询该组织的权限：

排查 GitHub 团队访问错误

添加团队 owner 时，可能出现如下错误：

error: failed to invite owners to crate <crate_name>: api errors (status 200 OK): could not find the github team org/repo

打开 GitHub 应用设置，检查 crates.io 是否位于“Authorized OAuth Apps”。若没有，回到 crates.io 完成授权。

随后在 GitHub 应用设置中点击 crates.io，检查你或你的组织是否列在“Organization access”中，并显示绿色勾号。若有“Grant”或“Request”按钮，可在有权限时授权，或者向组织 owner 请求相应访问权限。

来源：Cargo 团队及贡献者，The Cargo Book: Publishing on crates.io，文档源文件。本页为中文翻译；代码及占位输出逐字保留，补充了占位令牌、文件大小的来源限定及旧截图/组织授权范围的提示。采用项目提供的 MIT 许可分支，以下完整保留许可告知。未执行登录、打包、发布、撤回或账户授权操作。