Rust 编译器错误码 E0466 深度解析：`[macro_use]` 宏导入声明语法与 rustc 属性解析实现

导读

E0466 是 rustc 早期用于报告 #[macro_use] 宏导入声明语法错误（invalid import declaration）的专用错误码。本文以 rustc_error_codes 中的 E0466 文档 为骨架，先说明它为何被标记为"编译器不再发出"，再完整梳理 #[macro_use] 合法语法与非法写法的边界，最后深入到 rustc 的属性解析源码（rustc_attr_parsing、rustc_attr_ir），揭示该语法在编译器内部的解析状态机与数据结构。读完你将掌握 #[macro_use] 的完整写法规则，理解 rustc 错误码生命周期管理方式，并能在自己的 crate 中正确地进行声明式宏导入。

---

一、E0466 是什么，为何"不再被编译器发出"

在 error_codes 文档目录 中，E0466.md 的第一行就给出了明确声明：

Note: this error code is no longer emitted by the compiler.

这并非文档缺失或占位，而是 rustc 错误码管理的一种正式状态。在 compiler/rustc_error_codes/src/lib.rs 的说明中明确写着错误码的维护纪律：

• 错误码解释文本统一定义在 error_codes/EXXXX.md 文件中；
• 不要从宏列表中删除已登记的条目；
• 若某错误码不再被编译器发出，应在对应 markdown 文件顶部添加说明（以 E0001.md 为范本），并将不再能编译通过的代码示例标记为 ignore。

也就是说，E0466 的编号与文档被保留用于历史兼容和查询，但现代 rustc 已不再产生带 E0466 标签的编译错误。究其根源，E0466 覆盖的场景——"macro_use 属性参数写成了非法形式"——属于属性声明层的语法错误（原文称之为 "a syntax error at the level of attribute declarations"）。这类错误如今已统一收敛到 rustc_attr_parsing crate 的新式属性解析与诊断框架中，由通用诊断（如 "expected identifier"、"expected a list or no arguments" 之类按对应诊断辅助函数生成的提示）直接报告，而不再对应一个专用错误码。

对学习者而言，E0466 的历史含义并未过时：它精确划定了 #[macro_use] 的合法参数文法。这正是本文要继续展开的核心内容。

---

二、历史错误场景：什么写法会被判定为 malformed

E0466 文档给出了两个曾经触发该错误的示例（文档中以 compile_fail 标注，即期望编译失败）：

#[macro_use(a_macro(another_macro))] // error: invalid import declaration
extern crate core as some_crate;

#[macro_use(i_want = "some_macros")] // error: invalid import declaration
extern crate core as another_crate;

两种写法分别违背了 #[macro_use] 参数文法的一条规则：

非法写法	违规点	现编译器解析时的处置（依据源码）
#[macro_use(a_macro(another_macro))]	参数列表中出现带括号的嵌套调用，而非裸标识符	列表项无法解析为无参数 meta 项，解析器对调用点报告"期望标识符"类错误
#[macro_use(i_want = "some_macros")]	参数使用了 名称 = 值（Name-Value）键值对形式	属性参数是 Name-Value 形态，不符合"无参数 Word 或标识符列表"文法，报告"期望列表或无参数"类错误

结合源码推断：在 rustc_attr_parsing 的 macro_attrs.rs 中，macro_use 的属性模板 MACRO_USE_TEMPLATE 只允许 Word 与 List（标识符列表）两种形态。当遇到 NameValue 时走 expected_list_or_no_args 分支；当列表元素不是纯标识符（例如是嵌套调用或键值对）时，元素会被 meta_item() / word() 解析失败，随后触发 expected_identifier 诊断，并对错误的 span 直接上报。这正是 E0466 历史诊断行为在现代实现中的落点。

一个额外的边界：空参数列表

从 macro_attrs.rs 的 ArgParser::List(list) 分支还可以看到另一个细节：若写成 #[macro_use()]（空括号），列表为空时解析器不会静默通过，而是调用 warn_empty_attribute 发出警告。也就是说，macro_use 后接空列表既不是"导入所有"，也不被当作正常导入——想导入全部宏，应使用不带括号的裸 #[macro_use]。

---

三、正确的宏导入声明语法

3.1 只导入部分宏：#[macro_use(宏名1, 宏名2, ...)]

E0466 文档给出了标准的跨 crate 宏导入写法。宏在源 crate 中需要先经 #[macro_export] 标记为可导出：

// In some_crate:
#[macro_export]
macro_rules! get_tacos {
    // ...
}

#[macro_export]
macro_rules! get_pimientos {
    // ...
}

// In your crate:
#[macro_use(get_tacos, get_pimientos)] // 仅导入 get_tacos 与 get_pimientos
extern crate some_crate;

要点拆解：

1. 带参数的 #[macro_use(...)] 实现选择性导入：括号内是逗号分隔的宏名标识符列表，注释语义为 "It imports get_tacos and get_pimientos macros from some_crate"；
2. 参数必须是纯标识符，每个名字对应源 crate 中一个经 #[macro_export] 导出的宏；名字拼写错误会落入相邻错误码 E0469（"imported macro not found"）的管辖范围；
3. 该属性在早期 Rust 版本中作用于 extern crate 语句（E0466/E0468 文档中的示例均为此形态），并必须位于 crate 根部——若写在嵌套模块里会触发相邻错误码 E0468（"must be at crate root to import"）。更准确地说，从 MACRO_USE_ALLOWED_TARGETS 看，#[macro_use] 的合法挂载目标是 Mod（模块）与 ExternCrate 两项。

3.2 导入全部宏：裸 #[macro_use]

E0466 文档的收尾给出了"导入所有"的规则：

If you would like to import all exported macros, write macro_use with no arguments.

即不带任何括号：

#[macro_use]
extern crate some_crate; // 导入 some_crate 中所有 #[macro_export] 的宏

这一"无参数 = 全量导入、带列表 = 定向导入"的双态设计，在编译器内部被建模为一个枚举。见 rustc_attr_ir 的 data_structures.rs：

pub enum MacroUseArgs {
    /// 对应裸 `#[macro_use]`：导入全部
    UseAll,
    /// 对应 `#[macro_use(name1, name2, ...)]`：仅导入列出的宏
    UseSpecific(ThinVec<Ident>),
}

该枚举最终被装入 AttributeKind::MacroUse { span, arguments }（见同一文件的 AttributeKind 定义），成为 rustc 内部 IR 中表达该属性的统一载体，供后续 resolve（名称解析）阶段消费。

---

四、源码级视角：rustc 如何解析 #[macro_use]

4.1 解析入口与属性模板

现代 rustc 将属性解析集中在 compiler/rustc_attr_parsing crate。macro_use 的解析器为 MacroUseParser，其声明的文法模板是：

const MACRO_USE_TEMPLATE: AttributeTemplate = template!(
    Word, List: &["name1, name2, ..."],
    // https://doc.rust-lang.org/reference/macros-by-example.html#the-macro_use-attribute
);

这从侧面印证了第三节的结论：macro_use 只接受两种形状——Word（裸关键字，全量导入）与 List（宏名列表，定向导入）；NameValue（键值对）形态在参数分发时直接进入报错分支。E0466 文档所谓 "syntax error at the level of attribute declarations"（属性声明层语法错误），正是指这类不符合模板的输入。

同一文件还定义了 macro_escape（MacroEscapeParser）作为 macro_use 的弃用同义词——这一关系也记录在 rustc_feature 的 builtin_attrs.rs 的注释中。

4.2 解析状态机：处理重复与混用

MacroUseParser 内部维护一个跨多条同名属性的状态机（state: MacroUseArgs），用于处理"一个 item 上叠加多个 #[macro_use]"的极端情况：

• 已处于 UseAll 又出现第二个裸 #[macro_use]：对后一个属性发重复告警（warn_unused_duplicate）；
• 先写了 #[macro_use(a, b)] 又补一个裸 #[macro_use]：由于裸形式代表"全量导入"已然覆盖定向导入，会将状态升级为 UseAll，并对此前的每条定向导入属性逐一告警（源码中遍历 uses_attr_spans 逐条 lint）；
• 定向导入分支中，逐一校验列表元素必须是无参数的纯标识符（expect_no_args + word()），否则按 2.1 节所述在非法 span 处报错。

4.3 合法挂载目标

MacroUseParser 的 ALLOWED_TARGETS 是：

const MACRO_USE_ALLOWED_TARGETS: AllowedTargets<'_> = AllowedTargets::AllowListWarnRest(&[
    Allow(Target::Mod),          // 模块（mod）上合法
    Allow(Target::ExternCrate),  // extern crate 上合法
    Error(Target::WherePredicate), // 其余目标报错
]);

据此可确认：#[macro_use] 的挂载点限定为模块与 extern crate 声明。把宏导入属性挂在其他位置（如函数、trait、where 谓词等）属于非法使用——错误码 E0468 专门覆盖了"非 crate 根模块中通过 extern crate 导入宏"这一种错误情形，其修复方法正是"将宏导入移动到 crate 根"或改用模块形态的 #[macro_use]。

---

五、现代 Rust 中的演进与替代写法

5.1 macro_use extern crate 已被标记弃用

虽然 #[macro_use] extern crate 是 E0466/E0468/E0469 文档中的经典形态，但从当前仓库的 lint 定义（rustc_lint_defs/src/builtin.rs 中 macro_use_extern_crate lint）可以看到，将 #[macro_use] 应用于 extern crate 已被弃用，编译器会给出 "the #[macro_use] attribute is now deprecated in favor of using macros with use" 之类的提示；可通过 #![deny(macro_use_extern_crate)] 将该弃用提升为硬错误。与此同时，模块形态（在 mod 上写 #[macro_use]）与 2018 edition 起支持的直接 use some_crate::some_macro; 路径导入，是更推荐的做法。

5.2 E0466 与相邻错误码的关系

E0466 所管辖的"属性写错了"，和它的两个邻居经常被混为一谈，三者分工其实很清晰：

错误码	触发场景	修复思路
E0466（不再发出）	#[macro_use] 参数文法非法（嵌套调用、键值对等）	改为裸 #[macro_use] 或纯标识符列表
E0468	非 crate 根模块中经 extern crate 导入宏	移到 crate 根，或改用模块形态
E0469	列出的宏不存在 / 未从目标 crate 导出	核对宏名拼写与 #[macro_export]

E0469 文档中"能跑通的版本"给出了与 E0466 文档一致的对称结构——源 crate 侧用 #[macro_export] 导出 eat!、drink!，使用者一侧用 #[macro_use(eat, drink)] extern crate some_crate; 定向导入。可见 E0466 确立的"参数列表文法"是整个宏导入体系的地基。

5.3 在本仓库中的真实应用

这套语法并非只存在于文档中。rustc 自身的多个 crate 至今仍使用 #[macro_use] 从内部 crate 拉取宏，例如 compiler/rustc_middle/src/lib.rs（第 67、70 行）、compiler/rustc_parse/src/lib.rs、compiler/rustc_attr_parsing/src/lib.rs 等文件顶部均能搜到 #[macro_use] 的身影。此外，仓库测试套件中的 run-make/env-dep-info/macro_use.rs 等用例还验证了 macro_use 场景下的依赖信息追踪——这说明正确解析宏导入声明对增量编译的依赖图构建同样意义重大。

---

六、小结与自查清单

围绕 E0466 这一"退休错误码"，核心知识可收敛为以下自查清单：

1. 裸用即全量：#[macro_use]（不带括号）导入目标 crate/module 导出的全部宏；
2. 列表即定向：#[macro_use(name_a, name_b)] 只导入列出的宏，列表元素必须是逗号分隔的裸宏名；
3. 三种非法形态不要碰：#[macro_use(a(b))] 式嵌套调用、#[macro_use(k = "v")] 式键值对、#[macro_use()] 式空列表（后者至少是告警）；
4. 目标 crate 侧要有 #[macro_export]，否则导入会落入 E0469 的"找不到宏"诊断；
5. 注意挂载位置：crate 根（extern crate 形态）或模块；extern crate 形态已弃用并应迁移到 use；
6. E0466 的报错职责已被 rustc_attr_parsing 的新式属性解析以通用诊断取代，编号被保留以兼容历史文档与查询。

无论你是想给存量老代码做宏迁移，还是想理解 rustc 错误码归档机制、属性解析框架的实现套路，E0466 这份文档连同其邻居 E0468/E0469 都是一份难得的历史+现状对照标本。