rustc 错误 E0264 完全解读：`unknown external lang item` 的成因、复现与修复方案

E0264 是 rustc 在使用 #[lang = "..."] 属性为**外部函数（extern 项）声明语言项（lang item）时，因该语言项不在"允许外部声明"的弱语言项清单中而触发的编译错误。理解这条错误，需要同时把握两条知识线：一是 Rust 编译器内部语言项（lang item）的注册机制，二是弱语言项（weak lang item）**与普通语言项在使用边界上的差异。读完本文，你将能准确复现 E0264、看懂报错背后的编译期校验流程，并写出可被编译器接受的 panic_impl、eh_personality 等外部语言项声明。

一、错误现象与官方示例

错误消息本身非常简短："An unknown external lang item was used."（使用了一个未知的外部语言项）。它的触发代码位于官方错误文档（compiler/rustc_error_codes/src/error_codes/E0264.md）中：

#![feature(lang_items)]
#![allow(internal_features)]

extern "C" {
    #[lang = "copy"] // error: unknown external lang item: `copy`
    fn copy();
}

在文档对应的测试指令中，compile_fail,E0264 表示该代码片段预期编译失败且产生 E0264。实际报错文本由编译器诊断结构体生成，完整信息形如：

error: unknown external lang item: `copy`

这条消息在源码中的精确模板定义于 compiler/rustc_attr_parsing/src/diagnostics.rs：

#[derive(Diagnostic)]
#[diag("unknown external lang item: `{$lang_item}`", code = E0264)]
pub(crate) struct UnknownExternLangItem {
    #[primary_span]
    pub span: Span,
    pub lang_item: Symbol,
}

即 code = E0264、消息为 unknown external lang item: `{$lang_item}` ，其中 $lang_item 是被错误声明的那条语言项的名字。

二、为什么会报错：强语言项与弱语言项的分界

要理解"为什么 copy 不行"，先要理解 Rust 的语言项机制。

**语言项（lang item）**是编译器约定的一类特殊项，用于把语言特性与标准库中的具体实现连接起来。正如 compiler/rustc_attr_ir/src/lang_items.rs 开篇注释所概括的，它们包括：

• 表达"类型种类"的 trait，例如 Sync、Send；
• 表达运算符重载的 trait，例如 Add、Sub、Index；
• 由编译器自身直接调用的函数。

copy 正对应 core::marker::Copy 这个 trait。它属于必须由标准库在 crate 内部以正常 Rust 项形式定义的普通（强）语言项，而不是供外部（extern）声明、再由运行时或标准库补充实现的弱语言项。

**弱语言项（weak lang item）**则是另一类：它允许用户在自己 crate 的 extern "C" 块中声明，编译器在链接/编译阶段再去寻找对应实现。当前仓库中，弱语言项的完整清单定义在 compiler/rustc_attr_ir/src/weak_lang_items.rs：

weak_lang_items! {
    PanicImpl,          rust_begin_unwind;
    EhPersonality,      rust_eh_personality;
}

这个 weak_lang_items! 宏会展开为三项能力（见同文件 L7-L24）：

• WEAK_LANG_ITEMS: &[LangItem] 静态清单；
• LangItem::is_weak()：判断某语言项是否为弱语言项；
• LangItem::link_name()：返回该弱语言项对应的链接符号名，例如 PanicImpl → rust_begin_unwind、EhPersonality → rust_eh_personality。

可以看到，当前仓库中真正允许"外部声明"的弱语言项只有两个：panic_impl 与 eh_personality。

三、报错产生的编译期校验流程

E0264 不是链接期错误，而是在属性解析阶段就会抛出的编译期错误。处理 #[lang = "name"] 属性的解析器是 LangParser，位于 compiler/rustc_attr_parsing/src/attributes/rustc_internal.rs。它的核心校验逻辑如下：

pub(crate) struct LangParser;

impl SingleAttributeParser for LangParser {
    const PATH: &[Symbol] = &[sym::lang];
    const ALLOWED_TARGETS: AllowedTargets<'_> = AllowedTargets::ManuallyChecked;
    const TEMPLATE: AttributeTemplate = template!(NameValueStr: "name");
    const STABILITY: AttributeStability = unstable!(lang_items);

    fn convert(cx: &mut AcceptContext<'_, '_>, args: &ArgParser) -> Option<AttributeKind> {
        let nv = cx.expect_name_value(args, cx.attr_span, None)?;
        let name = cx.expect_string_literal(nv)?;
        let Some(lang_item) = LangItem::from_name(name) else {
            cx.emit_err(UnknownLangItem { span: cx.attr_span, name });
            return None;
        };

        // Only weak lang items may be applied to foreign items,
        // except for `ForeignTy` which can be a normal lang item.
        if [Target::ForeignFn, Target::ForeignStatic, Target::ForeignMod].contains(&cx.target)
            && !lang_item.is_weak()
        {
            cx.emit_err(UnknownExternLangItem { span: cx.attr_span, lang_item: lang_item.name() });
            return None;
        }
        // ...
    }
}

把它拆成四步，报错原因一目了然：

1. 属性只接受 name-value 字符串形式：#[lang = "copy"] 必须写成等号字符串字面量，模板为 template!(NameValueStr: "name")，属性整体受 #![feature(lang_items)] 与 rustc_attrs 稳定性门控。
2. 名字必须属于已知语言项集合：LangItem::from_name(name) 会在 language_item_table! 宏展开出的完整 LangItem 枚举上做名字反查（对应 lang_items.rs 的 from_name）。若名字完全不认识，会走 UnknownLangItem 分支；官方文档与示例表同样生成自该枚举的 .name() 方法（L103-L110）。
3. 外部项上只放行弱语言项：当目标是 ForeignFn（外部函数）、ForeignStatic（外部静态量）或 ForeignMod（整个 extern 块）时，执行 !lang_item.is_weak() 检查。copy 不是弱语言项，因此在这一步触发 UnknownExternLangItem，即 E0264。
4. 唯一例外是 ForeignTy：注释明确写道外部类型允许是普通语言项，因此该分支只针对函数、静态量和块做限制。

值得注意，错误中 "unknown" 的含义是"不是允许用在这种外部位点上的语言项"，而不是"编译器不认识这个名字"——copy 编译器当然认识，但它不该出现在 extern "C" 块里。从报错信息 unknown external lang item: `copy` 与 lang_item: Symbol 的对应关系也能印证这一点。

四、正确的写法：使用弱语言项

官方文档紧接着给出了可编译的对照示例——把 copy 换成真正的弱语言项 panic_impl：

#![feature(lang_items)]
#![allow(internal_features)]

extern "C" {
    #[lang = "panic_impl"] // ok!
    fn cake();
}

这里的两个细节很能说明问题：

• 语言项由 #[lang = "..."] 里的字符串决定语义归属，与函数名无关，因此函数名叫 cake 也完全合法；PanicImpl 对应的实际链接符号 rust_begin_unwind 由 link_name() 给出，而非取自用户函数名。
• panic_impl 是运行时（no_std/自定义运行时）场景下注册 panic 处理函数的关键入口。同理可声明 #[lang = "eh_personality"] 对应 rust_eh_personality，用于定义栈展开（unwinding）时的人格函数。

五、为什么需要这些"占位声明"：缺失时的链接期兜底

把弱语言项声明放进 extern 块后，编译器如何决定"到底用没用上、缺不缺"？这部分逻辑在 compiler/rustc_passes/src/weak_lang_items.rs 的 verify() 中：

• 只有当产出类型不是 rlib（即 Dylib、ProcMacro、Cdylib、Executable、StaticLib、Sdylib）时才需要检查；rlib 作为中间库可以"先欠着"。
• 编译器会聚合各 crate 上报的 missing_lang_items，若某弱语言项确实缺失、且当前 crate 类型要求它（required(tcx, item)），但用户又没有通过本 crate 提供对应项（items.get(item).is_none()），则分别报出 MissingPanicHandler（缺 PanicImpl）或 PanicUnwindWithoutStd（缺 EhPersonality）等后续错误。

也就是说：#[lang = "panic_impl"] 这类外部声明是一条"我来提供实现"的登记，而 E0264 则是在这条登记链的入口处拦截掉不合法的项——两者共同保证了语言项与 DefId 之间的映射是干净的一一对应关系（LanguageItems 内部用数组 + 反查表维持这一双射，见 lang_items.rs）。

六、一处路径勘误与实践排查清单

官方文档末尾提到"可用外部语言项列表见 compiler/rustc_hir/src/weak_lang_items.rs"。在当前仓库中，由于编译器内部模块重组，弱语言项的权威定义已迁移至 compiler/rustc_attr_ir/src/weak_lang_items.rs，它被 rustc_attr_parsing（属性解析）与 rustc_passes（弱语言项校验）共同引用；rustc_attr_ir 目录还集中存放了完整的 LangItem 枚举表（lang_items.rs 起）。查询"某语言项是否可外部声明"，应以这两处为准。

遇到 E0264 时，按以下顺序排查：

1. 确认 #[lang = "x"] 是否写在 extern "C" { ... } 块（或外部函数、外部静态量）内——若不是，错误通常是其他目标不匹配类报错而非 E0264；
2. 对照 weak_lang_items.rs 中的清单，确认 x 是否仅为 panic_impl、eh_personality 二者之一；若是普通语言项（如 copy、add、send），请移除该外部声明，让标准库在 crate 内以正常项定义它；
3. 若 x 连已知语言项都算不上，报错会提前落在 UnknownLangItem 分支，而非 E0264；
4. 若确实需要自定义 panic 入口或栈展开人格函数，改用弱语言项写法，并确保最终链接目标（可执行文件、动态库等）上有对应符号可供解析。

七、小结

E0264 本质上是一道安全闸门：#[lang] 属性承担着把用户代码与编译器内部约定挂钩的重任，编译器绝不允许普通语言项通过 extern 块的旁路被冒名定义。它通过 LangParser 在属性解析期对"目标位点 + 弱语言项白名单"做联合校验，把 panic_impl、eh_personality 之外的一切项挡在外部声明的门外。理解这道闸门的判定顺序（名字合法性 → 位点合法性 → 弱项白名单），你就能在遭遇 E0264 时瞬间定位问题并给出正确的改写方案。