Go json.SyntaxError Offset 怎样找到 JSON 语法错误位置

Go 解析 JSON 失败时，json.SyntaxError.Offset 给出的不是“第几列”，而是解析器读过的字节数。把它转换成原始输入的零基索引后，就能截取错误附近的上下文；如果要展示给用户，再按 UTF-8 和换行规则换算行号、列号。

官方文档：https://pkg.go.dev/encoding/json#SyntaxError

下面的示例只讨论语法错误定位。类型字段不匹配应看 json.UnmarshalTypeError，流式读取器的当前位置则要看 Decoder.InputOffset，不要把几种 Offset 混在一起。

SyntaxError.Offset 到底指向哪里

SyntaxError 描述的是 JSON 语法无法解析的情况，Offset 的官方定义是“发生错误前已经读取的字节数”。因此把它用于切片时要先减一：Offset 为 1 表示第一个字节之后出现问题，对应的零基索引通常是 0。

它不是字符下标，也不保证正好落在“罪魁字符”的开头。解析器可能在读到后续字节、遇到意外结束或确认结构不完整后才报错。工程上更稳妥的做法是把它当作定位锚点，展示一个有限的前后文窗口。

用 error.As 截取错误附近的 JSON

不要用字符串匹配判断错误类型。通过 errors.As 取出 *json.SyntaxError，再把 Offset 转成窗口起点和终点。下面的辅助函数保留原始字节，不会因为中文或 emoji 占用多个字节而把索引切坏。

package main

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

// syntaxContext 返回语法错误附近的原始字节窗口和零基位置。
func syntaxContext(data []byte, err error, radius int) ([]byte, int64, bool) {
    var syntaxErr *json.SyntaxError
    if !errors.As(err, &syntaxErr) {
        // 类型错误、IO 错误等不属于 JSON 语法定位范围。
        return nil, 0, false
    }
    if radius  int64(len(data)) {
        index = int64(len(data))
    }

    start := index - int64(radius)
    if start  int64(len(data)) {
        end = int64(len(data))
    }
    return data[start:end], index, true
}

func main() {
    data := []byte(`{"name":"Go", "items":[1, 2,]}`)
    var value any
    err := json.Unmarshal(data, &value)
    if err == nil {
        return
    }

    context, index, ok := syntaxContext(data, err, 8)
    if ok {
        // %q 让不可见空白和引号在日志中保持可辨认。
        fmt.Printf("index=%d context=%q\n", index, context)
    }
}

这里的 index 只是定位锚点，不能承诺就是唯一错误字符。窗口的大小应受控，避免把整份请求体写入日志；生产环境还要根据日志脱敏规则处理可能包含的账号、令牌或个人数据。

从字节位置换算成行号和列号

如果错误信息要回传给编辑器或接口调用方，可以在原始 []byte 上统计位置。行号通常从 1 开始；列号可以按 UTF-8 字符数统计，而不是直接拿字节差作为列号。

package main

import "unicode/utf8"

// bytePosition 把零基字节索引换算成 1 基行列。
func bytePosition(data []byte, index int64) (line, column int) {
    if index  int64(len(data)) {
        index = int64(len(data))
    }

    line, column = 1, 1
    for i := int64(0); i  index {
            width = 1
        }
        column++
        i += int64(width)
    }
    return line, column
}

这个换算函数的重点是：切片边界始终使用字节索引，列号才按 UTF-8 字符推进。若项目把制表符显示为多个屏幕空格，列号还应明确采用“逻辑字符列”还是“渲染列”，不要让客户端各自猜。

别把三种错误位置混为一谈

尤其是使用 json.Decoder 时，解码器会自行缓冲输入，底层 Reader 的读取进度不等于 JSON 值的逻辑边界。要定位语法错误，先从具体错误对象取 Offset；要记录流式 token 边界，再使用 InputOffset。

常见问题

Offset 为 0 时应该怎么截取？

把它钳制到 0，窗口从输入开头开始。异常结束等情况可能没有一个可直接标记的字符，前后文只能帮助判断缺失的结构。

能不能直接把 Offset 当作字符串下标？

不能。JSON 输入通常是 UTF-8 字节，中文、emoji 等字符可能占多个字节。先在 []byte 上切片，再按需要换算字符列。

为什么错误附近不一定就是错误字符？

解析器可能要读到后续字节才能确认结构不合法，所以 Offset 是解析进度锚点。展示窗口并结合错误文本、括号层级和上游输入共同判断。

小结：用 errors.As 取得 *json.SyntaxError，将 Offset-1 作为零基锚点，在字节层面安全截取有限窗口；只有面向用户展示时，才进一步换算 UTF-8 行列，并根据错误类型选择对应的定位字段。