Python JSONDecodeError 的 lineno 和 colno 怎么映射到原文

调用 json.loads() 解析多行配置时，最容易误读的是 JSONDecodeError 的位置字段。结论先说：lineno 和 colno 是面向读者的行列坐标，都是从 1 开始；pos 才是 doc 这个原始字符串里的 0 起始字符索引。要把错误落到原文，先用 lineno - 1 取行，再用 colno - 1 取列。

排查 JSON 语法错误时，不要把 colno 直接当成 Python 下标。正确映射是：error.doc.splitlines()[error.lineno - 1][error.colno - 1]，同时保留 error.pos 做全局偏移核对。

先把五个定位字段分清楚

json.loads() 遇到非法 JSON 时抛出 json.JSONDecodeError。官方接口把它定义为 ValueError 的子类，并额外提供 msg、doc、pos、lineno 和 colno。其中 pos 指向解析失败的位置，lineno 和 colno 是这个位置所在的行、列。

多行 JSON 如何还原出错行和字符

下面故意在第二行的 "port": 8080 后少写一个逗号。诊断函数不重新解析，也不修改输入，只按异常对象携带的坐标还原现场。

import json

def show_json_error(text):
    try:
        return json.loads(text)
    except json.JSONDecodeError as error:
        # 行列坐标从 1 开始，转成 Python 下标时各减 1。
        lines = error.doc.splitlines()
        line_index = error.lineno - 1
        column_index = error.colno - 1
        bad_line = lines[line_index] if 0 

这里的核心不是把列号换算成某种“可视宽度”，而是保留原始行。对普通 ASCII JSON，column_index 可以直接定位字符串下标；如果输入含制表符或组合字符，终端显示宽度可能与 Python 字符串索引不同，此时应把原始行和列号一起展示，不要擅自把坐标改成屏幕像素位置。

pos、换行和 Unicode 字符的边界

pos 很适合写日志或做全局定位，因为它不依赖你如何切行。验证时可以用每行长度和换行符累加出同一个偏移：

def position_from_line_column(text, lineno, colno):
    # 只模拟常见的换行分隔，返回与原文字符串一致的 0 起始索引。
    lines = text.splitlines(keepends=True)
    return sum(len(line) for line in lines[:lineno - 1]) + colno - 1

这段换算要求输入仍是同一份 str。如果先把 \r\n 替换成 \n、先做 strip()，或者把 UTF-8 字节解码成另一份文本，重新计算的 pos 就可能和异常中的 pos 不同。正确做法是记录 error.doc，必要时同时记录原始字节和解码策略。

常见问题

colno 是从 0 开始吗？

不是。colno 是从 1 开始的列号，转换成 Python 字符串下标要减 1。

为什么错误箭头看起来指向下一行？

解析器报告的是它确认无法继续的位置，可能落在下一个 token 或文件末尾；它不一定就是缺失符号的前一个字符。应结合 msg、当前行和上一行一起读。

可以只用异常字符串里的 line、column 吗？

不建议。异常文本适合给人看，程序化诊断应使用结构化字段，尤其是 doc 和 pos。

把 lineno/colno 当作展示坐标，把 pos 当作原文偏移，再保留未改写的 doc，就能覆盖大多数 JSONDecodeError 定位场景。官方文档见 Python json 模块说明。