导语
Rust 官方博客在 10/16 发布“docs.rs: changed default targets”，将文档构建的默认目标做出调整。虽然这看似是“文档层”的微调，但对依赖 docs.rs 文档与示例构建的企业内部平台、离线镜像与 CI 有实打实影响。本文解读该变更背后的工程动机与供应链启示，并给出一次“文档供应链”的体检清单。
变更动机与影响面
- 动机：
- 降低构建成本与排队时间；
- 把“非主流/高成本目标”的构建转为显式选择；
- 影响面：
- 文档示例在非默认目标下的构建行为变化；
- 企业内部“离线 docs”镜像的体积与同步策略；
- CI 上以 docs 构建作为“轻量验证”的工作流。
企业应该怎么做
- 盘点与对齐
- 盘点内部“文档消费”方式：在线阅读、离线镜像、在 IDE 中跳转、CI 里样例编译；
- 对齐默认目标变化：明确新增/减少了哪些目标的 doc 构建；
- 调整 CI/CD
- 把“示例构建”从默认目标解耦，按产品线选择目标列表；
- 对“跨平台 crates”构建 doc 的步骤进行矩阵化，避免隐藏失败；
- 离线镜像与缓存
- 调整离线镜像的抓取策略，减少存储与网络压力；
- 设定过期与刷新频率，保证工程师看到的是“可复现版本”的 doc；
- 开发者体验（DevEx）
- IDE 插件/Language Server 的跳转需适配 doc 目标变化；
- 文档中提供“目标选择指南”，减少初学者困惑。
供应链启示：文档也是“构建物”
- SBOM：将文档生成器与依赖计入 SBOM，确保来源与版本可追踪；
- 签名与镜像：对离线 doc 包进行签名与校验，避免篡改；
- 合规：面向客户交付的“开发包”中，明确 doc 的生成版本与目标列表。
度量与回归
- 文档构建时长、失败率、缓存命中率；
- 工程师搜索/跳转成功率与满意度；
- 离线镜像体积与同步时长；
- 兼容性问题单数量与关闭时长。
结语
“文档供应链”被忽视已久。借 10/16 docs.rs 变更之机，做一次从目标、构建、镜像到消费端的体检，会让团队在“效率—成本—可控性”之间找到更好平衡。
参考
- Rust Blog：docs.rs: changed default targets（2025-10-16）
