在 Python 里保存 JSON 文件大概是每个写脚本的人都会碰到的操作。刚入门的时候三五行代码就能跑通看起来简单得不能再简单。可真到了实际项目里问题就来了中文存进去变成一串 \uXXXX别人打开文件直接骂人数据里有 datetime 和 Decimal执行到一半就报 not JSON serializable文件几个 GB一保存卡半天写到一半程序崩了整个文件直接损坏。这些坑我几乎都踩过而且越是看着简单的东西踩起来越疼。这篇文章我不打算只贴一段能运行的代码就完事而是把“Python 保存 JSON 文件”这件事从头到尾拆开讲清楚基本原理、常用 API、参数细节、复杂类型处理、大文件策略、原子写入、并发安全以及在服务器和容器环境下的落地经验。既适合刚学 Python 的初学者也适合项目里天天跟 JSON 打交道但偶尔还会被细节坑一下的开发者。看完之后不管是在本机调试脚本还是部署到云平台跑定时任务你都能少走弯路。1. 整体设计先想清楚“保存 JSON”这件事的本质1.1 JSON 在 Python 生态里的核心作用JSONJavaScript Object Notation严格来说只是 JavaScript 对象的序列化格式但因为结构简单、跨语言通用它早就成了程序间交换数据的“国际语言”。Python 的 dict 和 list 天然跟 JSON 的对象和数组结构完全对应所以 Python 项目里几乎处处能看到 JSON配置文件、API 请求返回、日志记录、临时数据落盘、爬虫结果保存、机器学习训练集的标注文件……长得都一个样。但“长得像 dict”和“能真正落盘再读回来”是两回事。Python 对象在内存里是一组带类型的结构体而 JSON 文件里是纯文本。把内存对象变成文本的过程叫序列化把文本还原成对象的过程叫反序列化。保存 JSON 文件本质就是在做一次序列化加落盘。搞清楚这一点你就知道为什么不是所有 Python 对象都能直接存成 JSON——因为 JSON 格式只规定了六种数据类型对象、数组、字符串、数字、布尔值和 null。凡是 JSON 里没有的类型比如 datetime、Decimal、set、bytes就需要你自己想办法否则标准库帮不了你。1.2 一次完整落盘的心智模型我习惯把一次保存拆成四个阶段构造内存数据 → 调用序列化接口 → 打开文件句柄 → 写入并关闭。很多人写代码时只关注第二步把前两步和后两步全混在一起出了错就很难定位。import json data {name: 测试任务, items: [1, 2, 3]} with open(output.json, w, encodingutf-8) as f: json.dump(data, f, ensure_asciiFalse, indent2)上面这段看起来一气呵成但里面其实藏了三个关键点。第一data 必须是“能序列化”的 Python 对象第二json.dump 接收的是一个文件对象 f它内部会调用 f.write所以 open 的模式必须带 w 或 a第三open 的 encoding 参数要显式指定 utf-8否则在 Windows 上默认是 gbk保存出来的文件可能乱码。这三个细节任何一个踩到都能让你折腾半天。1.3 方案选型什么时候用 json什么时候换更合适的格式虽然标题是“保存 JSON 全攻略”但我还是想先泼一盆冷水JSON 不是万能的有些场景它确实不合适。你要知道自己为什么选 JSON而不是无脑用。配置文件如果配置很复杂、层级很深JSON 可以。但它不支持注释写给人看的体验比较差YAML 或 TOML 会更好。日志记录JSON Lines每行一个 JSON 对象比一个大 JSON 数组更适合追加日志因为你可以一行一行读、一行一行处理。高性能序列化如果单条数据就有几十 MB或者对数据大小敏感可以考虑 MessagePack、Protobuf或者直接上压缩。跨语言交互只要对方能解析 JSON它就是最不容易出问题的选择。选型的基础逻辑并不复杂先确认跨语言互通和数据可读性是不是硬需求再考虑性能、体积、注释、流式处理等次要因素。对大多数场景来说JSON 依然是那个“稳妥的默认项”但你要知道它不神圣。2. 核心 API 拆解json.dump 和 json.dumps 的全参数解析2.1 dump 和 dumps 差别到底在哪很多初学者会把 json.dump 和 json.dumps 搞混。其实规则非常简单有 s 的返回字符串没有 s 的写入文件对象。json.dumps(obj)把 obj 序列化成一个 str返回给内存里的字符串变量。json.dump(obj, fp)把 obj 序列化后直接调用 fp.write 写入没有返回值。我见过有人把 dumps 的结果塞给 open(...).write这完全没问题也见过有人把 dump 的返回值赋给一个变量然后到处找文件纯属自己吓自己。实际项目里的取舍是如果你还要对序列化结果做二次处理比如压缩、加密、hash、再拼接那就用 dumps如果只是单纯落盘直接 dump 更干净少一步中间变量。2.2 格式化参数indent、ensure_ascii、sort_keys、separators这四个参数是“别人看你的 JSON 文件舒不舒服”的关键。indent 控制缩进。不指定时json.dump 输出的是压缩过的单行文本如果你是为了给机器读这没问题但如果你用文本编辑器打开想人工排查那必须加 indent2 或 indent4。注意 indent 传整数即可不建议传字符串因为传字符串会改变换行行为容易产生意外结果。ensure_ascii 是中文显示的关键。默认是 True意味着所有非 ASCII 字符都会被转义成 \uXXXX。为了节省空间这个设计在以前网络传输时很有用但在本地文件里会让人完全看不懂。保存配置文件、爬虫结果、标注数据时我几乎永远是 ensure_asciiFalse。sort_keys 决定是否按 key 排序输出。默认 False字典的键按插入顺序排列Python 3.7 以后 dict 保持插入顺序。如果你希望文件内容稳定、方便 diff 或者统一格式就设成 True。我写回归测试的基线文件时必开它否则两个版本的输出顺序一乱diff 就没法看。separators 控制分隔符。默认是 (, , : )也就是每个键值对之间会带逗号加空格冒号后面也加空格。想要压缩体积可以设成 (,, :)。要注意如果同时指定了 indentseparators 的默认值会受影响因为美化输出本身要依赖换行。实际项目中想压缩就直接压缩想美化就美化很少有人同时折腾这两个。看个完整例子import json payload { name: 订单同步, enabled: True, priority: 3, tags: [上报, 定时] } # 美化输出中文正常显示键排序 with open(config.json, w, encodingutf-8) as f: json.dump(payload, f, ensure_asciiFalse, indent2, sort_keysTrue) # 压缩输出适合程序间传输 compact json.dumps(payload, ensure_asciiFalse, separators(,, :)) print(compact) # {name:订单同步,enabled:true,priority:3,tags:[上报,定时]}这里有个小细节值得注意TB级日志和百KB配置文件使用的 format 哲学完全不一样。你要想清楚这个文件将来是谁在读。如果是人读indent 和 ensure_ascii 必须有如果是纯程序读压缩格式还能省一点读写时间。2.3 中文乱码根源不是 JSON是编码中文变成 \uXXXX 虽然丑但它不是乱码。乱码通常是你打开文件时编码和保存时不匹配导致的“锟斤拷”或“é”字样。真正的乱码根源是 open 函数没指定 encodingutf-8。不信你试试在不指定任何参数的情况下在 Windows 上运行with open(test.json, w) as f: json.dump({名字: 张三}, f, ensure_asciiFalse)很多情况下你会得到一个 GBK 编码的 JSON 文件。这个文件内容看起来可能是正常的但换到 Linux 服务器上Python 默认按 UTF-8 读取就会报 UnicodeDecodeError或者读到一堆不可见字符。所以我的习惯是所有涉及文本读写的 open只要不是 100% 确定是纯 ASCII一律显式传 encodingutf-8不要省这一步。2.4 自定义序列化default 参数和 JSONEncoder 子类标准 json 模块不会处理 datetime、Decimal、set、bytes。你一旦把它们放进字典然后 dump马上会得到 TypeError。解法就两种自己转换或者给 json 模块一个“翻译器”。第一种手动转。在构造数据的地方把 datetime 对象转成 isoformat 字符串把 Decimal 转成 float 或 str把 set 转成 list。简单直接但很容易漏一旦漏了就得回到代码里补齐。第二种写一个自定义的 encoder。这个比较稳因为它是集中处理的兜底逻辑import json from datetime import datetime, date from decimal import Decimal class CustomEncoder(json.JSONEncoder): def default(self, obj): if isinstance(obj, (datetime, date)): return obj.isoformat() if isinstance(obj, Decimal): return float(obj) if isinstance(obj, set): return list(obj) if isinstance(obj, bytes): return obj.decode(utf-8, errorsreplace) return super().default(obj) data { created_at: datetime.now(), price: Decimal(19.99), tags: {a, b}, blob: bhello } with open(complex.json, w, encodingutf-8) as f: json.dump(data, f, clsCustomEncoder, ensure_asciiFalse, indent2)个人建议如果项目里这种数据很多写得远远不止一处那一定要把 encoder 单独做成一个模块全局统一复用。不要让每个模块都各自写各自的 default否则你的 JSON 文件里会出现“同样是日期有的存成字符串有的存成时间戳”这种混乱情况。2.5 读回来的正确姿势虽然标题是“保存”但保存和读取是一对不提读取就是耍流氓。读出 JSON 有两个要点一是 load 和 loads 的使用方式要对应二是要处理“文件损坏后抛出异常”的情况。from pathlib import Path path Path(complex.json) # 方式一读文本再 loads raw_text path.read_text(encodingutf-8) obj json.loads(raw_text) # 方式二open 后直接 load with path.open(r, encodingutf-8) as f: obj json.load(f)生产环境里我建议读取的时候始终包一层 try。原因很简单外部文件随时可能因为程序崩溃、手工编辑、磁盘写入中断而变成非法 JSON。一个健壮的加载函数应该返回默认值或者抛出带上下文的业务异常而不应该让裸的 JSONDecodeError 直接冒到上层去。3. 实操过程从最普通到工程化的完整演练3.1 最常规的操作把内置数据结构存成文件入门级代码就不摆架子了直接给出一个完整可运行的例子涵盖字典、列表、嵌套结构、布尔值、Noneimport json from pathlib import Path def save_json(path: Path, data: dict) - None: path.parent.mkdir(parentsTrue, exist_okTrue) with path.open(w, encodingutf-8) as f: json.dump(data, f, ensure_asciiFalse, indent2) def load_json(path: Path) - dict: with path.open(r, encodingutf-8) as f: return json.load(f) if __name__ __main__: my_data { job_name: 数据清洗, schedule: {cron: 0 2 * * *, timezone: Asia/Shanghai}, params: {limit: 100, dry_run: False, tags: None}, items: [{id: 1, value: 0.618}, {id: 2, value: 3.14}], } save_json(Path(output.json), my_data) reloaded load_json(Path(output.json)) print(reloaded[job_name])注意那行 path.parent.mkdir。很多人保存文件时只管文件名忘了父目录可能不存在结果跑出 FileNotFoundError。加上这一行后一次性创建目录结构以后再也不用为这种小错误打断节奏。3.2 保存格式友好的结果缩进、排序、Unicode、行尾全搞定当一个 JSON 文件要被人反复打开查看时统一格式比什么都重要。下面这段代码就是我处理“给人看的配置文件”标准姿势import json import os def dump_pretty_json(obj, filepath): tmp_path filepath .tmp with open(tmp_path, w, encodingutf-8, newline\n) as f: json.dump(obj, f, ensure_asciiFalse, indent2, sort_keysTrue) f.write(\n) os.replace(tmp_path, filepath)这里面有三个细节值得说。第一newline\n 是强制统一换行符。Windows 默认行尾是 \r\nLinux 是 \n如果开发机和服务器混用git diff 会经常出现“整行变化”的假象。显式统一后跨平台协作干净得多。第二最后加一个换行符很多编辑器要求文件以换行结尾否则会在末尾显示一个奇怪的标记。第三通过临时文件 os.replace 实现原子写入这样文件不会出现写了一半的中间状态。这个方法推荐所有人尽快用起来。3.3 复杂类型保存日期、Decimal、Enum、嵌套对象实际业务里数据结构没书上那么干净。比如爬虫结果里带着发布时间结算单里带着 Decimal 金额权限模块里带着 Enum日志里带着 bytes。这些类型你要么在源头上转好要么统一兜底。先看一个不带第三方依赖只用 json 标准库的完整方案import json from datetime import datetime from decimal import Decimal from enum import Enum from pathlib import Path class Status(Enum): PENDING pending DONE done class MyEncoder(json.JSONEncoder): def default(self, obj): if isinstance(obj, datetime): return {__type__: datetime, value: obj.isoformat()} if isinstance(obj, Decimal): return float(obj) if isinstance(obj, Enum): return obj.value return super().default(obj) payload { created: datetime(2025, 5, 1, 12, 30, 0), price: Decimal(88.88), state: Status.DONE, nested: {updated: datetime(2025, 5, 2, 8, 0, 0)} } text json.dumps(payload, clsMyEncoder, ensure_asciiFalse, indent2) Path(complex.json).write_text(text, encodingutf-8)这里我把 datetime 转成带类型标记的字典好处是读取时能根据type还原回 datetime 对象坏处是格式不再“纯净”其他语言解析时可能不认识。如果你只是给 Python 项目自己用这种带类型标记的做法非常实用如果 JSON 要给别的系统消费那还是老老实实转成 isoformat 字符串更稳妥。关键是想清楚文件的“消费方”是谁再决定用哪种编码策略。3.4 不依赖第三方库流式写大文件一次只写一条记录如果文件很大常见做法是保存成一个数组。但这就有一个致命问题必须把所有数据全放进内存里再一次性 dump。数据量一上来内存先爆。更好的思路是改成 JSON Lines 格式——每行一个独立的 JSON 对象一边生成一边写。import json def append_json_line(filepath, record): with open(filepath, a, encodingutf-8) as f: f.write(json.dumps(record, ensure_asciiFalse) \n)追加写入非常舒服但代价是文件不再是严格的单个 JSON而是每行独立 JSON 的文本集合。读取时就按行读、逐行解析def read_json_lines(filepath): with open(filepath, r, encodingutf-8) as f: for line in f: line line.strip() if not line: continue yield json.loads(line) for record in read_json_lines(big.jsonl): print(record[id])这个模式在日志系统里非常常见比如云平台导出任务日志、爬虫抓取记录、埋点数据采集几乎都用 JSON Lines 而不是一个大 JSON。你要是有这种场景别犹豫直接用这个方案。3.5 原子写入防止保存到一半文件损坏程序崩溃、磁盘写满、断电都会导致文件写入中途停止。结果就是一个半截的 JSON 文件不仅后续读不了上一个版本还白丢了。解决办法是先写临时文件成功后再原子替换目标文件。import json import os import tempfile def atomic_write_json(obj, filepath): dir_name os.path.dirname(os.path.abspath(filepath)) fd, tmp_path tempfile.mkstemp(dirdir_name, suffix.tmp) try: with os.fdopen(fd, w, encodingutf-8) as f: json.dump(obj, f, ensure_asciiFalse, indent2) f.flush() os.fsync(f.fileno()) os.replace(tmp_path, filepath) except Exception: # 清理临时文件 if os.path.exists(tmp_path): os.remove(tmp_path) raise这里面有两次关键操作。f.flush() 是把 Python 缓冲区的数据推给操作系统os.fsync(f.fileno()) 是让操作系统把数据真实落到磁盘。只有这两步都完成你才能真正避免“程序说写完了重启后文件却没了”的尴尬。os.replace 在 Windows 和 Linux 上都是原子操作直接覆盖目标路径不会产生“删除旧文件再写新文件”的中间空档。3.6 并发场景多线程、多进程同时写同一个 JSON 怎么办先说结论并发写同一个文件如果流程是“先读旧数据→内存里改→写回整个文件”那不管用什么库都不可能安全因为你永远有“读改写”三明治竞态。解决办法有几个层级。最省事的是“串行化”在应用层用一个 Lock。多线程场景下最简单import threading write_lock threading.Lock() def safe_dump_json(obj, filepath): with write_lock: atomic_write_json(obj, filepath)Python 的多进程场景锁机制各自独立需要引入 multiprocessing.Lock或者用 filelock 这类第三方库加一个文件锁try: from filelock import FileLock except ImportError: pass # pip install filelock def process_safe_dump(obj, filepath): lock_path filepath .lock with FileLock(lock_path): with open(filepath, w, encodingutf-8) as f: json.dump(obj, f, ensure_asciiFalse, indent2)但说实话如果写入频率很高这种整体重写文件的方案永远不舒服。更实际的架构是把写文件的事件记录下来比如先写日志再异步批量更新 JSON或者干脆改成 JSON Lines 只追加不重写整个文件。我在做配置同步、任务状态持久化的时候都建议把“高频小更新”降级成“低频全量快照”这样能少掉一大半并发问题。4. 常见问题排查与避坑实录4.1 打开 JSON 看到 \uXXXX 怎么办最直接的原因是 ensure_ascii 默认值为 True。你把中文、日文、韩文、emoji 全部转成 \u 形式了。解决方案是保存时传 ensure_asciiFalse。如果你现在文件已经写出来了可以用下面方式快速“救回来”import json from pathlib import Path raw Path(old.json).read_text(encodingutf-8) data json.loads(raw) # 解析时 \uXXXX 会被还原成真实字符 Path(new.json).write_text( json.dumps(data, ensure_asciiFalse, indent2), encodingutf-8 )这里有个易错点json.loads 会自动把 \uXXXX 还原成真实 Unicode所以你直接读取再重新 dump就能修复历史文件。但如果你打开文件用的是普通文本编辑器看到的就是转义符用浏览器或带 JSON 高亮的工具看可能会显示成正常字符。所以第一步永远是先解析再决定要不要重写。4.2 TypeError: Object of type datetime is not JSON serializable这个报错是最常见的“类型不支持”问题。原因很简单datetime 不在 JSON 规范内。解决办法就三种看你场景选方案做法优点缺点手动转换在写前把 datetime 转为字符串逻辑明确无隐式行为容易漏代码分散自定义 Encoder用 cls 参数统一处理集中管理不易遗漏读取方需配合还原逻辑传 default 函数json.dump(data, f, defaultstr)一行代码兜底写起来最快所有未知类型都变成字符串可能产生逻辑陷阱我最不推荐无脑直接抄 defaultstr。因为一旦里面有 bytes、Decimal 等类型全转成字符串虽然不会报错但类型语义完全丢失读回来之后想再按数字处理就得自己再转容易埋雷。4.3 保存后读取报 FileNotFoundError 或 PermissionErrorFileNotFoundError 多半是父目录不存在。代码开头加 path.parent.mkdir(parentsTrue, exist_okTrue)问题就消失。PermissionError 的情况要复杂一些。常见原因是文件被其他进程打开占用Windows 上尤其频繁或者临时目录下你没有写权限。解决思路先确认路径所属目录的权限用 os.access 判断但不能完全依赖它写入使用临时文件再替换这样即使原文件被占用通常也只是替换失败而不会把原文件损坏。另外还有一个很容易踩的坑往容器里跑任务时工作目录你可能以为有权限实际上容器用户是 nobody宿主机的目录映射过来不可写。建议所有落地文件的路径都做成显式配置项并在启动时做一次“可写性自检”不要等到跑任务跑到一半才暴露。4.4 大 JSON 文件保存又慢又占内存很多人的“大 JSON”其实是普通的 dict只是嵌套层次多。对这种性能瓶颈主要在 json.dump 的纯 Python 序列化阶段。有几个优化方向字符串优化别在内存里拼长字符串。如果数据来自数据库直接流式读取生成 JSON Lines。压缩文件很大很好配 zlib 或 gzip 合适吗如果文件给磁盘用非常合适。批量落地多条记录先攒到一个 list达到阈值一次性 dump 到一个分片文件再用额外索引文件去管理。跑分如果单个文件已经超过 1GB老实说用纯 JSON 已经不是好选择了考虑 MessagePack、Parquet、ORC或者干脆去数仓。对于大多数中小型项目JSON 完全够用只有当你发现每次保存都要卡好几秒、打开文件要转圈才需要考虑换格式。4.5 程序崩溃导致 JSON 文件损坏保存中途崩溃确实防不胜防但可以靠“临时文件 原子替换”来规避。上一节讲到的 atomic_write_json 就是标准解法。如果文件已经损坏了想抢救数据可以按行处理来提取部分记录针对“一直是 JSON Lines”的文件通常能救回 90%。针对单一大 JSON几乎难救只能靠备份。所以我的经验是重要 JSON 文件必须配上多版本或者定时备份。比如输出到 output.json 的同时再存一份带时间戳的 output_20250501.json。这个习惯能让你在第二天发现文件坏了时有个后悔药。不要觉得麻烦真出问题的时候你会发现这行代码值千金。4.6 问题速查表现象可能原因解决方案中文变 \uXXXXensure_asciiTrue保存时传 ensure_asciiFalse中文变乱码open 未指定 encodingutf-8读写都显式加 encodingutf-8datetime 报错JSON 规范无此类型自定义 Encoder 或手动转字符串Decimal 报错JSON 规范无此类型转为 float 或 str文件不存在父目录不存在path.parent.mkdir文件写入失败权限不足或文件被占用检查权限、换目录、临时文件原子替换文件读不出来写入不完整临时文件os.replace 原子写入写入很慢数据量大、重复整文件重写改用 JSON Lines、分批写、压缩多进程同时写并发问题文件锁或改为追加写模式5. 扩展场景在云环境里怎么把 JSON 存得又稳又规整5.1 容器环境下必须注意的路径与持久化问题现在很多 Python 任务都跑在容器或云主机里保存 JSON 文件就多了一层约束。容器重启后文件系统默认就是临时的不挂载持久化卷你辛辛苦苦写进去的 JSON 随时可能消失。所以部署到云端之前一定要把输出路径设计成可配置的环境变量或命令行参数别写死成工作目录下的相对路径。我在部署这类任务时习惯在入口函数里先做一次根目录检查配置里指定的 data_dir 必须存在且可写否则直接报错退出而不是等任务跑到最后才崩溃。这能省下无数“为什么跑了半小时却没数据”的排查时间。5.2 日志落盘与对象存储的取舍云环境里还有个常见选择JSON 文件到底存本地磁盘还是直接推到对象存储。本地磁盘读写速度最快适合高频率小文件但一旦实例被回收、磁盘故障数据就没了。对象存储随时可读取、可跨实例共享但单次写入延迟比本地高不适合高频落地。合理方案是分两层实时数据先落到本地比如 JSON Lines 追加定时任务再把这些文件打包/合并后推送到对象存储并清理本地过期文件。我见过很多团队把频繁的中间结果也直接推 OSS成本高不说还慢。像这样本地存近热数据、云端存远冷数据明显更实在。如果是 HoRain 云这类典型的云平台我一般会建议用户把任务部署在支持持久化数据盘的实例上把 JSON 输出目录挂到数据盘根路径这样即使应用容器重建数据盘还在文件不丢。再把关键的配置 JSON 和报表 JSON 定期同步到对象存储保证整机的数据安全性。5.3 定时任务场景避免重复写入互相覆盖云主机上跑定时任务很常见每隔五分钟爬一次数据存成 JSON 文件。最容易出的问题是多个任务实例同时启动然后都往同一个文件里写。除了加锁更稳妥的办法是文件名带时间戳或批次号比如 data_20250501120000.json天然规避并发。文件多了以后还要配置清理策略按天建目录、按月保留写一个简单的定时清理脚本。这些运维细节本地开发时你几乎不会遇到但一旦放云端持续跑几个月一定会遇到。5.4 配置管理与版本化输入的落地经验除了程序生成的 JSON云环境里还经常需要维护一份“输入配置” JSON比如任务参数、模型参数、调度规则。这份文件既然要长期存在于云环境中就值得做版本化。最简单的做法是每次更新配置后先另存一个带日期的副本再更新主文件。另一个经验是配置文件的写入不带服务重启的话程序可能在“读到一半的配置”时运行。为了避免这个我经常把配置做成 JSON Lines 中带版本号和生效时间每次读的时候取最大生效版本。这样一边写一边读也不会出错。以上这些经验并不是什么高深的技术都是我在实际项目里摔过跟头之后总结出来的。你可以把它们直接套用到自己的脚本里先从小事改起比如把每次 open 都补上 encodingutf-8把重要的保存改成“临时文件 os.replace”把频繁更新的数据改为追加式的 JSON Lines。一步步来你写的“保存 JSON 文件”会越来越省心。等你哪天回头看自己几个月前写的代码大概率会庆幸当时多花了几分钟把这些坑都填了。