线上排查一个 Go 服务的错误日志时，发现所有经过 defer 包装的错误，errors.Is 全都返回 false，日志里的 %+v 也看不到原始堆栈。代码长这样：
func LoadConfig(path string) (cfg *Config, err error) {
defer func() {
if err != nil {
err = fmt.Errorf("load config failed: %w", err)
}
}()
f, err := os.Open(path)
if err != nil {
return nil, err
}
defer f.Close()
return parse(f)
}
看起来毫无问题，但调用方 errors.Is(err, os.ErrNotExist) 始终是 false。链断了，包出来的错误只包了一层”空气”。这个问题背后牵扯的是 Go 里两个非常容易混淆的机制：defer 对返回值的写入时机，以及命名返回值与普通返回值在 return 语句上的语义差异。下面按「执行顺序模型 → 三种典型踩坑形态 → 正确包装姿势 → 可测量的验证方法」的顺序拆开讲。
一、先把 return 拆成三步：Go 的返回值到底什么时候被赋值
面试里最标准的问法是：”return x 在执行 defer 之前还是之后完成赋值？” 答案是：赋值在 defer 之前，函数真正返回在 defer 之后。Go 规范把 return 语句拆成三个阶段：
- 设置返回值（return value assignment）：把 return 后面的表达式求值，写入返回值变量。如果函数有命名返回值，这一步就是写入那个命名变量。
- 执行 defer 链（run deferred functions）：按后进先出（LIFO）的顺序执行所有已注册的 deferred function。
- 函数返回：把返回值变量交给调用方。
用一个最小例子就能验证第 1 步先于第 2 步：
package main
import "fmt"
func order1() (x int) {
defer func() { fmt.Println("defer 看到 x =", x) }()
return 100
}
func main() {
fmt.Println("返回值 =", order1())
}
defer 看到 x = 100
返回值 = 100
关键点在于 defer 里能看到 x == 100，说明 return 100 已经把值写进了命名返回值 x。由此推出一个非常重要的结论：命名返回值是可以被 defer 修改的，因为 defer 执行时它已经是「返回值变量」本身，而不是一份拷贝。同样的 defer 如果写成 func() { x++ }()，函数最终返回 101。
但这里有个致命细节：能否修改，取决于 return 语句写入的是不是同一个变量。这就引出了下面三种形态。
二、形态一：命名返回值被同名局部变量遮蔽，defer 改的是空气
回到开头那段代码。它的问题不是 %w 用错了，而是 return nil, err 这个写法与命名返回值结合后产生的语义错位。先看一个能直接复现的等价例子：
func bad() (result int, err error) {
defer func() {
if err != nil {
err = fmt.Errorf("wrapped: %w", err)
}
}()
result, err = compute()
if err != nil {
return 0, err // 注意这一行
}
return result, nil
}
func compute() (int, error) {
return 0, errors.New("boom")
}
期望返回 wrapped: boom，实际返回的是裸的 boom。原因：return 0, err 是一条 显式指定返回值的 return 语句。Go 的处理是先把 0 赋给命名返回值 result，把 err（当前值）赋给命名返回值 err，然后再执行 defer。defer 里 err = fmt.Errorf(...) 改的确实是命名返回值 err，看起来应该生效才对。
那为什么没生效？因为第一行的 f, err := os.Open(path) 用了 :=。在 := 语句中，只要左侧有至少一个新变量，编译器就允许复用已存在的变量——但复用的前提是「同一作用域」。在 bad() 里 result, err = compute() 用的是 =，没这个问题；而原始代码里 f, err := os.Open(path) 位于函数体第一层作用域，err 是命名返回值本身，确实被复用而不是新建。这层没问题。
真正的问题在别处，需要逐帧分析。重新看最开始的 LoadConfig：
func LoadConfig(path string) (cfg *Config, err error) {
defer func() {
if err != nil {
err = fmt.Errorf("load config failed: %w", err)
}
}()
f, err := os.Open(path) // 第一层作用域，err 复用命名返回值
if err != nil {
return nil, err // 显式 return，err 被写入命名返回值
}
...
return parse(f) // 这条 return 有 2 个返回值吗？
}
陷阱就在最后一行：return parse(f)。如果 parse 的签名是 func parse(io.Reader) (*Config, error)，那么 return parse(f) 是一条合法的多值 return，会依次把两个结果赋给 cfg 和 err，defer 中的包装应当生效。但如果 parse 只返回 *Config，编译器会直接拒绝 not enough return values。
所以在原始代码里，包装不生效的真正原因通常只有两类：要么 defer 捕获的 err 是另一个作用域里的变量，要么 return 语句写死了显式值、而 defer 修改了另一个变量。最常见的写法错误是这个：
func bad2() (err error) {
defer func() {
if err != nil {
err = fmt.Errorf("step failed: %w", err)
}
}()
if err := doSomething(); err != nil { // 注意这个 :=，err 是新的局部变量
return err // 这条 return 把局部 err 赋给命名返回值
}
return nil
}
这个版本是能正常包装的，因为 return err 会把局部 err 的值写入命名返回值，defer 再改命名返回值，顺序正确。但如果写成 return errors.New("xxx") 或 return fmt.Errorf("...") 直接构造新错误而不经过变量，同样能正确赋值给命名返回值，defer 也能改。
真正会让包装”丢”的，是 defer 里重新声明了 err：
func bad3() (err error) {
defer func() {
if err != nil {
err := fmt.Errorf("wrapped: %w", err) // := 新建局部变量！
_ = err
log.Printf("error: %v", err)
}
}()
return errors.New("boom")
}
这段代码能编译、能打日志，但函数返回的还是裸的 boom。go vet 会给出提示：shadow: declaration of "err" shadows declaration at line ...。如果你在 CI 里跑了 go vet ./...，这个坑在合入前就会被拦住。
三、形态二：defer 注册顺序决定包装顺序，错误链的方向容易搞反
包装生效之后，第二个坑是多层 defer 的包裹顺序。defer 是 LIFO，所以先注册的 defer 后执行，落在错误链的最外层。看这段：
func multi() (err error) {
defer func() {
if err != nil {
err = fmt.Errorf("outer: %w", err)
}
}()
defer func() {
if err != nil {
err = fmt.Errorf("inner: %w", err)
}
}()
return errors.New("root")
}
输出是 outer: inner: root。因为 inner 那个 defer 注册得晚、执行得早，先把 root 包成 inner: root；随后 outer 的 defer 再把当前 err 包成 outer: inner: root。这个顺序符合直觉（像洋葱），但和「代码书写顺序」相反，读代码时容易误判哪层是最外层。
更隐蔽的是错误链的方向问题。如果每层都用 %w，errors.Unwrap 会一路剥到 root，errors.Is(err, target) 能命中任意一层。但如果某一层偷懒用了 %v：
defer func() {
if err != nil {
err = fmt.Errorf("outer: %v", err) // %v 断了链
}
}()
那么 errors.Is 走到 outer: ... 这一层就断了，返回 false，但错误消息字符串仍然包含 root 的文字。“日志看着对、程序判断全错” 就是这个组合的典型症状。判断标准很简单：%w 建立链，%v/%s 只做格式化。从 Go 1.20 起，fmt.Errorf 支持多个 %w，返回的错误实现了 Unwrap() []error，此时 errors.Is 会对每个子错误递归判断，但 errors.Unwrap 会返回 nil（它是 Unwrap() error 接口，不匹配 []error 版本）。需要遍历时用 errors.As 或自己检测 interface{ Unwrap() []error }。
| 格式化动词 | 是否建立错误链 | errors.Is 能否穿透 | 典型用途 |
|---|---|---|---|
%w |
是 | 能 | 包装并保留原始错误 |
%v |
否 | 不能 | 仅拼装消息，丢弃原错误身份 |
%s |
否 | 不能 | 同上，字符串化 |
多个 %w（Go 1.20+） |
是（多叉） | 能，逐子判断 | 合并多个错误 |
四、形态三：defer 里改的是值类型返回值，拷贝后修改无效
上一节讲的是错误（接口类型）。如果命名返回值是值类型，情况一样：defer 修改的是返回值变量本身，能生效。例如：
func val() (n int) {
defer func() { n *= 2 }()
return 5
}
// 返回 10
但如果 return 语句写的是一个值类型的表达式而函数签名是命名返回值，仍然先赋值后 defer，照样能改：
func val2() (n int) {
defer func() { n++ }()
return 5 * 2
}
// 返回 11
真正会让人误判的是非命名返回值 + defer 修改局部变量，这是面试高频题：
func noName() int {
n := 5
defer func() { n++ }()
return n
}
// 返回 5，不是 6
原因：return n 先把 n 的值拷贝到一个未命名的返回值临时位置（可以说是一个隐式的返回槽），defer 修改的是局部变量 n，两者已无关联。改成命名返回值就返回 6。
把这个结论迁移到错误包装场景，就得到一个很实用的规则：只要你想在 defer 里对返回值做「加工」（包装错误、补零值、改状态），就必须用命名返回值，并且 defer 里不能用 := 遮蔽它。想把命名返回值的问题彻底规避，还有另一个更推荐的写法：把加工逻辑放进一个辅助函数，直接返回加工后的值，不在 defer 里改返回值。这两种写法对比：
// A: 命名返回值 + defer 修改（要小心遮蔽）
func A(path string) (cfg *Config, err error) {
defer func() {
if err != nil {
err = fmt.Errorf("A: %w", err)
}
}()
return load(path)
}
// B: defer 不改返回值，用闭包 helper 显式包装
func B(path string) (*Config, error) {
cfg, err := load(path)
if err != nil {
return nil, fmt.Errorf("B: %w", err)
}
return cfg, nil
}
A 写法短，但每次读都得在脑子里跑一遍”return 赋值 → defer 执行 → 返回”三步；B 写法直白，go vet 和 reviewer 都能一眼看出包装位置。团队里如果多人协作，B 的维护成本更低。A 只在包装点非常多（比如一个函数里有 5 条以上 return）时才明显占优。
五、panic 场景：recover 与命名返回值的交互
defer 的另一个常考组合是 recover。当 defer 里执行 recover() 吞掉 panic 后，函数会正常返回——返回的是什么值？ 如果 panic 发生在 return 赋值之前，命名返回值还是零值；如果发生在赋值之后（比如 defer 链中途 panic），命名返回值保留已赋的值。
func safeDiv(a, b int) (result int, err error) {
defer func() {
if r := recover(); r != nil {
err = fmt.Errorf("panic recovered: %v", r)
// result 保持 panic 前的值（这里是 0）
}
}()
return a / b, nil // b == 0 时触发 panic
}
调用 safeDiv(1, 0) 返回 (0, "panic recovered: runtime error: integer divide by zero")。注意 err 的赋值发生在 defer 中，只有命名返回值才能把 recover 产生的错误传出去；如果写成非命名返回值，recover 里对 err 的赋值不会影响最终返回值，调用方拿到的是零值——这在面试里几乎必问，因为它是 recover 唯一”有用”的出口。
注意事项：recover 返回的类型是 interface{}，直接 %v 进错误消息会丢堆栈。要保留堆栈需要显式 debug.Stack()，或者直接用 github.com/pkg/errors（老项目）或 runtime/debug。生产代码里更推荐在 HTTP/gRPC 中间件层统一 recover，业务函数不要到处写 recover，否则错误处理会散落在各处。
六、可测量验证：写测试把执行顺序钉住
这类陷阱光看出错现象不够，建议用表驱动测试把语义固化。下面是一组能直接跑的真实测试，覆盖命名返回值、非命名返回值、遮蔽、错误链穿透四种情况：
package defertest
import (
"errors"
"fmt"
"testing"
)
var errRoot = errors.New("root")
func named() (err error) {
defer func() {
if err != nil {
err = fmt.Errorf("named: %w", err)
}
}()
return errRoot
}
func unnamed() error {
err := errRoot
defer func() {
err = fmt.Errorf("unnamed: %w", err) // 改的是局部变量
}()
return err
}
func shadowed() (err error) {
defer func() {
if err != nil {
err := fmt.Errorf("shadowed: %w", err)
_ = err
}
}()
return errRoot
}
func TestDeferOrder(t *testing.T) {
cases := []struct {
name string
fn func() error
wantMsg string
wantIsRoot bool
}{
{"named", named, "named: root", true},
{"unnamed", unnamed, "root", true},
{"shadowed", shadowed, "root", true},
}
for _, c := range cases {
t.Run(c.name, func(t *testing.T) {
err := c.fn()
if err.Error() != c.wantMsg {
t.Fatalf("msg = %q, want %q", err.Error(), c.wantMsg)
}
if got := errors.Is(err, errRoot); got != c.wantIsRoot {
t.Fatalf("errors.Is = %v, want %v", got, c.wantIsRoot)
}
})
}
}
=== RUN TestDeferOrder
=== RUN TestDeferOrder/named
=== RUN TestDeferOrder/unnamed
=== RUN TestDeferOrder/shadowed
--- PASS: TestDeferOrder (0.00s)
--- PASS: TestDeferOrder/named (0.00s)
--- PASS: TestDeferOrder/unnamed (0.00s)
--- PASS: TestDeferOrder/shadowed (0.00s)
PASS
注意 unnamed 和 shadowed 的断言：消息里没有包装前缀，但 errors.Is 仍然命中 root，因为根本就没包上，错误就是原始的 errRoot。这种测试能精确区分”包装成功”和”包装失败但日志看起来正常”两种状态，比肉眼看日志可靠得多。
想自动化拦截这类问题，在 CI 里加上：
go vet ./... # 捕获 shadow 声明
go test -race ./... # 顺带覆盖 defer 与 goroutine 交叉场景
staticcheck ./... # SA4006 / S1021 等检查可辅助发现无效赋值
如果项目里已经有大量 defer 包装，可以用 golangci-lint 的 errcheck、wrapcheck 插件补一层。wrapcheck 会强制跨包返回的错误必须被包装，间接减少”包装全丢”的代码进入主干。
七、速查表：defer × 返回值组合的行为
| 函数签名 | return 写法 | defer 中修改 | 最终返回 |
|---|---|---|---|
(err error) |
return errRoot |
err = wrap(err) |
包装后的错误 |
(err error) |
return errRoot |
err := wrap(err) |
原始 errRoot（被遮蔽） |
error（非命名） |
return err |
err = wrap(err) |
原始 err（改了局部变量） |
(n int) |
return 5 |
n++ |
6 |
int（非命名） |
return n |
n++ |
原值（改的是局部变量） |
(result int, err error) |
panic 后 recover | err = ... |
err 生效，result 为零值 |
小结
return分三步：先赋值给返回值变量，再跑 defer，最后交给调用方。能在 defer 里改返回值的唯一前提是”命名返回值 + 不遮蔽”。- 错误包装失效最常见的两种原因是：defer 里用
:=遮蔽了命名返回值；或者用%v替代了%w导致错误链断裂。前者go vet可查，后者只能靠errors.Is单测兜底。 - 多层 defer 是 LIFO，先注册的在外层，错误消息的包裹顺序与代码书写顺序相反。
- 非命名返回值的函数，defer 修改局部变量对最终返回值没有影响；
recover要把错误传出去，必须依赖命名返回值。 - 团队规范上，优先使用”显式在 return 前包装”而不是”defer 里改返回值”，可读性和可测性都更好。
FAQ
Q1：既然命名返回值能被 defer 改，为什么 Go 官方风格指南不推荐滥用？
因为命名返回值让函数的返回路径变得不直观：读者必须同时追踪 return 语句和所有 defer 才能确定最终返回值。对于短函数（10 行以内）影响不大，对于长函数就是维护负担。官方更推荐只在两种场景使用命名返回值：需要在 defer/recover 中设置错误，或者返回值语义需要文档化（比如 (result []byte, err error) 明确字段含义）。
Q2：defer f.Close() 里的错误为什么经常被吞掉？怎么正确地合并？
defer f.Close() 直接丢弃了 Close 的返回值。如果写操作有缓冲，Close 才是真正 flush 并报错的地方，吞掉就会丢数据。正确做法是命名返回错误并合并：
func writeFile(path string, data []byte) (err error) {
f, err := os.Create(path)
if err != nil {
return err
}
defer func() {
if cerr := f.Close(); cerr != nil && err == nil {
err = cerr
}
}()
_, err = f.Write(data)
return err
}
注意条件是 err == nil，否则原始写错误会被 Close 错误覆盖。Go 1.20+ 可以用 errors.Join(err, cerr) 保留两个错误。
Q3：errors.Is 和 errors.As 到底什么时候用哪个？
errors.Is(err, target) 用于比较错误身份，判断链上是否存在与 target 相等的错误（通过 == 或 Is 方法）。errors.As(err, &target) 用于提取错误类型，把链上第一个可赋值给 target 类型的错误取出来。典型用法：判断文件不存在用 errors.Is(err, fs.ErrNotExist)；取出 *MyError 里的字段用 var me *MyError; errors.As(err, &me)。两者都要求链上的每一层用 %w 包装。
Q4：报错 declared and not used: err 或 no new variables on left side of := 怎么处理？
前者是 := 新建了变量却没使用，Go 编译器直接拒绝编译；后者是 := 左侧全是已有变量。这两种都说明你在 defer 里或错误处理分支里误用了 :=。正确做法：想复用命名返回值就用 =，想新建局部变量就用 := 且确保后面真的用到。遇到 shadow: declaration of "err" shadows declaration 的 vet 警告，先确认是否是有意新建——绝大多数情况是无意的，改成 = 即可。
Q5：性能上，defer 在热点路径会有开销吗？
Go 1.14 引入 open-coded defer 之后，非循环体内、defer 数量固定的场景基本没有额外开销（编译期内联，常见场景下性能与不用 defer 持平）；循环体内或 defer 数量动态的场景仍走堆分配路径，会有约几十纳秒级别的开销。错误包装通常发生在错误路径上，不在热点路径，不需要为此放弃 defer。真要抠性能，用 go test -bench 对比 BenchmarkDefer 与直接调用即可，不要凭印象优化。
Q6：多个 goroutine 同时写同一个命名返回值会怎样？
会出现 data race，go test -race 会直接报 WARNING: DATA RACE。命名返回值本质上只是函数栈上的变量，没有同步保护。如果 defer 里启动了 goroutine 并在其中读写返回值，必须用 sync.WaitGroup 等待并在 defer 结束前完成，或者干脆不在 defer 里跨 goroutine 修改返回值。这个模式在”异步上报耗时”的代码里很常见，但上报耗时不需要写返回值，只需读，改成只读就不会有 race。