json_repair

April 17, 2026 · View on GitHub

本文档由 AI 翻译，如有疏漏欢迎指正。

这个 Python 工具包可以修复来自 LLM、API、日志和人工编辑输入中的损坏 JSON。

可修复缺失引号、逗号、括号、注释、夹杂说明文字和被截断的值。
既可以作为 json.loads() 的兜底解析器，也可以配合 schema 做引导修复。
可直接安装 pip install json-repair，也可以先试用在线演示。

快速示例

import json_repair

bad_json = '{"users":[{"name":"Ada","role":"admin",}],"ok":tru'
decoded_object = json_repair.loads(bad_json)

# {'users': [{'name': 'Ada', 'role': 'admin'}], 'ok': True}

如果 json_repair 帮你省下了调试时间，欢迎给仓库点个 Star：https://github.com/mangiucugna/json_repair

如果这个项目帮到你了

最简单的支持方式：给仓库点个 Star，让更多人能搜到它。
如果身边有人也在处理大模型或脏数据 JSON，把仓库或在线演示链接发给他们。
如果你遇到了修不好的样例，欢迎在 GitHub 提 Issue 并附上最小复现输入。
如果你的团队在生产环境长期使用它，再考虑通过 Sponsors 支持维护会更自然。

高级赞助商

Icana-AI —— CallCoach（全球领先的呼叫中心 AI 教练）的开发者。访问 https://www.icana.ai/
mjharte

演示

中文提示的在线演示（GitHub Pages）：https://mangiucugna.github.io/json_repair/index.zh.html
英文演示：https://mangiucugna.github.io/json_repair/
Google NotebookLM 英文音频介绍：https://notebooklm.google.com/notebook/05312bb3-f6f3-4e49-a99b-bd51db64520b/audio

想支持这个项目？

这个库免费且由作者业余维护。如果它帮到了你的工作，欢迎在 GitHub Sponsors 支持：https://github.com/sponsors/mangiucugna

动机

许多大模型输出的 JSON 并不规范：有时缺一个括号，有时多出文本。幸运的是，大部分错误足够简单，可以在不破坏内容的情况下修复。找不到一个轻量、可靠的 Python 包能处理这些问题，于是就写了 json_repair。

支持的用例

修复 JSON 语法错误

缺失引号、逗号错误、未转义字符、不完整的键值对。
布尔/空值写错（true/false/null），修复损坏的键值结构。

修复损坏的数组和对象

补全/修复未完成的数组或对象，添加必要的元素（逗号、括号）或默认值（null、""）。
清理包含额外非 JSON 字符（如注释、杂项文本）的字符串，尽量保持结构。

自动补全缺失值

自动为缺失的字段补充合理默认值（如空字符串或 null），保证可解析。

如何使用

安装：

pip install json-repair

基础用法：

from json_repair import repair_json

good_json_string = repair_json(bad_json_string)
# 如果输入极度损坏，可能返回空字符串

替代 json.loads()：

import json_repair

decoded_object = json_repair.loads(json_string)
# 或者
decoded_object = json_repair.repair_json(json_string, return_objects=True)

避免反模式

有些用户会先手动调用一次 json.loads()，失败后再回退到 json_repair。这通常是重复工作，因为 json_repair 默认就会先做一次严格的 json.loads() / json.load() 检查。它的正常流程是：

先尝试标准库 json.loads() / json.load()
如果成功，直接返回解析结果
如果失败，再进入修复解析器

默认推荐直接这样调用：

import json_repair

obj = json_repair.loads(json_string)

只有在你明确想跳过这一步验证时，才使用 skip_json_loads=True。

如果确定输入损坏，直接传 skip_json_loads=True：

obj = repair_json(bad_json_string, skip_json_loads=True)

从文件读取

json_repair 也提供 json.load() 的替代：

from json_repair import load, from_file

decoded_object = load(open(fname, "rb"))
decoded_object = from_file(fname)

I/O 异常不会被库捕获，需要由调用方处理。

非拉丁字符

处理中文/日文/韩文等时，传入 ensure_ascii=False 保留原文：

repair_json("{'test_chinese_ascii':'统一码'}", ensure_ascii=False)

透传 json.dumps 参数

repair_json 支持并透传 json.dumps 的参数（如 indent）。

性能提示

默认情况下，json_repair 会先尝试标准库 JSON 解析，只有严格解析失败时才会进入修复解析器。
如果你已经确定输入不是有效 JSON，可以传 skip_json_loads=True，直接跳过这一步验证。
return_objects=True 更快，因为直接返回对象。
skip_json_loads=True 只适合你 100% 确定输入不是有效 JSON 的场景。
如有转义问题，传入原始字符串（如 r"string with escaping\""）。

这是一个明确的取舍：

默认行为：先走标准库 JSON 校验路径，失败后再修复
skip_json_loads=True：直接跳过校验路径，进入修复解析器

json_repair 故意保持标准库 JSON 作为默认验证路径，不会自动探测或切换到第三方 JSON 库。这样可以避免常见路径上的额外开销，也能让行为更可预测。

什么时候自己使用其他 JSON 库

如果你需要标准库之外的 JSON 语义，或者想自己控制性能取舍，请显式使用你偏好的 JSON 库，而不是期待 json_repair 自动切换解析器。很多人会问到 orjson，它也是同样的用法。

推荐模式：

严格 JSON 优先，只有失败时才修复：

import json_repair

obj = json_repair.loads(json_string)

已知输入损坏，直接跳过验证：

from json_repair import repair_json

obj = repair_json(bad_json_string, return_objects=True, skip_json_loads=True)

先用 orjson，失败后再回退到 json_repair：

import json_repair
import orjson

try:
    obj = orjson.loads(json_string)
except orjson.JSONDecodeError:
    obj = json_repair.loads(json_string, skip_json_loads=True)

严格模式

默认尽量修复；若需要严格校验而非修复，可传 strict=True：

from json_repair import repair_json
repair_json(bad_json_string, strict=True)

严格模式会在发现结构问题（重复键、缺少冒号、空键/值、多个顶层元素等）时立刻抛出 ValueError。CLI 也支持 json_repair --strict input.json。

严格模式可与 skip_json_loads=True 组合：跳过初始 json.loads 检查，但仍执行严格解析规则。

Schema 引导修复

Schema 引导修复目前处于 beta 阶段，仍可能出现 bug。

可使用 JSON Schema（或 Pydantic v2 模型）指导修复。开启后解析器会：

补齐缺失值（默认值、必填字段）
在安全范围内做类型转换（例如 "1" → 1，布尔支持 "yes"/"no"/1/0）
移除 schema 明确禁止的字段/数组项

可通过 schema_repair_mode 选择模式：

standard（默认）：当前 schema 引导行为。
salvage：包含 standard，并额外启用：
- 数组项无法修复时按项丢弃（而不是整体失败）；
- 当 schema 结构明确时，按属性顺序把数组映射为对象。
- 当根 schema 期望对象且输入为单元素对象数组时，可在根节点解包（[{...}] -> {...}）；
- 仅在可安全推断时补齐缺失必填字段（default、const、首个 enum，或在约束允许时补空数组/空对象）。

适用于需要稳定、可验证输出（下游校验、落库、类型化处理等）的场景。若无法修复到满足 schema，将抛出 ValueError。

安装可选依赖：

pip install 'json-repair[schema]'

（CLI 可用 pipx install 'json-repair[schema]'。）

注意：只要传了 schema，无论输入 JSON 本身是否有效，都会执行 schema 引导。Schema 与 strict=True 互斥。

from json_repair import repair_json

schema = {
    "type": "object",
    "properties": {"value": {"type": "integer"}},
    "required": ["value"],
}

repair_json('{"value": "1"}', schema=schema, return_objects=True)

repair_json(
    '{"items":[{"id":1,"score":85.6},{"id":2,"score":"N/A"}]}',
    schema={
        "type": "object",
        "properties": {
            "items": {
                "type": "array",
                "items": {
                    "type": "object",
                    "properties": {"id": {"type": "integer"}, "score": {"type": "number"}},
                    "required": ["id", "score"],
                },
            }
        },
        "required": ["items"],
    },
    schema_repair_mode="salvage",
    return_objects=True,
)

Pydantic v2 模型示例：

from pydantic import BaseModel, Field
from json_repair import repair_json


class Payload(BaseModel):
    value: int
    tags: list[str] = Field(default_factory=list)


repair_json(
    '{"value": "1", "tags": }',
    schema=Payload,
    skip_json_loads=True,
    return_objects=True,
)

流式处理

需要在流式数据上修复 JSON 时，可传 stream_stable=True：

stream_output = repair_json(stream_input, stream_stable=True)

CLI 使用

安装命令行工具：

pipx install json-repair

查看选项：

$ json_repair -h
usage: json_repair [-h] [-i] [-o TARGET] [--ensure_ascii] [--indent INDENT]
                   [--skip-json-loads] [--schema SCHEMA] [--schema-model MODEL]
                   [--strict] [--schema-repair-mode {standard,salvage}] [filename]

Repair and parse JSON files.

positional arguments:
  filename              The JSON file to repair (if omitted, reads from stdin)

options:
  -h, --help            show this help message and exit
  -i, --inline          Replace the file inline instead of returning the output to stdout
  -o TARGET, --output TARGET
                        If specified, the output will be written to TARGET filename instead of stdout
  --ensure_ascii        Pass ensure_ascii=True to json.dumps()
  --indent INDENT       Number of spaces for indentation (Default 2)
  --skip-json-loads     Skip initial json.loads validation
  --schema SCHEMA       Path to a JSON Schema file that guides repairs
  --schema-model MODEL  Pydantic v2 model in 'module:ClassName' form that guides repairs
  --strict              Raise on duplicate keys, missing separators, empty keys/values, and similar structural issues instead of repairing them
  --schema-repair-mode {standard,salvage}
                        Schema 修复模式：standard（默认）或 salvage（尽力返回可用数组/对象）

在 requirements 中依赖

请只固定大版本号！
采用严格语义化版本与 TDD，次版本/补丁版本不会引入破坏性更新，更新频繁。建议在 requirements.txt 里使用：

json_repair==0.*

如何引用

如果你在学术工作中使用了本库，BibTex 如下：

@software{Baccianella_JSON_Repair_-_2025,
    author  = "Stefano {Baccianella}",
    month   = "feb",
    title   = "JSON Repair - A python module to repair invalid JSON, commonly used to parse the output of LLMs",
    url     = "https://github.com/mangiucugna/json_repair",
    version = "0.39.1",
    year    = 2025
}

欢迎引用并分享论文链接！

工作原理

模块按照 BNF 解析 JSON，并在发现问题时使用启发式修复：

<json> ::= <primitive> | <container>

<primitive> ::= <number> | <string> | <boolean>
; 其中:
; <number> 是合法的实数
; <string> 是用引号包裹的字符串
; <boolean> 为 'true' / 'false' / 'null'

<container> ::= <object> | <array>
<array> ::= '[' [ <json> *(', ' <json>) ] ']'
<object> ::= '{' [ <member> *(', ' <member>) ] '}'
<member> ::= <string> ': ' <json>

若解析出错（如缺少括号或引号），将尝试：

补充缺失的括号/大括号。
为字符串补引号或补单引号。
调整空白并移除多余换行。

如有遗漏的边界情况，欢迎提交 Issue 或 PR。

贡献

想要参与贡献，请先阅读 CONTRIBUTING.md，再浏览 Code Wiki 的代码库导览与入口说明：https://codewiki.google/github.com/mangiucugna/json_repair

开发指南

使用 uv 配置开发环境并运行工具：

uv sync --group dev
uv run pre-commit run --all-files
uv run pytest

提交后请确认 GitHub Actions 通过。

发布指南

需要仓库 owner 权限：

修改 pyproject.toml，按照 semver 更新版本。
先提交并推送所有改动，否则后续步骤会失败。
运行 python -m build。
在 GitHub 创建 Release，标记已解决的 Issue 与贡献者，Tag 与版本一致。
Release 创建后会触发 GitHub Actions 发布到 PyPI，确认任务通过。

文档演示 API 部署（PythonAnywhere）

文档站点由 GitHub Pages 工作流 pages-build-deployment 发布。
当 main 上 Pages 发布成功后，.github/workflows/pythonanywhere-sync.yml 会把 docs/app.py 上传到 PythonAnywhere 的 /home/mangiucugna/json_repair/app.py，并重载 mangiucugna.pythonanywhere.com。
需要仓库 Actions 密钥：PythonAnywhere API token（PYTHONANYWHERE_API_TOKEN）。

其他语言的 JSON 修复

Typescript: https://github.com/josdejong/jsonrepair
Go: https://github.com/RealAlexandreAI/json-repair
Ruby: https://github.com/sashazykov/json-repair-rb
Rust: https://github.com/oramasearch/llm_json
R: https://github.com/cgxjdzz/jsonRepair
Java: https://github.com/du00cs/json-repairj