Cargo Knowledge Patch 是一个用于 Rust 生态的 Cargo 知识型技能,适用于改动 Cargo 清单、配置、依赖工作流、构建、工作区、打包、发布、Cargo 脚本或不稳定 Cargo 特性的场景。其核心工作方式是先检查仓库和已安装工具链,再应用指导:运行 cargo --version 并确认仓库是否固定工具链;查看 Cargo.toml、Cargo.lock、.cargo/config.toml、工作区清单和相关 CI 命令;区分稳定行为与仍需 nightly Cargo 及 -Z 标志的特性;在复制旧命令行或配置键前检查兼容性与移除说明;按索引打开任务相关参考,并保持仓库的最低支持 Rust 版本。修改后应先用最窄范围的 Cargo 命令验证清单与配置,再运行完整测试套件。
内容按主题索引组织:升级与兼容性(安全修复、移除、弃用、默认值变化、平台要求、迁移风险);配置、网络与缓存(配置合并与 include、缓存清理、Git 与 SSH、代理、runner、警告策略);构建、目标与产物(edition、目标、构建目录、rustc 与 rustdoc、profile、doctest、产物、清理);工作区、依赖与元数据(工作区、特性统一、依赖树、元数据、vendoring、目标过滤);打包、发布与注册表(包验证、归档、工作区发布、注册表数据与 API);脚本、构建脚本与子命令(Cargo 脚本、构建脚本环境与元数据、外部子命令、补全与帮助);不稳定分析与 lint(构建分析、计时、SBOM 数据、Cargo lint、单元图、实验性构建控制)。
文档还包含破坏性变更与迁移检查:升级存在漏洞的 Cargo 安装,建议使用包含解压修复的工具链处理不可信 crate;用 plumbing 命令、--unit-graph 或结构化构建分析日志替代已移除的 build-plan;用 --artifact-dir 替代已移除的 --out-dir;用 -Zlockfile-path 下的 resolver.lockfile-path 替代 --lockfile-path 命令行用法;--timings 不再接受格式值;公共依赖使用 cargo tree --edges public;并提醒 cargo fix 与 cargo clippy --fix 默认只作用于默认目标、cargo publish 不保留生成的 .crate 归档、cargo metadata 独立于 CARGO_BUILD_TARGET、cargo install 忽略 resolver.lockfile-path、cargo package 包含 Cargo.lock 等默认行为变化。
高价值稳定特性方面,介绍了 build.build-dir 与 build.warnings、顶层 include 组合配置、host-tuple 目标选择、-m 作为 --manifest-path 短形式、cargo clean --workspace、工作区发布、http.proxy-cainfo、profile 的 immediate-abort panic 策略、target 表设置 rustdocflags、布尔字面量作为 cfg 谓词,以及构建脚本通过 CARGO_CFG_FEATURE 和 CARGO_CFG_DEBUG_ASSERTIONS 获得的信息。不稳定特性部分强调不要因相关组件稳定就删除必需的 -Z 标志,并需在对应参考中确认准确标志与当前行为,将 nightly 专用配置隔离。最后给出验证清单:确认 Cargo 版本与固定工具链、用受支持工具链解析所有改动过的清单和配置、工作区或依赖变化后运行 cargo metadata、包内容变化时运行 cargo package --list、必要时运行 cargo package、变更 runner 或目标相关标志时测试宿主与交叉目标路径、把注册表发布视为外部可见且非原子操作、避免依赖内部目标或构建目录布局,并记录不稳定标志的用途及所需命令。