Go bytes.Buffer WriteByte 为什么总是返回 nil

调用 bytes.Buffer.WriteByte 后，err 一直是 nil 是正常行为。Go 官方文档明确规定：这个方法会把一个字节追加到缓冲区，返回的错误始终为 nil；保留 error 返回值，是为了让它和 bufio.Writer 的同名方法保持接口形状。

官方资料：https://pkg.go.dev/bytes#Buffer.WriteByte

因此，代码中可以保留统一的错误判断，但不要把 nil 理解成“写入动作没有发生”。真正需要关注的是输入到底是一个字节还是一个 Unicode 字符，以及缓冲区过大时的边界。

为什么这个 error 固定为 nil

bytes.Buffer 是内存中的可变字节缓冲区，不像文件或网络连接那样有底层设备返回写入错误。WriteByte 的职责只是扩展内部存储并追加一个 byte，所以正常返回路径没有可报告的 error。

它的签名仍然是 func (b *Buffer) WriteByte(c byte) error，原因在于 bufio.Writer 也提供同样形状的写入方法。调用方如果面向这类接口编程，就不必为内存缓冲和带 I/O 的写入器分别改一套控制流。

零值 Buffer 就可以直接追加字节

bytes.Buffer 的零值可以直接使用，不需要先调用构造函数。下面的示例把 ASCII 字符逐个追加，再读取完整内容。示例中的错误判断保留了统一写入接口所需的结构。

package main

import (
    "bytes"
    "fmt"
)

func main() {
    var buf bytes.Buffer // 零值 Buffer 已经可以接收写入
    for _, c := range []byte{'G', 'o', '!'} {
        if err := buf.WriteByte(c); err != nil {
            // bytes.Buffer.WriteByte 按契约返回 nil，统一接口仍保留判断
            panic(err)
        }
    }
    fmt.Println(buf.String()) // 读取尚未消费的缓冲内容
}

这里的 c 是单个字节，不是任意长度的字符串。对于 ASCII 字符，一个字符通常正好对应一个字节；遇到中文或其他多字节 UTF-8 字符时，不能把一个 rune 强行转换成一个 byte 期待得到完整字符。

单字节、字符和字符串应该怎样选

把输入类型先分清，通常比纠结 error 更重要。下面这张表给出最小选择边界：

例如要追加中文字符，应使用 WriteRune，因为它会按 UTF-8 编码写入对应的多个字节：

var buf bytes.Buffer

if _, err := buf.WriteRune('中'); err != nil {
    // WriteRune 的 error 也按统一接口保留，便于替换写入目标
    panic(err)
}
fmt.Println(buf.String()) // 读取完整的 UTF-8 字符

真正需要留意的容量边界

“error 总是 nil”只描述正常方法契约，不代表所有异常都会通过 error 返回。官方文档说明，缓冲区变得过大时，WriteByte 会因 ErrTooLarge 触发 panic，而不是返回一个非 nil error。

这意味着两件事：第一，不要为了等待非 nil error 而写一套永远不会触发的分支；第二，如果数据规模可能失控，应在进入缓冲区之前限制输入大小，或改用流式写入，避免把无限增长的内容全部积在内存里。

另外，WriteByte 会改变 Buffer 的内容状态。写入后再调用 ReadByte、Next 或 Read，读取位置会继续向前推进；如果需要保留当前内容用于后续判断，可在修改前使用 Bytes 或 String 获取视图/副本语义，并按文档要求安排调用顺序。

几个容易混淆的问题

WriteByte 返回 nil，是否可以完全不写错误判断？

如果变量的静态类型就是 *bytes.Buffer，可以确认该方法按契约返回 nil；但保留判断通常更利于以后替换为 bufio.Writer 或其他写入器。是否省略判断，应由调用层的接口设计决定。

写入中文为什么不能循环调用一次 WriteByte？

中文字符在 UTF-8 中通常由多个字节组成。逐字节追加并非错误，但需要先得到完整 UTF-8 编码；直接把字符值转换成一个 byte 会丢失信息。面向字符时优先使用 WriteRune。

需要检查写入了多少字节怎么办？

WriteByte 本身只返回 error，不返回数量，因为每次目标就是一个字节。要统计一段数据的写入量，应使用 Write、WriteString 或 WriteRune 返回的数量。

结论

bytes.Buffer.WriteByte 的 error 固定为 nil，是明确的 API 契约，不是错误遗漏。它保留 error 是为了与 bufio.Writer.WriteByte 兼容；使用时应把注意力放到 byte 与 rune 的区别、写入方法的输入类型，以及缓冲区过大时的 panic 边界。