错误格式化

很多人看到 fmt.Errorf 中的 %w 时，会误以为它只能写在格式字符串的最后。实际判断标准不是“是否在末尾”，而是两个位置能否正确配对：格式字符串里的动词位置，以及参数列表里的操作数位置。只要对应操作数实现了 error，%w 可以出现在前缀、中间或后缀，并把错误关系保留下来。

结论：%w 是“带错误包装的 %v”。先保证它绑定到正确的 error 参数，再根据调用方是否需要 errors.Is 或 errors.As 来决定使用它还是普通的 %v。

背景：%w 解决的不是字符串拼接

错误返回通常需要补充上下文，例如“读取配置失败”或“保存订单失败”。如果只用 %v，最终文本看起来完整，但原始错误的身份不会继续暴露给调用方；调用方只能再次解析字符串，这会让判断变得脆弱。

Go 1.13 引入了 %w，让 fmt.Errorf 在格式化文本的同时包装底层错误。这样调用方可以用 errors.Is 判断哨兵错误，用 errors.As 提取具体错误类型。Go 1.20 起，fmt.Errorf 还支持多个 %w，返回的错误可以展开为多个被包装错误。

旧写法的问题：看字符串位置，不看参数绑定

下面三种写法的区别不在于 %w 是否位于末尾，而在于它绑定到哪个参数：

package main

import (
	"errors"
	"fmt"
)

var errConfig = errors.New("配置缺失")

func examples() {
	// %w 可以出现在前缀、中间或后缀，关键是它对应 error 参数。
	a := fmt.Errorf("%w：读取配置", errConfig)
	b := fmt.Errorf("读取配置：%w", errConfig)
	c := fmt.Errorf("读取%w失败", errConfig)

	// %v 只保留格式化文本，不建立可供 errors.Is 检查的包装关系。
	d := fmt.Errorf("读取配置：%v", errConfig)

	_, _, _, _ = a, b, c, d
}

前三个结果的展示文本可能不同，但它们都把 errConfig 放进了错误链。d 的文字也可能相似，却只完成了文本格式化。如果业务需要判断“是否就是配置缺失”，就不能把 %w 和 %v 当作同义写法。

新规则：按格式动词和操作数位置配对

可以把 fmt.Errorf(format, args...) 看成两层关系。第一层是格式字符串扫描到的动词，例如 %w 或 %v；第二层是动词根据普通顺序或显式索引取到的参数。真正被包装的是 %w 取到且实现了 error 的那个操作数。

package main

import (
	"errors"
	"fmt"
)

var errTimeout = errors.New("请求超时")

func indexed() error {
	// 显式索引让格式位置和参数位置可读，但不能把非 error 参数伪装成 error。
	return fmt.Errorf("原因：%[2]w；资源：%[1]s", "用户服务", errTimeout)
}

这里的 %[2]w 明确取第二个参数，因此包装的是 errTimeout；%[1]s 取第一个参数作为普通文本。索引改变的是取参位置，不改变 %w 必须绑定 error 的要求。

多个 %w：版本语义和错误类型都要看

如果一个格式字符串中有多个 %w，Go 1.20 及之后的标准库会按出现顺序收集其中实现了 error 的操作数。它适合表达一个结果同时受到多个原因影响的场景，但不要为了“看起来完整”无条件堆叠错误。

package main

import (
	"errors"
	"fmt"
)

var (
	errRead  = errors.New("读取失败")
	errClose = errors.New("关闭失败")
)

func combine() error {
	// 多个 %w 表示多个可检查原因；这里只传入实现 error 的值。
	return fmt.Errorf("处理文件：%w；收尾：%w", errRead, errClose)
}

如果项目需要兼容 Go 1.20 之前的工具链，就不要把多个 %w 当成可用能力；应改成单层包装、显式定义组合错误，或使用项目已支持的兼容方案。另一个边界是操作数类型：%w 不是“任何值都能保留关系”的特殊字符串，传入非 error 值时，不能得到有效的错误包装。

兼容注意：调用方应该检查关系，不要解析错误文本

包装的价值要在调用方体现。判断固定错误使用 errors.Is，提取结构化错误使用 errors.As；只有当调用方明确只需要展示文本时，才适合使用 %v。

package main

import (
	"errors"
	"fmt"
)

func handle(err error) string {
	// Is 检查错误链中的身份，不依赖 Error 文本是否带了上下文。
	if errors.Is(err, errTimeout) {
		return "可以重试"
	}

	// As 适合提取调用方需要的具体错误类型。
	var target *MyError
	if errors.As(err, &target) {
		return target.Code
	}

	// 未识别的错误保留原文，避免把未知原因误判成已知类别。
	return fmt.Sprint(err)
}

type MyError struct{ Code string }

func (e *MyError) Error() string { return e.Code }

示例中的检查顺序只是一个常见决策方式：先判断稳定的哨兵错误，再尝试提取类型，最后才回退到文本。不要用字符串前缀代替错误链判断，也不要因为格式字符串里出现了 %w 就自动把所有底层错误暴露成公共 API。

采用建议：用四个问题快速判断

所以，“%w 为什么只能出现在 Errorf 的指定位置”这个问题的准确答案是：它没有“只能在末尾”的位置限制，但必须出现在格式字符串中，并通过取参规则绑定到正确的 error 操作数。位置、类型和调用方检查方式，三者缺一不可。

常见问题

%w 能否放在文本中间？

可以。它可以和前缀、后缀及其他格式动词混排，关键是对应参数必须是 error。

%w 和 %v 打印出来一样，为什么还要区分？

它们的展示形式通常相近，但 %w 额外保留错误关系，调用方可以继续使用 errors.Is 或 errors.As。

多个 %w 是否总是更好？

不是。它表达多个原因时有价值，但会扩大调用方可观察的错误集合；如果项目需要旧版本兼容，还要先确认工具链边界。