夜雨聆风2026 年 5 月 1 日，docs.rs 实施了一项影响所有 Rust crate 的变更：从这一天起，新发布的 crate 如果不在 Cargo.toml 中显式声明 targets，docs.rs 将只构建默认平台（x86_64-unknown-linux-gnu）的文档，而不是此前的五个平台。
这条变更并非突然决定。早在 2020 年，docs.rs 团队就在博客中预告过这一方向，并在过去几年允许用户通过 metadata 自行选择构建哪些目标。现在，默认值终于改了。
原来构建五个目标，现在只打一个
docs.rs 此前的默认行为是构建五个目标的文档：
x86_64-unknown-linux-gnu x86_64-apple-darwin x86_64-pc-windows-msvc i686-unknown-linux-gnu i686-pc-windows-msvc
对大多数 crate 来说，其中的平台差异代码极少，甚至根本没有。这意味着大量构建资源被浪费在重复产出几乎相同的内容上。而 docs.rs 作为免费公共服务，每一分 CPU 时间都来自捐赠。
从 5 月 1 日起，默认降为只构建 x86_64-unknown-linux-gnu。如果你的 crate 有通过 cfg(target_os) 或 cfg(windows) 等条件编译暴露的平台特定 API，这些 API 的文档将不再自动出现在 docs.rs 上。
这一变更影响的是新发布和旧版本的重新构建。已有文档不受影响。
对谁有影响
如果你的 crate 有以下特征，需要主动配置：
跨平台库，且有平台条件编译的公开 API 暴露了 Windows 特定 API（ #[cfg(windows)]）公开了 macOS/iOS 特有的功能 需要为 32 位平台提供不同的接口 crate 文档中包含平台相关的示例代码
如果你的 crate 是纯逻辑库（像 serde 的 derive 部分、纯算法实现），不依赖任何平台条件编译，那什么都不用做，默认单平台文档完全够用。
在 Cargo.toml 中显式配置 targets
修正方式很简单，在 Cargo.toml 的 [package.metadata.docs.rs] 段中列出你需要的目标：
[package.metadata.docs.rs] targets = [ "x86_64-unknown-linux-gnu", "x86_64-apple-darwin", "x86_64-pc-windows-msvc", ] 这样 docs.rs 会为这三个目标构建文档，而不会再构建 i686 的版本。你也可以继续使用五个目标的列表，按需选择即可。
如果只是想覆盖默认目标（比如你的 crate 主要面向 macOS 用户）：
[package.metadata.docs.rs] default-target = "x86_64-apple-darwin" 另外，如果你启用了 docs.rs 的 features：
[package.metadata.docs.rs] features = ["serde", "tokio"] targets = ["x86_64-unknown-linux-gnu"] 值得注意的一点：default-target 会用作 Rustdoc 的 --default-theme 等设置的上下文，但它只影响"默认渲染的目标"，真正控制构建哪些目标的是 targets 字段。
为什么这和 AI 密切相关
这个话题还有一个当前版本中容易被忽视的维度：AI 编程助手对文档的依赖方式。
像 Claude Code、GitHub Copilot、Cursor 这些工具，大量使用 docs.rs 的文档作为 RAG（检索增强生成）上下文。当开发者让 AI 助手写一步跨平台代码时——比如检测当前操作系统并调用对应的 API——AI 模型需要知道每个平台的 API 签名、参数类型和约束条件。
如果 docs.rs 只构建了 Linux 的文档，AI 能获取的上下文就只包含 cfg(unix) 或 cfg(not(windows)) 路径下的公开 API。Windows 或 macOS 独有的 API 不可见，模型生成的跨平台代码可能会出现：
调用了 Linux 上不存在但文档中没有标注的 Windows API 生成的 cfg 门控判断错误 遗漏了平台相关的安全约束或 panic 条件
这实际上是 AI 辅助编程中的一个"上下文盲区"问题：开发者以为 AI 能看到完整的 crate API 表面，但因为文档平台缺失，AI 看到的只是冰山一角。
那些在 Rust 生态中已经做了多平台配置的 crate——比如 tokio、serde、regex——它们的 docs.rs 页面本来就支持目标切换。但大量中小型跨平台 crate 过去依赖 docs.rs 的默认五目标构建来获得多平台覆盖。现在默认变为单平台后，这些 crate 的 AI 上下文将显著缩水。
该怎么做
如果你维护的 crate 有平台相关代码，现在就应该检查两步：
第一，确认你的 Cargo.toml 中是否已有 [package.metadata.docs.rs] 配置。如果没有，访问你的 crate 在 docs.rs 上的页面，看有没有目标选择下拉框——如果只有 Linux 一个，说明你的文档已经降级了。
第二，梳理你的公开 API 中有多少是条件编译的。如果你的公开类型、方法或常量带有 #[cfg(target_os = "windows")] 或 #[cfg(target_family = "unix")] 属性，那就一定要显式配置 targets。
建议的最小配置：
[package.metadata.docs.rs] targets = ["x86_64-unknown-linux-gnu", "x86_64-apple-darwin", "x86_64-pc-windows-msvc"] 这三个目标覆盖了 Rust 开发者的主流工作平台。如果你的 crate 支持更小众的平台（如 Android、FreeBSD），可根据实际需要追加。
如果你的 crate 用到了 docs.rs 的 all-features 或 features，记得和 targets 配置放在一起：
[package.metadata.docs.rs] all-features = true targets = ["x86_64-unknown-linux-gnu", "x86_64-apple-darwin", "x86_64-pc-windows-msvc"] 几点观察
这次变更本身是合理的资源优化。docs.rs 是 Rust 生态最重要的基础设施之一，依托捐赠运行，减少不必要的构建是负责任的做法。默认从五目标降为一目标也不会给绝大多数 crate 带来问题——因为绝大多数 crate 根本没有平台相关代码。
真正需要关注的是那些"有平台差异但不自知"的 crate。一些库可能只在特定平台上暴露了少量辅助函数，维护者自己主要在一个平台上开发，没有意识到这些函数在 doc 构建时被静默跳过了。加上现在 AI 编程助手越来越成为开发者接触 crate API 的第一入口，文档平台覆盖的完整性实际上比过去更重要了。
过去几年，Rust 生态中工具链层面的"默认值"发生了不少变化：Cargo 的 edition = "2024" 成为新项目默认值、rustfmt 的默认样式调整、现在 docs.rs 的构建目标默认值也变了。每一条单独的变更看起来都不大，但累积起来，它们重新定义了一个 crate 在生态中的"默认可见性"。作为 crate 维护者，主动检查这些默认值是否还适合自己的项目，正在变成一项定期维护工作。
#Rust #docs.rs #AI
