很多Rust开发者都希望把自己写的小工具或者共享库放到crates.io上，让其他开发者能用，但很多人第一次发布的时候踩了坑，比如Cargo.toml缺字段、没测试就发布、安全漏洞没发现，最后包要么发布失败，要么被标记为不安全，影响自己的信誉。接下来就详细说说Cargo包发布到crates.io的完整规范，从准备到发布再到后期维护，确保流程合规又安全。
一、提前准备：把好发布前的核心关卡
1.1 检查Cargo.toml的必填配置
这是发布成功的基础，crates.io后台会自动校验这些内容，缺任何一项都发布不了。你可以打开项目根目录的Cargo.toml文件，对照下面的正确配置检查：
[package]
name = "simple_add" # 包名，必须是crates.io上唯一的，发布前最好先搜一下有没有重名的
version = "0.1.0" # 版本号，按SemVer规则写，比如主版本.次版本.修订版，比如1.2.3
description = "一个简单的Rust库，用于计算两个整数的和" # 必填，简洁说明包的用途，用户搜的时候会显示
license = "MIT" # 必填，明确开源协议，比如MIT、Apache-2.0、GPL-3.0，不能空着或写模糊的描述
edition = "2021" # 用的Rust版本，必填，确保代码的兼容性
authors = ["李小明 <liming@example.com>"] # 可选但建议填，说明作者信息，增加可信度
[dependencies]
# 这里是第三方依赖，尽量选维护活跃、没有安全漏洞的版本，比如如果用到rand库，要写"rand = 0.8"这样的固定版本
很多新手容易忽略description和license这两个必填字段，结果执行发布命令的时候直接报错，白忙活半天。还有包名如果重复了，crates.io会提示你换个名字，所以发布前一定要先去官网搜一下确认。
1.2 本地测试与安全扫描
写完代码后，别急着发布，先在本地把所有问题解决，这是保证包质量和安全的关键。 首先是测试代码，Rust自带的cargo test命令会跑你写的所有测试用例，包括文档里的示例，比如我们写的加法库，文档里的示例会被自动执行，确保能正常运行：
# 进入项目根目录，执行测试命令
cargo test
# 正常的话会显示"test result: ok"，如果有报错，先把bug修复再继续
然后是安全扫描，用cargo audit工具检查所有依赖包有没有已知的安全漏洞，比如某个旧版本的依赖有远程代码执行的问题，要是没检查就发布，别人用了你的包可能会出问题，这个步骤是合规性的重要一环：
# 如果没装cargo audit，先执行安装命令（只需要装一次）
cargo install cargo-audit
# 然后执行安全扫描，会输出所有有漏洞的依赖，建议修复到安全版本再发布
cargo audit
我们再补充一个简单的库代码示例，带文档注释，crates.io上会显示这个示例，用户可以直接用：
// src/lib.rs
/// 计算两个整数的和
/// # Example
/// ```
/// assert_eq!(add(2, 3), 5);
/// assert_eq!(add(-1, 1), 0);
/// ```
pub fn add(a: i32, b: i32) -> i32 {
a + b
}
二、正式发布步骤：按步操作避免踩坑
2.1 登录crates.io账号
要发布包，必须有crates.io的账号，先去官网注册，然后拿到账号的API Token，用来在本地终端登录，Token要妥善保存，不能泄露，不然别人可以用你的账号发布恶意包：
# 把下面的YourToken换成你在crates.io账号设置里拿到的实际Token
cargo login YourToken
# 执行成功会显示"Logged in as 你的用户名"，Token会存在本地的配置文件里，下次不用再输
2.2 执行干跑发布
正式发布前一定要执行干跑，模拟发布流程，不会真的把包上传到crates.io，用来提前发现问题，比如配置错误、代码语法问题等：
# 进入项目根目录，执行干跑命令
cargo publish --dry-run
# 如果没报错，会显示"Package (simple_add v0.1.0) would be published"，说明没问题；如果有报错，比如license填错，改了再试
2.3 执行正式发布
干跑没问题后，再执行正式发布命令，把包上传到crates.io：
cargo publish
# 执行成功会显示"Published simple_add v0.1.0 to registry `https://crates.io/`"，这样你的包就上线了，所有人都能搜到和用了
三、发布后不能大意：合规性的长期保障
3.1 发布后的包自查
发布成功后，第一时间去crates.io搜索你的包，确认所有信息都正确：比如包名、版本、介绍、文档示例，还有有没有安全标记。如果发现哪里错了，比如description写错了，需要更新版本来修改，不能直接改已发布的包，因为crates.io不允许修改已发布的包内容，只能发新版本。
3.2 版本更新的正确姿势
如果要更新包，版本号一定要按SemVer规则来，这个规则其实就是三位数字：主版本.次版本.修订版，简单来说：主版本变了意味着有不兼容的大改动，次版本变了是加了新功能但兼容旧版本，修订版变了是小bug修复。比如你要修刚才加法库的一个小bug，就把版本改成0.1.1，发布的时候直接用cargo publish就可以，不用重新注册账号。
应用场景
这套规范适用于所有Rust开发者的包发布场景：个人开发者分享自用的工具库、团队内部共享的内部库、开源项目对外发布的公开包，不管包大小，都需要遵循这个流程，确保包能顺利上线，被他人安全使用，也能提升自己的开源信誉，避免因为发布不规范导致的包下架、被标记不安全等问题。
技术优缺点
这套发布规范的优点很明显：一是流程标准化，减少新手踩坑的概率，比如必填字段的检查、安全扫描等步骤，能提前解决大部分问题；二是安全性有保障，通过安全扫描和合规配置，能避免包被恶意利用；三是文档规范，文档注释的要求能让用户快速上手，提升包的使用率。缺点主要是刚学习的时候需要记的步骤稍多，对完全没接触过包管理的新手来说，可能需要花点时间熟悉每个命令的作用，但熟练后就会发现这套流程能节省很多时间。
注意事项
- 包名要唯一，发布前一定要去crates.io搜一下，避免和已有的包重名，不然会发布失败；2. API Token绝对不能泄露，泄露后别人可以用你的账号发布恶意包，甚至删除已发布的包；3. 不要在包里放敏感信息，比如API密钥、密码等，crates.io是公开平台，所有内容都能被任何人看到；4. 文档注释要写清楚，示例代码要正确，这样用户才能看懂怎么用你的包；5. 发布前一定要做本地测试和干跑，不要图省事直接正式发布，避免发布错误的包影响信誉。
总结
Cargo包发布的规范核心就是“合规、安全、稳定”，从准备阶段的配置检查、测试扫描，到正式发布的登录、干跑，再到发布后的自查和版本更新，每一步都有实际的意义，不是多余的流程。遵循这套规范，不仅能让你的包顺利上线crates.io，还能保证包的质量和安全，让其他开发者放心使用，也能帮你建立良好的开源口碑，不管是个人还是团队，都能从中受益。
评论
围绕“Cargo包发布流程规范：确保crates.io发布合规性与安全性的操作要点”参与讨论