深入理解 Rust 编译器错误码 E0518：[inline] 属性误用与内联提示机制

E0518 是 Rust 编译器历史上用于报告“#[inline(..)] 属性被错误地放置在函数或方法之外”的错误码，其官方解释文档位于 E0518.md。本文以该错误码文档为核心，结合当前编译器仓库中 #[inline] 属性的解析实现与错误码管理机制，完整讲解 E0518 的原始定义、触发示例、#[inline] 三种取值的语义、现代编译器中该错误的演变方式，以及正确的修复做法，帮助你在阅读历史报错、维护旧代码或学习 rustc 错误码体系时建立准确的事实边界。

一、错误码 E0518 的原始定义：什么代码会触发它

根据官方错误码文档 E0518.md，E0518 的原始含义是：

An #[inline(..)] attribute was incorrectly placed on something other than a function or method. （#[inline(..)] 属性被错误地放置在函数或方法以外的东西上。）

文档给出的触发示例如下（注意文档中的代码块已标记为 ignore (no longer emitted)，表示该示例在现代编译器上不再产生 E0518，仅作为历史参考）：

#[inline(always)]
struct Foo;

#[inline(never)]
impl Foo {
    // ...
}

这段代码包含两处误用：

1. #[inline(always)] 被直接写在 struct Foo 定义上——结构体不是可内联的函数实体，该属性对其无意义；
2. #[inline(never)] 被写在 impl 块上——Rust 不允许用单个 #[inline] 属性对整个 impl 块的所有方法“批量生效”。

理解这两个误用是全文的关键：#[inline] 只针对函数和方法这一级别的作用单元，编译器从不会把属性“下放”到结构体字段、impl 块或 trait 声明等更大范围。

二、E0518 的现状：一个“不再发出”的历史错误码

需要先明确一个重要的事实边界：该错误码在当前编译器中已不再被发出。E0518.md 的第一行就注明：

Note: this error code is no longer emitted by the compiler. （注意：该错误码已不再被编译器发出。）

这并不意味着 E0518 从错误码体系中被删除了。rustc 对退役错误码有一套严格的保留机制，其规则记录在错误码汇总入口 rustc_error_codes/src/lib.rs 的注释中，要点如下：

• 不得从错误码列表中删除条目：在 error_codes! 宏中，0518 仍然占有一席之地（见 lib.rs 中的 0518 条目），以保证错误码编号的稳定性与文档链接的永久性；
• 退役方式是“加注记”：开发者只须在对应 markdown 文件头部加上“该错误不再被发出”的说明（E0001 是官方给出的范例），并移除所有已无法编译的示例；
• 失效示例的标注约定：不再构建的代码块须用 ignore (no longer emitted) 标记——这正是 E0518.md 中示例代码块的写法，也解释了为什么你在该文档里看到的是 ```ignore (no longer emitted) 而非普通代码块。

从这一机制可以推断：你在新版本 rustc 上把 #[inline] 写在 struct 或 impl 上，可能收到的是通用属性检查（attribute input check 一类）的诊断，或者被 rustc_attrs 工具属性检查接管，而不再是编号 E0518。但在阅读旧版编译器的日志、旧 issue 或第三方教程时，仍会遇到 E0518，理解其原始语义仍然必要。

三、#[inline] 的真实语义：三个层级与默认行为

E0518 文档在解释误用的同时，也说明了 #[inline] 本身的作用，这里展开讲清：

#[inline] 是一个提示（hint）类属性，用来影响编译器是否尝试内联某个函数或方法。文档原文指出：

#[inline] hints the compiler whether or not to attempt to inline a method or function. By default, the compiler does a pretty good job of figuring this out itself. 默认情况下，编译器自己能做得相当好。

结合当前仓库中属性的解析实现 rustc_attr_parsing/src/attributes/inline.rs，#[inline] 的三种写法与内部表示的对应关系非常清晰：

写法	内部表示	语义
#[inline]	InlineAttr::Hint	无参数时产生 Hint：给优化器一个“可以考虑内联”的提示，最终仍由编译器基于成本模型自行决策
#[inline(always)]	InlineAttr::Always	强制要求跨编译单元/跨代码边界内联该函数，覆盖编译器默认判断
#[inline(never)]	InlineAttr::Never	强制禁止内联，例如为调试或隔离体积考虑

解析逻辑中还有两个值得注意的细节：

• 参数列表只接受 always 和 never 两个单词，其他参数会触发 expected_specific_argument 诊断（inline.rs L50-L53）；
• name = "value" 这种键值形式属于畸形输入（ill-formed attribute input），会被 ILL_FORMED_ATTRIBUTE_INPUT lint 拦截（inline.rs L56-L59）。

此外，仓库中还存在一个不稳定的内部属性 #[rustc_force_inline]（inline.rs L64-L96），它比 #[inline(always)] 更激进，可携带 reason 参数说明强制内联的理由，且当它与普通 #[inline] 同时出现时会报告冲突错误。这属于 rustc 内部调试/基准用途（rustc_attrs feature gate），普通库代码不应使用。

四、现代编译器中 #[inline] 的合法目标：一份权威清单

既然 E0518 已退役，“把 #[inline] 写在哪里才算合法”这一问题现在由属性解析器中的 ALLOWED_TARGETS 白名单直接回答。当前实现位于 rustc_attr_parsing/src/attributes/inline.rs L13-L29，可以归纳为三类：

1. 允许（Allow）：自由函数、固有方法（inherent method）、带函数体的 trait 方法、trait impl 中的方法、闭包（closure）、非宏场景下的委托（delegation）。这是 #[inline] 的“主战场”，其中闭包是较新的扩展点，说明 E0518 时代“仅函数或方法”的描述在今天已被放宽；
2. 警告（Warn）：无函数体的 trait 方法签名、外部函数（foreign fn）、字段、宏定义、match 臂、关联常量、宏调用等——这些位置上属性不会生效，编译器会以警告提示你“这里不该写 #[inline]”；
3. 模板约束：属性模板为 Word, List: ["always", "never"]（inline.rs L30-L34），再次印证第二节中的取值约束。

从源码结构看，这套 Allow / Warn 分级正是 E0518 退役的直接原因：过去“放在非法目标上”是硬错误（E0518），现在被统一收编进通用的属性目标检查（allowed targets 检查与 ill-formed attribute input 一类诊断），错误编号不再单独保留。这也解释了为什么 lib.rs 中注明错误码的宏内容会接受 tidy 工具（check_error_codes_docs）的自动化校验——保证“退役注记”与文档格式始终符合 RFC 1567 规范化的错误码文档要求。

五、正确的修复方式：逐方法标注，而非标注 impl 块

回到 E0518 文档给出的修复指引，原文只有一句话但极为关键：

If you wish to apply this attribute to all methods in an impl, manually annotate each method; it is not possible to annotate the entire impl with an #[inline] attribute. 如果你希望对 impl 中的所有方法应用该属性，请手动逐个方法标注；不可能对整个 impl 使用 #[inline] 属性。

对照第二节中的错误示例，正确写法应当是：

// 错误：属性写在结构体或 impl 块上（E0518 的历史触发场景）
// #[inline(always)]
struct Foo;
// #[inline(never)]
// impl Foo { ... }

// 正确：把 #[inline] 标注到具体函数/方法上
struct Foo;

impl Foo {
    #[inline]
    pub fn bar(&self) -> u32 {
        42
    }

    #[inline(always)]
    pub fn baz(&self) -> u64 {
        7
    }
}

要点回顾：

• 结构体、枚举等类型定义本身不接受 #[inline]，因为内联的对象是“可调用的函数实体”，而非类型；
• impl 块是方法的集合容器，属性不会向下传播，必须落在每个 fn 上；
• 在 trait 定义中（无函数体的签名位置），#[inline] 目前只会得到警告——这也符合 inline.rs 中 Warn(Target::Method(MethodKind::Trait { body: false })) 的设定，语义上“强制内联”应当出现在提供实现的位置（impl 或带默认体的 trait 方法）。

六、E0518 在错误码文档体系中的位置与维护规则

对维护 rustc 或对错误码文档生成流程感兴趣的读者，E0518 恰好是理解整套体系的“活教材”：

• 集中管理：所有错误码解释文档集中在 compiler/rustc_error_codes/src/error_codes/ 目录，统一由 lib.rs 中的 error_codes! 宏汇总。该宏同时被 rustc_errors 等 crate 使用，是错误码文档与编译器实现的单一事实来源（single source of truth）；
• 命名与编号规则：E 前缀加四位数字（E0518），已废弃但未移除的编号会在列表中以注释说明原因（例如列表中的 0556, // REMOVED: merged with other attribute error codes，见 lib.rs L337）；E0518 属于“保留编号 + 文档加注记”这一保留类别，而不是被完全删除的编号；
• 格式规范：文档须遵循 RFC 1567 的长错误码解释规范化格式（lib.rs L12-L16），且宏内容会被 tidy 的 check_error_codes_docs 检查（lib.rs L18-L19）。

七、小结

• E0518 的原始语义是 #[inline(..)] 被写在了非函数/非方法目标（如 struct、impl 块）上，其历史示例与修复方法完整记录在 E0518.md；
• 该错误码在现代 rustc 中已不再发出，编号被保留在 error_codes! 宏 中以维持错误码体系的稳定性，其诊断职责被通用的属性目标检查（ALLOWED_TARGETS）取代；
• #[inline] 的三种形态（无参数 Hint、always、never）由 inline.rs 的解析器 精确实现，合法目标以“允许 + 警告”两级清单管理；
• 实战层面记住两条：想强制/禁止内联就写在具体 fn 上；想覆盖整个 impl 的所有方法，只能逐个方法标注，不存在“impl 级”的 #[inline]。