rustc 错误 E0476 深度解析：`CoerceUnsized` 自定义转换中"源指针生命周期不覆盖对象类型"

本篇文章围绕 rustc（Rust 编译器）仓库中的错误码文档 E0476.md，完整解读编译器错误 E0476（lifetime of the source pointer does not outlive lifetime bound of the object type）。文中结合 rustc 源码中该错误的真实触发代码、诊断生成链路与仓库内对应的 UI 回归测试，说明它为何只在 unstable 的 CoerceUnsized trait 场景出现、报错信息里"源指针 / 对象类型"究竟指什么，以及如何在自定义非安全大小（unsizing）转换实现中修正生命周期约束。读完本文，你将能读懂并修复这类与"生命周期子类型（outlives）约束"相关的强制转换编译错误。

错误总览：一句话理解 E0476

E0476: the coerced type does not outlive the value being coerced to.

该错误的完整诊断文本（正式报错主消息）为：

lifetime of the source pointer does not outlive lifetime bound of the object type

它描述的情形是：在一次**强制转换（coercion）**过程中，充当"源指针"（即被转换的类型 &'b S）的生命周期 'b，没有覆盖（outlive）作为"对象类型"（转换目标 &'a T）要求的生命周期 'a。Rust 无法证明 'b: 'a（即 'b 比 'a 活得更长或至少一样长），因此拒绝这次转换。

在 rustc 仓库中，错误码正文由 E0476.md 承载，可通过 rustc --explain E0476 查看；而错误码的主消息与诊断结构体定义位于 rustc_trait_selection 的 diagnostics.rs：

#[derive(Diagnostic)]
#[diag("lifetime of the source pointer does not outlive lifetime bound of the object type", code = E0476)]
pub(crate) struct OutlivesBound<'a> {
    #[primary_span]
    pub span: Span,
    #[subdiagnostic]
    pub notes: Vec<note_and_explain::RegionExplanation<'a>>,
}

触发示例：自定义 CoerceUnsized 实现

E0476 目前只能在 unstable 的 CoerceUnsized trait 场景中遇到。该 trait 允许开发者给"智能指针背后的 unsized 类型"实现自定义转换（例如把 Box<[i32; 3]> 转换成 Box<[i32]> 这样的操作）。下面的代码即文档中给出的错误示例，需要在 nightly 工具链下开启 coerce_unsized 与 unsize 两个 feature：

#![feature(coerce_unsized)]
#![feature(unsize)]

use std::marker::Unsize;
use std::ops::CoerceUnsized;

// error: lifetime of the source pointer does not outlive lifetime bound of the
//        object type
impl<'a, 'b, T, S> CoerceUnsized<&'a T> for &'b S where S: Unsize<T> {}

这个 impl 声明了：如果 S: Unsize<T>，那么一个 &'b S（S 是 sized 类型）可以被自定义转换为 &'a T（T 是无大小类型，例如 trait 对象 / 切片等）。编译器在检查这个 impl 时会发现生命周期约束不成立。

"源指针"与"对象类型"到底指什么

• 源指针（source pointer / coerced type）：被转换的 &'b S。它指向数据 S，只保证数据在 'b 内有效。
• 对象类型（object type / value being coerced to）：转换目标 &'a T。这里的 T 是无大小的"对象类型"（unsized type，如 dyn Trait），&'a T 是一个胖指针（wide pointer），其结果要能在 'a 内使用。

把 &'b S 变成指向 T（无大小目标）的 &'a T，本质上是在借用层面放大数据的"有效时间"：&'a T 要求底层数据活过 'a。只有当 'b: 'a（源数据活得比 'a 更久）时，产出的 &'a T 才不会悬垂。原示例没有声明 'b: 'a，于是编译器报出 E0476。

编译器的检查路径：从 impl 到错误诊断

理解 E0476 最好从 rustc 源码出发，追踪它在何处被判定失败、又在何处被渲染成最终错误。

1. 内置理解 CoerceUnsized：引用对引用要求 'b: 'a

CoerceUnsized 是被编译器"内置理解"（built-in trait）的 trait（lang item 为 coerce_unsized）。对 impl CoerceUnsized 这类需要编译器配合的实现，rustc 会进行专门的结构校验，相关代码在 rustc_hir_analysis 的 coherence/builtin.rs 中。当源类型与目标类型都是引用（&'a/&'b）时，代码会注册一条子区域约束：

(&ty::Ref(r_a, ty_a, mutbl_a), &ty::Ref(r_b, ty_b, mutbl_b)) => {
    infcx.sub_regions(
        SubregionOrigin::RelateObjectBound(span),
        r_b,
        r_a,
        ty::VisibleForLeakCheck::Yes,
    );
    // ...
}

sub_regions(origin, sup, sub) 表示要求 sup: sub，这里即要求 'b: 'a（源引用的生命周期 'b 必须覆盖对象类型引用的生命周期 'a）。SubregionOrigin::RelateObjectBound(span) 这个"区域来源标记"被单独定义，专门用于记录这一约束的产生点（见 rustc_infer/src/infer/mod.rs 的 RelateObjectBound(Span) 变体）。

2. 区域推断失败，产生 E0476

上一步注册的 'b: 'a 子区域约束会交给 rustc 的区域解析 / 类型检查逻辑求解。约束无法满足时，会产生一个 RegionResolutionError::ConcreteFailure。这类区域错误最终汇总到 trait selection 的 report_region_errors，并在 report_concrete_failure 中根据来源类型分派渲染（见 rustc_trait_selection/src/error_reporting/infer/region.rs）。其中 RelateObjectBound 分支正是唯一产生 E0476 的位置：

SubregionOrigin::RelateObjectBound(span) => {
    let object_valid = note_and_explain::RegionExplanation::new(
        self.tcx, generic_param_scope, sub, None,
        note_and_explain::PrefixKind::TypeObjValidFor,
        note_and_explain::SuffixKind::Empty,
    );
    let pointer_valid = note_and_explain::RegionExplanation::new(
        self.tcx, generic_param_scope, sup, None,
        note_and_explain::PrefixKind::SourcePointerValidFor,
        note_and_explain::SuffixKind::Empty,
    );
    self.dcx().create_err(OutlivesBound { span, notes: ... })
}

也就是说，错误在源码层面由 diagnostics.rs 的 OutlivesBound 结构体 + region.rs 的两个 note 子诊断共同构成。两条 note 分别描述：

• 目标（对象类型）要求的生命周期 'a；
• 源（指针）实际只保证的生命周期 'b。

真实报错输出逐行解读

仓库在 tests/ui/error-codes/ 下存放了 E0476 的回归测试。测试源文件 E0476.rs 用 Wrapper<T> 包装引用并开启 old / next 两个 revision（后者额外用 -Znext-solver=coherence），期望错误输出同时包含 E0476：

//@ revisions: old next
//@[next] compile-flags: -Znext-solver=coherence
#![feature(coerce_unsized)]
#![feature(unsize)]

use std::marker::Unsize;
use std::ops::CoerceUnsized;

struct Wrapper<T>(T);

impl<'a, 'b, T, S> CoerceUnsized<&'a Wrapper<T>> for &'b Wrapper<S> where S: Unsize<T> {}
//~^ ERROR lifetime of the source pointer does not outlive lifetime bound of the object type [E0476]
//~^^ ERROR E0119

fn main() {}

期望的 stderr 输出（E0476.next.stderr 与 E0476.old.stderr 内容一致）核心部分为：

error[E0476]: lifetime of the source pointer does not outlive lifetime bound of the object type
  --> $DIR/E0476.rs:11:1
   |
LL | impl<'a, 'b, T, S> CoerceUnsized<&'a Wrapper<T>> for &'b Wrapper<S> where S: Unsize<T> {}
   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   |
note: object type is valid for the lifetime `'a` as defined here
  --> $DIR/E0476.rs:11:6
   |
LL | impl<'a, 'b, T, S> CoerceUnsized<&'a Wrapper<T>> for &'b Wrapper<S> where S: Unsize<T> {}
   |      ^^
note: source pointer is only valid for the lifetime `'b` as defined here
  --> $DIR/E0476.rs:11:10
   |
LL | impl<'a, 'b, T, S> CoerceUnsized<&'a Wrapper<T>> for &'b Wrapper<S> where S: Unsize<T> {}
   |          ^^

可以看到两条 note 的定位与 region.rs 中 TypeObjValidFor / SourcePointerValidFor 两个前缀一一对应：'a 是"对象类型有效的生命周期"，'b 是"源指针仅有效的生命周期"。约束缺失一目了然。

此外该测试还会伴随报出 E0119（conflicting implementations）：stderr 的 note 指出 core crate 中已经存在形状完全相同的内置实现。这恰好印证了下一个事实。

为什么通常不需要自己写引用类型的实现

在标准库 core 的 ops/unsize.rs 中，&、&mut、*const、*mut 之间的 CoerceUnsized 内置实现已经声明齐全，并且无一例外地携带 'b: 'a 约束。例如：

#[unstable(feature = "coerce_unsized", issue = "18598")]
impl<'a, 'b: 'a, T: PointeeSized + Unsize<U>, U: PointeeSized> CoerceUnsized<&'a U> for &'b T {}

该文件同时包含 &'a mut U for &'b mut T、*const U for *mut T 等其他组合，且标准库实现均写明了 'b: 'a（可变引用 / 共享引用场景下源生命周期须覆盖目标生命周期）。正因为这些内置实现已覆盖引用类型，普通用户再写一个 impl CoerceUnsized<&'a T> for &'b S 不但会触发 E0476（缺 'b: 'a），即便补上约束也会与标准库实现重叠触发 E0119。

如何修复 E0476

修复的核心原则：让源指针的生命周期明确覆盖（outlive）对象类型要求的生命周期。具体手段有：

方案一：给 impl 的生命周期参数加上 'b: 'a 约束

把原示例改为与标准库内置实现一致的写法：

#![feature(coerce_unsized)]
#![feature(unsize)]

use std::marker::Unsize;
use std::ops::CoerceUnsized;

impl<'a, 'b: 'a, T, S> CoerceUnsized<&'a T> for &'b S where S: Unsize<T> {}

此时 'b: 'a 使区域约束可被证明，E0476 消失。（注：该例若要实际通过编译，还需规避与 core 内置引用实现 的 E0119 重叠冲突——引用与引用的转换标准库已提供，通常不必自行实现。）

方案二：自定义智能指针场景中，按字段保证生命周期顺序

E0476 的实用场景是给自定义智能指针结构体写转换，例如把 Foo<T, [i32; 3]> 转成 Foo<T, [i32]>。rustc 在 coerce_unsized_info 中会对这类结构体逐字段校验，要求最终落到"指针类型字段上的生命周期顺序"合理（builtin.rs 的注释对此有详细说明，见 coherence/builtin.rs）。当你给结构体同时引入源、目标两个生命周期参数、而内部指针字段无法满足 'b: 'a 时，就会出现 E0476。修复同样是：

• 若字段携带不同生命周期，在 impl 的 where 子句或类型参数中显式要求 'b: 'a；
• 若转换前后本应共享同一个来源借用，优先让结构体字段使用单一生命周期，从根上消除"目标生命周期长于源生命周期"的可能。

方案三：让约束由调用处类型系统自然保证

在大多数业务代码中，&dyn Trait / &[T] 这类 unsizing 转换由编译器根据标准库内置 CoerceUnsized 实现自动完成，并不需要你手写 CoerceUnsized impl。若你在日常代码中遇到 E0476，应先检查是否（不必要地）复制了本应由标准库提供的实现，而不是继续添加更多 impl。

何时会遇到 E0476：使用边界与注意事项

从本错误码文档与源码看，E0476 有以下使用边界：

• 只在 nightly 生效：CoerceUnsized 与 Unsize 仍是 unstable trait，需 #![feature(coerce_unsized)]、#![feature(unsize)]，对应 tracking issue #18598（可参见 core ops/unsize.rs 上的 unstable 标注）。

• 只在"自定义 CoerceUnsized 实现"这一路径上被触发：对稳定版用户而言，普通代码中的 unsizing 转换（如 &[i32; N] 到 &[i32]、Box<T> 到 Box<dyn Trait>）不会遇到该错误。

• 与生命周期子类型约束的常见错误为伴：E0476 属于 rustc 生命周期（region）错误族。仓库同目录下还有语义相邻的错误码，如：

  • E0312（引用的生命周期未覆盖其借用内容）
  • E0477（类型不满足要求的生命周期）
  • E0478（生命周期约束不满足）

  它们在 diagnostics.rs 中彼此相邻定义，都通过 report_region_errors 通道生成。

复现与验证

想要亲手验证 E0476，除按上文编写 nightly 代码片段外，还可以在 rustc 源码仓库中运行编译测试（compiletest UI 测试，需要 nightly bootstrap 工具链），例如：

./x.py test tests/ui/error-codes/

该目录下的 E0476.rs 会在 old 与 next（新求解器 coherence 模式）两个 revision 下运行，并与 E0476.old.stderr、E0476.next.stderr 比对，确认新旧 trait 求解路径下 E0476 的输出保持一致。遇到此类错误时，先运行 rustc --explain E0476 查看 E0476.md 给出的标准解释，再对照本文源码级路径定位约束来源，通常就能快速修正。