Go JSON Decoder 怎样报告出错字节偏移

Go 的 JSON Decoder 遇到语法错误时，应先用 errors.As 提取 *json.SyntaxError，读取它的 Offset；不要把 dec.InputOffset() 当成错误字符的位置。后者报告解码器当前位置，适合记录进度，但不是通用的报错定位接口。

假设我正在给一个配置导入入口补错误提示，我会把“哪里坏了”和“解码器停在哪”存成两个字段。这是我的接口取舍：宁可明确说明无法获得精确坏字节，也不拿一个看似精确的进度数字误导用户。下面是构造输入示例，不是线上故障记录或本机实测报告。

Go 官方标准库文档：https://pkg.go.dev/encoding/json

为什么 InputOffset 不是语法错误位置

SyntaxError.Offset 描述报告错误时已经读过多少字节。对于普通 Decode 扫描到非法字符的情况，Offset 常可理解为从 1 起算的该字符字节位置。InputOffset 表示最近返回 token 的末尾与下一个 token 的开头之间的当前位置。它们的名字都含 offset，却回答不同的问题。

一个容易不适应的地方是：Decode 可能在尚未接受完整值时就失败，当前位置不一定推进到出错字符。因此，首次 Decode 报语法错误时，即使 InputOffset 仍为 0，也不能据此判断错误在文件开头。反过来，解码成功后的位置也不代表底层 Reader 没有读过更多数据。

怎样从 Decode 的 error 中取得 Offset

我的最小写法是先分错误类型，不从 err.Error() 里截数字。errors.As 还可以穿透实现了 Unwrap 的包装错误，避免调用层增加上下文后，原本的类型断言失效。下面完整程序只对一个输入执行一次 Decode，目的是把报告字段分开。

package main

import (
    "encoding/json"
    "errors"
    "fmt"
    "io"
    "strings"
)

// describe 针对一次 Decode，保留原始输入的字节坐标。
func describe(src string) {
    dec := json.NewDecoder(strings.NewReader(src))
    before := dec.InputOffset()
    var value any
    err := dec.Decode(&value)
    if err == nil {
        fmt.Printf("解码成功，结束字节位置=%d\n", dec.InputOffset())
        return
    }

    var syntaxErr *json.SyntaxError
    switch {
    case errors.As(err, &syntaxErr):
        // 不解析错误文案；Offset 表示报告错误时已读过的字节数。
        fmt.Printf("JSON 语法错误，Offset=%d，原因=%v\n",
            syntaxErr.Offset, err)
    case errors.Is(err, io.ErrUnexpectedEOF):
        // 截断输入没有 SyntaxError.Offset，不伪造坏字符位置。
        fmt.Println("JSON 输入未完成：", err)
    case errors.Is(err, io.EOF):
        fmt.Println("没有可解码的 JSON 值")
    default:
        // 类型错误、自定义解码错误及底层 I/O 错误另行分类。
        fmt.Println("其他解码错误：", err)
    }
    fmt.Printf("Decode 前位置=%d，失败后当前位置=%d\n",
        before, dec.InputOffset())
}

func main() {
    // 第一个输入完整但语法有误，第二个在值尚未结束时被截断。
    describe("{\"城市\":\"杭州\",\"数量\":!}")
    describe("{\"数量\":")
}

第一个构造输入中的感叹号不能作为 JSON 值，应走语法错误分支；第二个输入缺少值和结束符，应按未完成输入处理。这里不给出伪造的运行日志。读者使用自己的输入时，应观察错误类别与位置字段的语义，而不是比较两种 offset 是否数值相同。

不要在所有错误分支都输出“第 N 个字符错误”。类型不匹配可能对应 UnmarshalTypeError；自定义 UnmarshalJSON 还可以返回业务定义的错误。只有确实取得带坐标的错误，才把坐标标成精确字段，其余分支保留原因和必要上下文。

中文 JSON 的偏移为什么比看到的字符数大

字节位置不是 Unicode 字符数量。示例含“城市”“杭州”等中文，在 UTF-8 中会占用多个字节；JSON 文本里的转义形式也按原始输入字节计算，而不是按解码后的字符串计算。定位时必须保留送给 Decoder 的原始字节，不能先格式化、替换换行、反转义或重新编码，再套用旧坐标。

如果只需要行号和字节列，可以使用下面的辅助函数。它适用于已确认是原始输入中某一坏字节的 Offset，不用于把 InputOffset 或 EOF 位置强行变成错误字符。将它放在前一个程序的 main 函数之外即可使用。

// byteLineColumn 只接受原始数据内、从 1 起算的坏字节位置。
// 返回的列是字节列，不是屏幕显示列；换行按 LF 处理。
func byteLineColumn(src []byte, offset int64) (line, column int, ok bool) {
    if offset  int64(len(src)) {
        return 0, 0, false
    }
    index := int(offset - 1)
    line, column = 1, 1
    for _, b := range src[:index] {
        if b == '\n' {
            line, column = line+1, 1
        } else {
            column++
        }
    }
    return line, column, true
}

这段代码刻意把结果命名为“字节列”。如果要显示字符列，应在确定字节边界后，再对所在行前缀计算 rune；制表符、组合字符和全角字符的视觉宽度还需要单独约定。我倾向于在导入错误报告中保留原始字节偏移，并补充行号，而不是承诺与任意编辑器光标列完全一致。

截断输入、Reader 预读和连续 JSON 值要注意什么

输入被截断：io.ErrUnexpectedEOF 不携带 SyntaxError.Offset。一个尚未完成的对象未必存在“非法字符”，它可能只是缺少后续内容。若应用保留了完整输入，可以说“输入结束时 JSON 尚未完成”，不能伪称末尾字符一定错误；空输入或只有空白时的 io.EOF 又应与此区分。

Reader 有预读：Decoder 自带缓冲，可能从 Reader 取得超出当前 JSON 值的数据。包装 Reader 统计的字节数、文件当前位置和 InputOffset 不必相等。需要读取 Decoder 已缓冲的剩余内容时有 Buffered 接口，但它不是补算报错位置的公式。

同一 Decoder 解多个值：保留 Decode 前后的位置以及记录序号，日志中明确是哪个 Decoder 输入流。不要看见 SyntaxError.Offset 就再无条件加上 Decode 前的 InputOffset；也不要把所有其他错误类型的 Offset 当成相同坐标体系。若应用逐行切片后分别创建 Decoder，偏移属于各自的输入切片；要显示文件位置，应由应用保存切片起点再转换，而不是猜测。

自定义解码内部还有 JSON：如果 UnmarshalJSON 内部另建了解码器，内部返回的坐标可能只针对那个局部输入。错误包装层应该同时写清上下文，不能只在最外层留下一个没有参照系的数字。

几个定位时常见的追问

Offset 减 1 就一定是坏字符下标吗

对普通 Decode 扫描非法字符、且 Offset 确实指向原始数据内字节时，减 1 可换成从 0 起算的下标；先检查范围。不要把这个规则不加区分地套在 Token 状态错误、截断输入或自定义解码器错误上。

失败后能继续 Decode 来自动跳过坏对象吗

不要把它作为恢复协议。若必须跳过坏记录，应先由外部记录分隔或长度边界确定下一条输入，再建立新的解码上下文；本文的错误提示代码不负责恢复损坏的任意 JSON 流。

需要把出错附近的原文打进日志吗

通常先记录错误类型、字节位置和记录编号。若确实需要片段，应限制长度并脱敏，避免把密码或个人信息写入日志。对我来说，错误提示的价值是坐标可解释，而不是把整份输入复制一遍。

归纳起来：SyntaxError.Offset 用来解释语法错误，InputOffset 用来解释解码器位置，原始字节用来做坐标转换。把三者分开命名，报错信息才不会精确到一个错误的地方。

官方实现参考：https://go.dev/src/encoding/json/stream.go；https://go.dev/src/encoding/json/scanner.go