cargo-machete

cargo-machete - 未使用依赖检测

使用 cargo-machete 检测并移除 Rust 项目中的未使用依赖。

何时使用此技能

在以下情况下使用此技能……	在以下情况下改用 X……
审查未使用的依赖	检查过时的依赖——使用 cargo outdated
清理 Cargo.toml	审查安全漏洞——使用 cargo audit
通过移除冗余依赖来优化构建时间	检查许可证合规性——使用 cargo deny
在 CI 中验证依赖	需要精确到 nightly 的分析——使用 cargo +nightly udeps

上下文

• Cargo.toml：!find . -maxdepth 1 -name \'Cargo.toml\'
• 工作区：!find . -maxdepth 1 -name 'Cargo.toml' -exec grep -q '\[workspace\]' {} +
• 已安装 cargo-machete：!cargo machete --version
• Machete 配置：!find . -maxdepth 1 -name \'.cargo-machete.toml\'
• 工作区成员：!find . -maxdepth 1 -name 'Cargo.toml' -exec grep -A 20 '^\[workspace\]' {} +

执行

执行以下未使用依赖分析：

第 1 步：确认已安装

检查是否已安装 cargo-machete（参见上面的上下文）。如果尚未安装，请安装：

cargo install cargo-machete

第 2 步：运行依赖分析

运行 cargo-machete 并附带元数据，以获取详细输出：

# Single crate
cargo machete --with-metadata

# Workspace (if Context shows workspace)
cargo machete --workspace --with-metadata

第 3 步：评估结果

查看输出并对每项发现进行分类：

发现	操作
确实未使用的依赖	使用 --fix 移除，或手动移除
Proc-macro 依赖（例如 serde derive）	添加 machete:ignore 注释
仅供 Build.rs 使用的依赖	移至 [build-dependencies]
重新导出的依赖	添加带说明的 machete:ignore 注释

第 4 步：应用修复

对于确认未使用的依赖，自动将其移除：

cargo machete --fix

对于误报，在 Cargo.toml 中添加忽略标注：

serde = "1.0"  # machete:ignore - used via derive macro

或者创建 .cargo-machete.toml，配置项目范围的忽略项：

[ignore]
dependencies = ["serde", "log"]

第 5 步：验证构建

移除依赖后，确认所有内容仍可成功编译：

cargo check --all-targets
cargo test --no-run

处理误报

场景	解决方案
Proc-macro 依赖（例如 serde derive）	添加 machete:ignore 注释
仅供 Build.rs 使用的依赖	移至 [build-dependencies]
重新导出的依赖	添加带说明的 machete:ignore 注释
仅供示例/基准测试使用的依赖	确认其位于 [dev-dependencies] 中

与 cargo-udeps 的比较

特性	cargo-machete	cargo-udeps
准确性	良好	极佳
速度	非常快	较慢
Rust 版本	稳定版	需要 nightly
误报	有一些	较少

使用 cargo-machete 执行快速 CI 检查。使用 cargo-udeps 进行全面审查：

cargo +nightly udeps --workspace --all-features

Agent 优化

上下文	命令
快速检查	cargo machete
详细检查	cargo machete --with-metadata
工作区检查	cargo machete --workspace --with-metadata
自动修复	cargo machete --fix
修复后验证	cargo check --all-targets
精确检查（nightly）	cargo +nightly udeps --workspace

快速参考

标志	说明
--with-metadata	显示包含版本和位置的详细输出
--fix	自动从 Cargo.toml 中移除未使用的依赖
--workspace	检查所有工作区成员
-p <crate>	检查指定的工作区成员
--exclude <crate>	排除指定的工作区成员

故障排除

问题	解决方案
Proc macro 被标记为未使用	在 Cargo.toml 中添加 machete:ignore 注释
Build.rs 依赖被标记	移至 [build-dependencies]
重新导出的依赖被标记	添加带说明的 machete:ignore 注释
需要更高的准确性	使用 cargo +nightly udeps

有关 CI 集成模式、配置文件示例、pre-commit 设置和 Makefile 集成，请参阅 REFERENCE.md。