Go errors.Join 为什么格式化后是多行文本

errors.Join 格式化后出现多行，是标准库定义的结果，不是 fmt 随机插入了换行。它会先丢弃 nil 错误，再按参数顺序取得每个子错误的 Error() 文本，并在文本之间放入换行符。因此 %v、%s 或直接打印这个 error 时，看到的就是逐行排列的消息。

官方文档：https://pkg.go.dev/errors

为什么 errors.Join 会自然显示成多行

把两个错误合并后，最终 error 仍然只有一个外层值，但它的展示文本由多个子错误组成。下面的最小示例故意同时打印普通文本和带引号的文本，方便区分“真的有换行”和“终端换行显示”。

package main

import (
	"errors"
	"fmt"
)

func main() {
	first := errors.New("文件校验失败")
	second := errors.New("远端请求失败")
	joined := errors.Join(first, second)

	fmt.Printf("%v\n", joined)   // 普通展示：两个 Error 文本各占一行
	fmt.Printf("%q\n", joined)   // 引号展示：把换行显示为转义序列
	fmt.Printf("%s\n", joined)   // 字符串展示：仍按 Error 文本输出
}

%q 适合排查隐藏的换行符；如果子错误自身已经包含换行，最终行数还会继续增加。这个行为不是日志框架的特殊规则，任何依赖 error 文本的展示方式都可能保留它。

这不是一条字符串：Join 仍然保留错误树

多行只是 Error() 的展示结果。非空的 Join 返回值还实现了 Unwrap() []error，因此调用方不应该用字符串包含判断来识别失败类型。标准库的 errors.Is 和 errors.As 会继续遍历这些子错误。

var (
	errPermission = errors.New("权限不足")
	errTimeout    = errors.New("请求超时")
)

func check(joined error) string {
	if errors.Is(joined, errTimeout) { // 判断语义：命中超时成员
		return "可重试"
	}
	if errors.Is(joined, errPermission) { // 判断语义：命中权限成员
		return "先授权"
	}
	return "人工排查"
}

还有一个容易混淆的边界：errors.Unwrap(joined) 只处理返回单个 error 的 Unwrap() error，不会把多错误切片直接交出来。需要读取全部成员时，应使用类型断言获取 Unwrap() []error，但业务判断通常让 Is/As 完成即可。

日志、接口和旧实现迁移时怎么处理

如果旧代码使用自定义 multi-error，将实现迁移到 errors.Join 时，先确认三件事：原实现是否用逗号或分号连接文本、调用方是否依赖 Unwrap() error、接口层是否把整段文本当作稳定字段。最容易被忽略的是顺序和 nil 过滤：Join 按传入顺序保留非 nil 成员，不能把它当成无序集合。

迁移回归清单：四组边界要测

1. 所有参数都是 nil 时，结果应为 nil；只有一个非 nil 错误时，不应凭空多出空行。
2. 两个或多个成员时，确认展示顺序与传入顺序一致，并确认成员自身的换行会被保留。
3. 用 errors.Is 检查每个哨兵错误，用 errors.As 检查自定义类型，不要只比较 Error() 字符串。
4. 为日志和对外响应分别写测试：前者验证可读性，后者验证错误码、摘要和敏感信息边界。

常见问题

errors.Join 为什么不是用逗号连接？

因为标准库把每个子错误作为独立消息行处理，换行比逗号更容易在日志中分辨多个失败来源；这是 API 的既定格式。

能不能通过 strings.Replace 把换行改掉？

可以在展示层生成一份单行摘要，但不要修改原 error 的判断语义；优先保留原值给 Is/As，另算一个面向日志或响应的摘要。

errors.Join 适合替代所有错误返回吗？

不适合。只有多个错误都对调用方有价值时才聚合；如果一个根因已经足够说明失败，直接返回它通常更清晰。