Rust proc-macro crate 不可用 — 宏导入失败

症状

本篇指南处理“Rust proc-macro crate 不可用 — 宏导入失败”。请从症状出发，按顺序执行诊断，在推进前确认每个假设；随后通过修复与验证步骤闭环。

可观察到的症状包括：

• error: proc-macro crates cannot export items other than macros
• error[E0433]: failed to resolve: could not find X in Y
• 仅在下游 crate 中 derive 宏失败

诊断

先在隔离环境中复现故障，再按顺序执行以下检查，逐步缩小范围。

步骤 1

grep -n "proc-macro" Cargo.toml

定义 derive 的 crate 必须在 [lib] 下声明 proc-macro = true，否则无法定义 derive。

步骤 2

cargo build 2>&1 | grep -E "proc-macro|E0433" | head

解析失败会指出 crate 与项，说明是导出还是依赖配置有误。

常见诱因（按出现频率排序）：

• proc-macro crate 试图导出普通项，或作为普通依赖使用
• derive 宏定义在未设置 proc-macro = true 的 crate 中
• 宏未通过必要的 pub use 或门面 crate 再导出

根因

proc-macro crate 会编译为编译器插件，只能导出宏。若它同时导出 trait 或函数，构建会失败；使用方必须通过合法导出该宏的 crate 导入。

修复

拆分 crate：让 proc-macro crate 只定义宏，把共享项移到普通库 crate，并通过门面再导出 derive，使用户只导入一个 crate。

注意：更改 crate 类型会破坏既有导入路径；应提供门面并逐步弃用旧路径。

# Cargo.toml of the proc-macro crate
[lib]
proc-macro = true

[dependencies]
syn = "2"
quote = "1"

# Facade crate re-exports the derive so users import one path
# lib.rs
pub use my_derive::MyTrait;

验证

cargo build 通过且下游 crate 可 derive 该宏；cargo doc 显示宏由门面导出。

修复后补充一条回归测试，复现原始症状，防止问题再次出现。

这类故障通常是环境问题而非纯逻辑错误，因此在缺陷记录中应写明完整命令、环境变量与工作目录。请用最小的脚本复现，待最小用例清楚后再扩大范围。为这类故障准备一份简短的排查清单，能显著减少下次排障时间。