rustc 错误 E0199 深度解析：safe trait 不允许 unsafe impl

导读

E0199 是 rustc 在 trait 一致性检查（coherence check）阶段报告的一类编译错误，其核心语义是：对安全（safe）trait 的实现被错误地标记为 unsafe impl。在 Rust 中，unsafe 修饰符只能且必须用于 unsafe trait 的实现，把它加在 safe trait 的实现上不仅毫无意义，还会触发编译失败。本文以 E0199.md 为骨架，结合 rustc 源码中的 unsafety checker、trait 实现安全模型及配套 UI 测试，完整讲解该错误的触发条件、编译器底层判定逻辑、修复方法与相关联的错误码。

E0199 是什么：诊断信息与触发场景

官方错误文档 E0199.md 对该错误的定义只有一句话：

A trait implementation was marked as unsafe while the trait is safe.

即“一个 trait 实现被标记为 unsafe，但该 trait 本身是安全的”。错误文档给出的失败示例为：

struct Foo;

trait Bar { }

unsafe impl Bar for Foo { } // error!

这里 Bar 是一个没有任何不安全约束的普通 safe trait，对 Foo 实现它不存在任何需要由实现者额外保证的 unsafe 不变式，因此在实现上书写 unsafe 关键字属于误用，编译器直接报 E0199。

需要特别说明的是，该示例在错误文档中被标注为 compile_fail,E0199，意思是它既是一个编译失败用例，同时也绑定了预期错误码，rustc 的测试体系会专门验证这一点（详见下文“测试与回归保障”）。

为什么 safe trait 不允许 unsafe impl：安全模型辨析

要理解 E0199，关键是分清 Rust 中两类 trait 在“unsafe 义务”上的差别：

1. safe trait（安全 trait）：例如 Bar 这样的普通 trait。实现者只需要满足 trait 定义的接口签名即可，编译器可以自动检查实现是否合法，实现本身“天然安全”，无需实现者声明额外义务。若 trait 上没有任何 unsafe 相关约束，给它加上 unsafe impl 是多余的——这正是 E0199 拦截的场景。

2. unsafe trait（不安全 trait）：例如 Send、Sync 以及所有用 unsafe trait 关键字声明的 trait。它们对实现者提出了编译器无法自动验证的不变量要求（例如“该类型可以跨线程共享”），实现者必须以 unsafe impl 形式“立下保证”。若 unsafe trait 被写成普通 impl，则会触发对偶错误 E0200（unsafe trait 缺少 unsafe 实现声明）；若通过 #[may_dangle] 之类属性间接引入 unsafe 义务而未写 unsafe impl，则触发 E0569。

三者构成一套完整的“安全矩阵”，可概括如下表：

实现写法	trait 本身安全（safe）	trait 本身不安全（unsafe）
impl Trait for T	合法	报 E0200（需要 unsafe impl）
unsafe impl Trait for T	报 E0199（不应写 unsafe）	合法

修复方式正如错误文档第二段代码所示：把多余的 unsafe 去掉即可：

struct Foo;

trait Bar { }

impl Bar for Foo { } // ok!

编译器底层实现：unsafety checker 的判定逻辑

E0199 并非在语法解析阶段产生，而是在类型检查过程中的 trait 一致性分析阶段被抛出的。其触发点在 unsafety.rs 中的 check_item 函数，它通过一个四元组模式匹配来决定报告哪个错误码：

match (trait_def_safety, unsafe_attr, trait_header.safety, trait_header.polarity) {
    (Safety::Safe, None, Safety::Unsafe, Positive) => {
        // 命中 E0199：trait 安全、无 may_dangle 类属性、impl 却标了 unsafe、极性为正向
        let span = tcx.def_span(def_id);
        return Err(struct_span_code_err!(
            tcx.dcx(),
            tcx.def_span(def_id),
            E0199,
            "implementing the trait `{}` is not unsafe",
            trait_ref.print_trait_sugared()
        )
        .with_span_suggestion_verbose(
            span.with_hi(span.lo() + rustc_span::BytePos(7)),
            "remove `unsafe` from this trait implementation",
            "",
            rustc_errors::Applicability::MachineApplicable,
        )
        .emit());
    }
    ...
}

从源码可以拆解出 E0199 的确切判定条件，四个维度缺一不可：

• trait_def_safety == Safety::Safe：目标 trait 定义本身是安全的；
• unsafe_attr == None：impl 上没有 #[may_dangle] 这类需要 unsafe 的 dropck 属性（否则会走 E0569 分支）；
• trait_header.safety == Safety::Unsafe：本次 impl 显式写了 unsafe 关键字；
• trait_header.polarity == Positive：这是一个正向（positive）实现，而非 negative impl（负实现另有 AST 校验兜底，见源码第 113–117 行的断言）。

值得一提的是 trait_def_safety 的取值并不总等于 trait 声明本身的安全性。check_item 的开头对 Copy trait 做了特殊处理（unsafety.rs）：当 Self 类型包含 unsafe 字段时，编译器会临时把 Copy 的实现“视为不安全”，此时反而要求写 unsafe impl；只有当类型没有 unsafe 字段时 Copy 才按 safe trait 处理。因此 E0199 的判定是综合 trait 声明与具体 Self 类型特征的动态结果。

E0199 是如何被触发的：一致性检查的调用链

check_item 并不直接由查询系统调用，而是作为 trait 一致性检查流水线中的一个环节被执行。调用关系如下：

1. coherent_trait 是 rustc 的 query（在 mod.rs 中定义），它遍历某 trait 的所有本地实现；
2. 对每个实现依次执行多项子检查，包括 check_impl（方法签名匹配）、check_object_overlap、unsafety::check_item、orphan_check_impl 与 builtin::check_trait（见 mod.rs）；
3. check_item 在 (Safety::Safe, None, Safety::Unsafe, Positive) 分支命中时，通过 struct_span_code_err! 宏上报 E0199 诊断并返回 Err，导致整个 coherent_trait 检查结果变为失败。

从工程视角看，unsafety checker 的价值在于把“trait 的安全性”和“impl 的 unsafe 声明”强制绑定：safe trait + unsafe impl（E0199）、unsafe trait + 普通 impl（E0200）、隐含 unsafe 义务却未声明（E0569）三种误用形式都由同一段模式匹配统一拦截，保持了诊断逻辑的内聚。

诊断输出与自动修复建议

错误文档只给出了“去掉 unsafe”这一结论，而实际编译器的诊断信息比文档更丰富。当触发 E0199 时，rustc 会输出主错误信息：

error[E0199]: implementing the trait `Bar` is not unsafe

同时，由于源码中通过 with_span_suggestion_verbose 附加了一个**机器可应用（MachineApplicable）**的自动修复建议，rustc --fix 或支持自动应用诊断建议的编辑器会直接提议删除 impl 前的 unsafe 关键字（见 unsafety.rs）。之所以适用性标注为 MachineApplicable，是因为去掉多余 unsafe 不会改变任何语义，属于完全安全的机械改写。这一点与 E0200/E0569 的诊断形成对比——后两者在 impl 前“补上” unsafe 时适用性仅为 MaybeIncorrect，因为添加 unsafe 意味着实现者要承担额外的不变量责任，编译器无法确认其正确性。

实战：E0199 的典型复现与解决步骤

在本地用任何 Nightly 工具链即可复现该错误。将下述文件作为 main.rs 保存并执行 rustc main.rs（或在 Cargo 项目中 cargo check）：

struct Foo;

trait Bar { }

unsafe impl Bar for Foo { }   // 编译报 E0199

观察到的输出大致为：

error[E0199]: implementing the trait `Bar` is not unsafe
  --> src/main.rs:6:1
   |
6  | unsafe impl Bar for Foo { }
   | ^^^^^^ remove `unsafe` from this trait implementation

error: aborting due to 1 previous error

修复有三种选择：

1. 首选：直接移除 unsafe，改成 impl Bar for Foo { }，代码即通过编译——这也是错误文档推荐的唯一正确写法；
2. 若 Bar 确实有需要实现者保证的不变量，说明它本该被声明为 unsafe trait，此时应回到 trait 定义处改为 unsafe trait Bar { }，并同步将实现写为 unsafe impl（但要注意修改 trait 后必须由实现者真正兑现不变量，否则引入的是正确性问题而非编译问题）；
3. 若本意是实现标准库中的安全 trait（如 Display、Clone 等），直接去掉 unsafe 即可，无需其它改动。

判断“该不该写 unsafe”的口诀：询问自己这个 trait 是否要求实现者保证编译器无法验证的不变量。若答案为否，它就是一个 safe trait，实现上写 unsafe 会撞上 E0199；若答案为是，则只有 unsafe impl 合法，漏写会撞上 E0200。

与相邻错误码的关系：E0200、E0569

E0199 并非孤立存在，它与同源检查器产出的另外两个错误构成一个完整的诊断族，对照阅读可加深理解：

• E0200：The trait X requires an unsafe impl declaration。即对 unsafe trait 写了普通 impl。其错误示例为 unsafe trait Bar + impl Bar for Foo，修复方式是在 impl 前补 unsafe 关键字。当 Self 含 unsafe 字段而实现 Copy 时也会走该分支，编译器会额外附注说明“该类型包含 unsafe 字段，请先审视其不变量”。
• E0569：当 impl 带有 #[may_dangle]（dropck 相关属性）、trait 本身安全且未写 unsafe 时触发，提示“requires an unsafe impl declaration due to #[{}] attribute”。

也就是说，unsafety checker 用三种错误码分别覆盖了“多写了 unsafe”“少写了 unsafe”“属性隐含 unsafe 义务却未声明”三类情况，其中 E0199 对应第一种。三者判定都在 unsafety.rs 的同一段 match 中完成，分支顺序即源码第 36–121 行，阅读源码时可通过该模式直观对照错误码的取舍逻辑。

测试与回归保障

rustc 为每个错误码都配套了编译期 UI 测试。E0199 对应的测试文件位于 tests/ui/error-codes/E0199.rs，其内容直接呼应本文开头给出的官方示例：

#![feature(negative_impls)]

struct Foo;

trait Bar { }
unsafe impl Bar for Foo { } //~ ERROR implementing the trait `Bar` is not unsafe [E0199]

fn main() {
}

其中 //~ ERROR 注释用于告诉 compiletest 框架“此行下方（含本行）的代码必须在编译时报出指定错误信息与错误码”，从而保证 E0199 的诊断文案、位置定位与错误码在每次编译器改动后依然稳定。若读者希望验证修复后的代码可正常编译，可将示例中的 unsafe impl 改为普通 impl 后通过 rustc 或 cargo check 验证。

小结

E0199 本质上是 Rust 编译器对“unsafe 关键字误用”的静态拦截：safe trait 的实现不得标记 unsafe。其底层由 unsafety.rs 中 (Safety::Safe, None, Safety::Unsafe, Positive) 的模式分支负责判定，经由一致性检查流水线 coherent_trait 触发，并附带了 MachineApplicable 的“删除 unsafe”自动修复建议。理解 E0199 与 E0200、E0569 的分工，能帮助开发者准确把握 Rust 中 safe/unsafe trait 与 unsafe impl 之间的对应关系，避免在使用并发原语、自定义 trait 或 dropck 相关属性时出现安全语义误配。