发布 crate 到 crates.io
本教程共 78 篇 · 第 56 篇 · 更新于 2026-08-08 · 约 9 分钟阅读
本节目标：掌握把 Rust 库发布到 crates.io 的完整流程——注册登录、补全元信息、预检、上传，以及后续发布新版本、撤回版本和管理协作者。
写好一个好用的库，最自然的心愿是分享给别人。GitHub 当然能放源码，但 Rust 生态有一座专门的”应用商店”叫 crates.io。别人只要写一行依赖就能用上你的库，这才是 Rust 社区的打开方式。
1-1 一个必须知道的前提
发布到 crates.io 后，某个具体版本不可被覆盖、代码也不可被删除。一旦 1.0.0 传上去了，它就永远在那。要改只能发新版本号。
Warning这条铁律意味着：发布前务必确认代码没问题、没有把密钥或隐私内容打包进去。crates.io 的设计目标是”永久存档”，它不提供删除按钮。传错了只能靠
cargo yank阻止别人继续依赖，但已存在的内容仍留在存档里。
1-2 首次发布：注册并登录
首先需要一个 crates.io 账号。打开 crates.io 主页，用右上角的 GitHub 账号登录。然后进入你的账户设置页（Settings → API Tokens），生成一个 Token。
拿到 Token 后在终端登录：
cargo login 你的Token字符串这条命令把 Token 存到本地的 ~/.cargo/credentials.toml 文件里，以后 cargo publish 会自动用它，不用每次输入。
NoteToken 等同于你账号的钥匙，千万别贴到代码、截图或聊天里。一旦怀疑泄漏，立刻去设置页 Revoke（撤销）并重新生成。
包名是”先到先得”。你想要的英文名如果被别人占了，就只能换一个。所以动手前最好先在 crates.io 搜一下心仪的名字还在不在。
1-3 发布前必须填的元信息
cargo publish 对 Cargo.toml 的完整性有硬性要求。发布前务必填好这些字段：
[package]
name = "my_cool_lib"
version = "0.1.0"
edition = "2024"
license = "MIT"
description = "一句话说清这个库是干嘛的"
homepage = "https://example.com"
documentation = "https://docs.rs/my_cool_lib"
repository = "https://github.com/yourname/my_cool_lib"
readme = "README.md"其中 license 和 description 是发布的最低门槛——不填 cargo publish 会直接拒绝。可选的 keywords（关键词）和 categories（分类）能让你的包更容易被搜到，强烈建议填上。
Tip
license用 SPDX 标识符，比如MIT、Apache-2.0、MIT OR Apache-2.0。不知道填啥，开源库常用MIT。edition我们全册以 2024 Edition 为准，这里填2024。
1-4 预检：先 dry-run
正式上传前，强烈建议跑一次预检，确保编译无警告无错误：
cargo publish --dry-run它做和真正发布几乎一样的步骤：验证、打包、解压、编译，但不上传。你能在 target/package 目录里看到生成的 .crate 文件。
crates.io 要求 .crate 文件不能超过 10MB。用下面的命令检查包里会包含哪些文件，避免把测试数据、视频、生成的代码等大块头打包进去：
cargo package --list想排除某些文件，在 Cargo.toml 里用 exclude：
[package]
exclude = [
"public/assets/*",
"videos/*",
]想显式只打包某些文件，用 include（注意：一旦设了 include，exclude 就失效）：
[package]
include = [
"**/*.rs",
"Cargo.toml",
]打包时 Cargo 还会自动尊重 .gitignore，被忽略的文件不会进去。
1-5 正式上传
预检通过，就可以真正发布了：
cargo publish这条命令会依次：验证项目、把源码压成 .crate、解压到临时目录确认能编译、上传到 crates.io、由注册服务做额外校验后加入列表。看到成功提示，你的库就上线了，全世界都能 cargo add my_cool_lib 引入它。
1-6 发布新版本
绝大多数时候你不是发新包，而是发已存在包的新版本。做法很简单：改 Cargo.toml 里的 version，且必须遵循语义化版本（SemVer）规则。例如从 0.1.0 升到 0.1.1（修 bug）或 0.2.0（加功能）。然后再次 cargo publish。
NoteSemVer 简记：
MAJOR.MINOR.PATCH。不兼容的改动升 MAJOR，新增向后兼容功能升 MINOR，向后兼容的 bug 修复升 PATCH。0.x 阶段 API 还不稳定，MINOR 变动就可能包含破坏性修改，这是社区惯例。
1-7 管理已发布的包
包的管理主要靠命令，而不是网页后台。
cargo yank 撤回某个版本——注意它不删除任何代码，只是阻止别人再把它加为新依赖，已依赖它的项目照常工作：
cargo yank --vers 1.0.1
cargo yank --vers 1.0.1 --undo # 撤销撤回如果传了隐私内容，yank 救不了你，得立刻去重置/作废那些凭据。
cargo owner 管理协作者。只有 owner 能发新版本：
cargo owner --add github用户名
cargo owner --remove github用户名还能加整个 GitHub Team：cargo owner --add github:组织名:team名。Team 类型的 owner 权限受限——能发版、能 yank，但不能增删 owner，比直接加个人安全。
Warning不要把不信任的人加为 owner。因为 owner 有权把你也移除掉，自己反被踢出项目。加 Team 能避免这种风险。
1-8 发布前的自检清单
每次 cargo publish 前，过一遍这份清单能少踩很多坑：
Cargo.toml里license和description都填了吗？缺了会被拒绝。readme指向的文件存在吗？很多用户先在 crates.io 上看 README 决定是否用你的库。- 跑过
cargo publish --dry-run，确认没有编译警告、文档测试也通过了吗？ - 用
cargo package --list检查过打包内容，没有把.env、密钥、大资源误塞进去吗？ - 版本号按 SemVer 递增了吗？发错版本号只能发新的，旧的撤不回。
- 在本地
cargo doc --open审过文档了吗？示例、链接、标题都正常吗？
Tip把这份清单做成发版前的固定动作，能避免”发上去才发现 README 链接 404”这种尴尬。小团队尤其值得写进 CONTRIBUTING 文档。
还有一个心态问题：别等到”完美”才发。Rust 社区对 0.x 版本包容度很高，API 还在演进是常态。先发 0.1.0 收集真实反馈，比闭门造车主更好。等 API 稳定了再上 1.0.0，那时破坏性的改动就要慎之又慎了。
1-9 版本撤销与预发布
再说清楚 yank 和删除的区别，很多人会混。yank 不是删除：已依赖该版本的项目照样能拉到、照常编译；它只是阻止”新”的项目把它加进依赖。所以 yank 适合”这个版本有 bug、别再用了”，而不是”我要抹掉它”。真要彻底消失，crates.io 不提供——这是它作为永久存档的刻意设计。
Note发布前如果想先小范围内测、又不想让别人在生产里依赖，可以用预发布版本号，比如
0.1.0-alpha.1。按 SemVer，带预发布标签的版本不会被当作稳定依赖自动选中，等成熟了再发正式的0.1.0。
发布这件事实则不复杂，难的是”发得负责任”：文档、许可证、版本号、清理敏感文件，每一样都关系到用你库的人。把这些习惯养成了，开源对你就是水到渠成的事。
走到这一步，你已经具备把成果分享给整个 Rust 社区的能力。下一章我们看如何在本地同时管理多个包——工作空间。