在 Python 生态里混了一阵子之后我发现自己其实一直把一个最常见的文件类型当“黑盒”在用——.ipynb。每天在 Jupyter 里写代码、跑实验、画图、保存却从来没认真想过这个文件内部到底长什么样。直到有几次分支合并时被一串串不可读的 diff 整得焦头烂额才开始静下心来把这个格式彻底拆了一遍。这篇文章就把我对.ipynb文件的认识从头捋一遍包括它的结构、它在工程协作里为什么这么闹心、日常使用效率极高的几个操作方式以及文件损坏和体积膨胀时的处理思路。如果你也写过 notebook、被 Git 冲突折磨过、或者只是好奇这文件里到底存了什么那这篇值得看完。1. 先搞清楚 .ipynb 到底是个什么JSON 皮囊 交互式内脏很多人以为.ipynb是某种专属二进制格式其实完全不是。它就是一个标准的 JSON 文件只是文件后缀换成了.ipynb全称是 iPython Notebook但现在基本泛指 Jupyter Notebook。这意味着你用任何文本编辑器打开它都能直接看到里面的文字内容没有任何加密和混淆。也正因为它基于 JSONPython、R、Julia 甚至 JavaScript 都有现成的解析库跨语言交换非常方便。一个最简单不过的 notebook 文件结构大概是这样的{ cells: [ { cell_type: code, execution_count: 1, metadata: {}, outputs: [ { name: stdout, output_type: stream, text: hello world\n } ], source: [ print(hello world) ] } ], metadata: { kernelspec: { display_name: Python 3, language: python, name: python3 }, language_info: { name: python, version: 3.11.0 } }, nbformat: 4, nbformat_minor: 4 }粗看这个结构顶层就是三块cells、metadata、nbformat。其中nbformat是格式规范的版本号目前主流是 4不同小版本之间有一些字段上的兼容差异。metadata是文件的元信息保存了内核种类、Python 版本、语言信息等。而cells才是真正承载内容的骨架是一个数组里面每一元素就是一个单元。1.1 code cell 里的四件套source、execution_count、outputs、metadata在.ipynb文件里最关键的还是 code cell。每个 code cell 都有四个主要字段source单元格里的源码一般以字符串数组的形式存在每个数组元素对应一行方便解析器的逐行处理。如果你用程序读取常常需要.join(cell[source])才能拿到完整源码。execution_count这个 cell 最近一次执行的编号。注意是“最近一次执行”不是执行次数。只要你在 notebook 里按一次运行它就会变一次。这个字段是 Git 冲突的常客。outputs执行之后的结果列表。包括纯文本输出、图片 base64、富文本 HTML 等等。典型类型有stream、execute_result、display_data、error等。这个也是导致文件体积膨胀和版本冲突的大头。metadata记录当前 cell 的局部元信息比如是否折叠代码、标签等大多数场景下是空对象。不同 cell 的metadata内容不一定一样比如 markdown cell 可以带tags字段code cell 还可以带collapsed这类 UI 状态。保存这些东西对于用户复现交互状态很有帮助但对于只有代码本身有意义的项目来说又显得多余。1.2 markdown cell 与 raw cell 的区别和应用除了 code cell文件里还经常会看到markdown和raw两种类型的 cell。markdown cell 的source里存的是带#、-等排版的 Markdown 文本用于写说明、标题、公式。它没有outputs和execution_count。很多人在做技术分享时喜欢把README内容直接写成 notebook 的 markdown cell好处是代码和文档共存于一个文件评审的时候可以直接看到上下文。raw cell 则更特殊一点它里面的内容不会被执行也不会被渲染只用于存放你需要“原样保留”的文本比如 LaTeX 源码片段或者某些特定格式的开头。平时我们很少主动创建 raw cell但接触nbconvert这类工具时会遇到它。从本质上讲.ipynb保存的不仅仅是代码还保存了“执行后”的整个世界。source是输入outputs是输出metadata是环境线索整份文件就是一个可以再次打开的完整会话记录。这也是它和纯.py文件最大的差别:.py只有逻辑.ipynb还有故事。2. 为什么 .ipynb 在 Git 里会变成“冲突之王”输出、计数器与元数据的锅如果你和我一样曾经在一个稍微上点规模的项目里把.ipynb提交进了 Git大概率会经历过这种场景两个人各自运行过同一个 notebook然后各自提交各自的分支等到 merge 的时候Git 会直接宣告这个文件冲突而且 diff 里夹杂着一大堆你根本不想看的 base64 图片数据、执行计数和元数据变化。问题不在于 Git而在于.ipynb的默认保存策略太“重”。我们来看几个最容易导致冲突的因素execution_count每次执行都会递增哪怕代码一行没改只要跑过一次文件就变了。outputs里保存了大量输出结果图片转成 base64 后字符串长度吓人任何二次执行都会让输出对象变化。metadata中的language_info版本号、kernel 路径等都可能因为环境不同而变化。有些 UI 操作比如折叠某个 cell也会写进metadata导致无意义的 diff。我用一个真实场景说明。你新建一个 notebook写三行代码执行完保存提交到 Git。同事拉下来也执行一遍保存提交。此时同一个 cell 的execution_count从1变成2outputs里的文本前面多了个Out[2]标记metadata[language_info][version]也换了。Git 拿到两个版本它不知道你到底改了源码还是只是重新跑了一下只能把所有变化都当作真实修改来处理。结果就是一个友好 diff 都没有全屏大红大绿。2.1 把源头掐掉提交前清除输出的几种方案既然冲突主要来自outputs和execution_count最直接的办法就是让它们不出现在版本控制里。最原始的操作是在 Jupyter 里手动选择 Kernel - Restart Clear Output然后保存。但手动操作的问题在于容易忘而且多人协作时无法保证每个人都遵守。更保险的方法是使用nbconvert的命令行能力在提交前统一处理jupyter nbconvert --to notebook --ClearOutputPreprocessor.enabledTrue --inplace your_notebook.ipynb这条命令会在原文件上清除所有输出同时保留源码和 markdown。如果你希望顺便把execution_count也重置掉再加上一行--ClearMetadataPreprocessor.enabledTrue也能做到。把这条命令写进项目的Makefile或者 CI 的脚本里每次合并前统一跑一遍冲突能少掉大半。还有一种思路是让 Git 在提交的时候自动“清洗”文件和真实入库的版本。用一个叫nbstripout的命令行工具它可以注册一个 Git filter 到当前仓库本地提交时自动过滤掉输出但工作区里的文件仍然是带输出的互不干扰。安装和使用都很简单pip install nbstripout然后进入你的 git 仓库执行nbstripout --install它会自动修改.git/config给*.ipynb配上clean和smudge过滤器。之后再提交 notebook入库的内容就不会包含 output。但前提是团队所有人都要在本地做一次这个操作否则没装的人还是会把输出提交上去。2.2 如果真要 review notebook别用普通 diff用同类工具就算你清掉了所有输出代码层面的 diff 依然可能因为大段的 markdown 和分散的metadata而显得难读。拿普通文本 diff 去看一个 notebook 的 JSON等于让一个眼科医生用放大镜看一整首诗词拼成的字谜极不直观。你真正想要的是按 cell 的维度来看变化哪个 cell 的代码改了哪个 cell 是新增的哪一行 markdown 文字被删掉了。有没有专门做这件事的工具有。Jupyter 生态里有一个叫 nbdime 的对比工具可以按 cell 为单位展示两个 notebook 的差异还能在 JupyterLab 里以 web 界面呈现。命令行来看两个核心命令就够了nbdiff --insecure notebooks/old.ipynb notebooks/new.ipynb nbdiff-web notebooks/old.ipynb notebooks/new.ipynbnbdiff输出的是文本对比nbdiff-web会打开浏览器在你眼前并排显示两个 notebook 的差异块支持一键 merge。用它来做 code review比在 GitHub 上直接看原始 JSON diff 要好用太多。我个人的经验是如果你在一个团队里做数据分析最好把“提交前清空输出”和“用 nbdime 做 review”这两件事都固定成流程。前者让文件变小变干净后者让变化点变得可读。这两步在线索清晰度上的提升远超你想象。3. 十行最实活的 .ipynb 日常技巧转脚本、命令行运行、批量操作聊完了底层结构和协作痛点这一部分说点日常真正用得上、能让你效率提高不少的操作。很多人只知道双击打开 Jupyter然后在网页里点点点实际上.ipynb文件在命令行里也能玩出花样。3.1 把 notebook 一键变成纯 Python 脚本有时候你辛辛苦苦在 notebook 里调好了一个分析流程最后要放进生产环境或者给别人跑一个干净的.py文件。使用nbconvert的--to script参数可以快速转换jupyter nbconvert --to script your_nb.ipynb你会在同目录下得到一个your_nb.py。这个脚本保留了每个 cell 里的代码并自动加上# In[1]:这样的注释标记表明每个代码块原属于哪个 notebook cell。如果 notebook 里有 markdown cell它们会被转换成#注释不会影响脚本运行。但是注意转换出来的脚本是纯顺序执行的notebook 里那种“先跑 cell 1再回过去改 cell 2”的交互状态不会被保留。如果代码里存在跨 cell 的变量依赖脚本执行顺序仍然是从上到下只要你的 notebook 是干净顺序运行的一般没问题。如果你想顺便执行转换后的脚本并验证结果可以在nbconvert命令后面加--execute。这样它会把整个 notebook 从头到尾执行一遍把输出记录下来。适合用来检测代码在“全新内核”下是否能完整跑通某种程度上就是自动化回归测试。3.2 把 notebook 变成 HTML、Markdown 或 PDF分享给不装 Jupyter 的人团队里不是每个人都装了 Jupyter、熟悉 Python。把 notebook 转成静态格式比让他们自己搭环境要划算得多jupyter nbconvert --to html your_nb.ipynb jupyter nbconvert --to markdown your_nb.ipynb转换成 HTML 后你可以直接在浏览器里打开代码、输出、Markdown 渲染效果都在。转换成 Markdown 后你还能继续用其他 Markdown 工具加工、发布到博客平台。如果你的机器上装了 LaTeX甚至可以用--to pdf直接生成 PDF 报告。不过 PDF 转换对中文支持稍麻烦一般需要额外配置字体我的经验是不如在浏览器里打印 HTML 来得省事。还有一个容易被忽略的场景用nbconvert做批量转换在自动化报告、定时邮件通知里特别有用。比如每天早上跑一个数据更新脚本然后把结果 notebook 转成 HTML 发给团队就是一条命令的事jupyter nbconvert --to html --execute report.ipynb --output report.html--execute让 notebook 在执行完所有 cell 之后再导出 HTML输出的就是带最新数据的报告比截图和文件搬运优雅得多。3.3 不打开 Jupyter直接在命令行里执行 notebookJupyter 现在已经不是单纯一个网页 IDE它提供了 CLI 入口。以 Jupyter 7 为例你可以这样做jupyter execute notebook.ipynb它会在不打开浏览器的情况下用当前默认内核执行整个 notebook。如果某个 cell 抛出异常执行会停止并返回非零退出码你也可以配上--inplace让执行结果直接写回原文件。在 CI 里想跑一个 notebook 回归测试这一条命令足够。另外如果你需要对一批 notebook 做统一操作比如清理输出、统一转脚本别手动一个一个跑命令写个几十行的 Python 脚本一次性处理是更高效的做法。我经常会用下面这段代码遍历目录把每个 notebook 里的outputs清空并重新写回import json from pathlib import Path for ipynb_path in Path(.).rglob(*.ipynb): nb json.loads(ipynb_path.read_text(encodingutf-8)) for cell in nb[cells]: if cell[cell_type] code: cell[outputs] [] cell[execution_count] None ipynb_path.write_text( json.dumps(nb, indent1, ensure_asciiFalse) \n, encodingutf-8 )脚本执行速度极快不会因为你双击打开过 Jupyter 而产生额外状态。配合 Cron 或者定时任务可以做成每个项目内部的“提交前清洗”步骤。4. 从一块损坏的 .ipynb 说起JSON 报错、校验与修复实操用.ipynb用久了几乎每个人都会遇到一次打不开文件的情况。最常见的是 Jupyter 启动后点击某个 notebook网页上直接跳出一行刺眼的红字“Unreadable Notebook: Notebook JSON is invalid”。这类错误之所以发生本质上吃透了.ipynb的 JSON 属性。任何能破坏 JSON 结构的操作都会让文件失效比如在笔记本保存的过程中强行断电、磁盘空间写满导致文件截断、某些同步盘把文件部分同步上传、用未保存好就关掉的编辑器覆盖了文件等等。另外冷启动 Jupyter 时如果正好在自动检查点写入期间崩溃也容易出现这种问题。4.1 快速定位 JSON 的第几行出了什么错JSON 的语法错误通常带有具体行号和列号所以第一步先用标准工具校验一下python -m json.tool broken.ipynb如果你足够幸运它会在终端里明确指出Expecting property name enclosed in double quotes: line 62 column 5 (char 1234)这个报错通常意味着某行的 key 或者 value 没有闭合引号或者在数组末尾多了个逗号。带着这个线索打开原始文本文件在指定位置前后检查缺失符号一般能找到问题。如果错误不是那么明显你还可以用json.loads在一个 Python 脚本里尝试解析然后用except json.JSONDecodeError as e拿到e.lineno和e.colno。这比肉眼在一大堆 JSON 里扫要快得多。另外别忘了 Jupyter 自己的自动检查点文件。在你编辑 notebook 期间Jupyter 会定期生成文件名-checkpoint.ipynb通常隐藏在与原文件同级的.ipynb_checkpoints目录下。这个文件是最接近崩溃前状态的备份。我的建议是遇到损坏先去.ipynb_checkpoints目录里找找xxx-checkpoint.ipynb。如果它可用直接用nbformat.read读取再写回一个新名字就行。4.2 常见 JSON 异常形态和手工修复套路在我拆过的坏文件里大概出现得最多的是下面这几类现象常见原因快速处理Unterminated string文件被截断字符串没有结束引号找备份或者自动检查点恢复行尾多了一个逗号比如} , }手动编辑过 JSON或某种同步工具合并出错删掉多余的逗号Non-ASCII characters乱码文件编码被破坏UTF-8 内容被转成其他编码尝试用encodingutf-8读取必要时忽略错误数组括号不闭合]缺失同步或截断导致括号丢失在文件末尾手动补上缺失的]和}NaN/Infinity出现在 JSON 里某些旧工具写入非法数字将它们替换成合法 JSON 数字或null这里给你一个稍微暴力一点的修复示例。假设你的文件缺少了最后一个大括号报错是Expecting , delimiter: line 800 column 1。你可以先用文本文件读取全部内容然后在末尾强制补上缺失的}from pathlib import Path import json path Path(broken.ipynb) text path.read_text(encodingutf-8, errorsignore) # 简单粗暴先清理可能存在的非法末尾逗号 text text.rstrip() if text.endswith(,): text text[:-1] # 补上最外层的闭合大括号只用于确定缺一个需要注意实际情况 text \n} path.write_text(text, encodingutf-8)这当然不是一个万能恢复器但它大概率能救回大部分只是在写文件时掉了最后几个字符的 notebook。真正被底层截断到中间位置的文件想完整复原几乎不可能这时候最靠谱的仍然是最初的-checkpoint.ipynb。4.3 用 nbformat 把合法的 JSON 修复成规范 notebook还有一种情况文件本身是合法 JSON但内部结构不符合 nbformat 规范比如缺少nbformat字段、cells里出现了未知类型或者outputs字段结构错乱。这种时刻nbformat.read能帮你诊断import nbformat with open(notebook.ipynb, r, encodingutf-8) as f: nb nbformat.read(f, as_version4)如果它抛出了NotebookValidationError意味着 notebook 的结构存在硬伤。部分字段缺失时你还能手动重建如果缺失严重唯一合适的思路就是从历史提交或同事手里找一份版本。再提供一个更通用的保险策略每次打开一个 notebook 时都检查一下是否包含nbformat和cells字段没有就立刻报错提醒不要带病运行。这能避免你拿着一个结构缺失的文件跑一整天最后才发现数据全没保存。5. 定位 .ipynb 的“隐藏体积”为什么一个代码文件能有几十MB以及如何瘦身我见过一个 200 行的代码 notebook体积却超过了 80MB。打开文件80% 的内容都是一大段 base64 字符串。如果不去看文件的原始内容你很难想象代码文件也能胖成这样子。这里面的大头基本是图片输出用matplotlib画个图Jupyter 默认会把渲染之后的 PNG 甚至 SVG 以 base64 编码直接嵌进 notebook 的outputs里。一张像素高、DPI 高的图编码后字符串轻松达到几百 KB 甚至数 MB。如果你一年 365 天都在 notebook 里跑同一个小图你就会得到一个体积爆炸的“时间胶囊”。其实不仅是图片文本输出也可能是巨大无比的。比如你在一个 cell 里print(df.head())结果 DataFrame 有几百列每列的字符串都很长Jupyter 会用 HTML 表格的形态把整个结果塞进输出里体积也会很可观。5.1 输出里的图片、文本和 HTML 是怎么塞进去的用一个简单方式可以看到输出对象的原始结构。比如你画了一个图然后打开.ipynb文件搜索data:image/png;base64你会看到类似这样的字段{ data: { image/png: iVBORw0KGgoAAAANSUhEUg..., text/plain: Figure size 640x480 with 1 Axes }, metadata: {}, output_type: display_data }Jupyter 后端为了让你在网页界面上看到图形会把图片编码成 Data URL。这个东西对你和你的团队肉眼阅读毫无意义占空间却是实打实的。文本输出则长成另一个模样{ name: stdout, output_type: stream, text: Running step 1\nRunning step 2\n... }如果你在循环里重复打印了 10 万行日志这个text数组就可能膨胀得非常夸张。这类输出在渲染时是合理的但一旦写进 JSON 文件里就成了体积负担。5.2 三种实用的瘦身策略不存、外置、或者只存源码第一种策略最简单提交到版本库之前清空所有输出。这等于删掉了所有outputs字段文件重归苗条。此前的第 2 章已经提供了方式就不再重复。但是要注意如果你需要在本地随时看到输出又在提交时只提交源码那么“清空输出”这件事一定要发生在提交前的 filter 流程里不能直接在工作区手动乱删。第二种策略是把大图输出到文件而不是直接内嵌在 notebook 里。拿 matplotlib 举例不推荐把大图渲染成 base64 放进 notebook 里而是把图片保存成磁盘文件然后在 notebook 里用 Markdown 或者IPython.display.Image来引用。这样 notebook 本身只保存一小段相对路径图片作为独立资源文件存在体积小、也方便其他工具复用。import matplotlib.pyplot as plt import IPython.display as display fig, ax plt.subplots(figsize(8, 6)) ax.plot([1, 2, 3], [4, 5, 6]) fig.savefig(result.png, dpi80, bbox_inchestight) plt.close(fig) # 防止 notebook 自动内嵌输出 display.Image(filenameresult.png)这里面的关键点是我把dpi从默认的 100 降到了 80同时关闭了plt.show()让图形不会进入 inline 输出再手动存到文件。这样你的 notebook 体积不会因为一两个图就被撑爆。第三种策略是在项目目录规范中约定notebook 只放业务代码和可复用片段最终数据结果放入 JSON 或 CSV 目录图片放入 assets 目录。大家的.ipynb变得轻量审查代码时也更容易聚焦。这个策略更接近一个工程规范问题但它带来的可维护性提升是很直接的。5.3 体积已经爆炸了怎么办批量压缩历史文件如果你之前已经有一批体积庞大的.ipynb提交在了仓库里可以先写一个脚本批量清洗。直接读取 JSON把所有outputs清空并重写文件import json from pathlib import Path from copy import deepcopy def strip_outputs(nb): new_nb deepcopy(nb) for cell in new_nb.get(cells, []): if cell.get(cell_type) code: cell[outputs] [] cell[execution_count] None return new_nb for p in Path(.).rglob(*.ipynb): with open(p, r, encodingutf-8) as f: nb json.load(f) with open(p, w, encodingutf-8) as f: json.dump(strip_outputs(nb), f, indent1, ensure_asciiFalse)注意这个脚本会直接改写原文件。跑之前一定先备份否则你丢掉所有历史输出再想找就没地方找了。如果要让 git 历史里的旧版本也都瘦下来那就要涉及改写历史提交操作更复杂一般也不建议随意做。更稳妥的办法是从今天开始让所有 notebook 保持小体积入库旧的超大文件在必要时用git filter-repo这类工具单独处理而不是写进日常流程。6. 从“看到”到“管理”给 .ipynb 的文件治理几条务实建议到这里.ipynb的内部结构、协作痛点和批量操作都梳理清楚了。剩下我想聊一点自己踩过坑之后的工程体会。第一对待 notbook 的定位要想清楚它到底是“报告草稿”还是“生产代码”如果是前者保留 outputs 是合理的因为你想让别人直接看到结果如果是后者那它的核心资产应该是源码和 markdownoutputs 只是过程中级产物直接丢弃才是最佳选择。在我见过的大部分失败项目里最典型的错误就是把两端混在一起既想让 notebook 成为日常分析报告又想把它当成稳定的数据管道。结果就是文件里堆满了执行结果、图片和临时状态谁都不敢乱动。第二代码还是值得抽模块。如果 notebook 里有很长一段数据处理逻辑而且这段逻辑以后还要复用那就该趁早把它挪进.py模块notebook 只负责调用和展示。这样做之后单元测试可以针对.py文件写notebook 的变化就只剩调用方式和讨论内容无论是 review 还是排查问题都会轻松不少。第三团队协作里固定一个“提交前动作”非常有价值。我的做法是在项目根目录放一个Makefile里面放一条clean-notebooks命令统一执行清空输出、重置执行计数、格式化 JSON。以后任何人想把代码合进主干先跑一下这条命令。就算最初忘了几次养成习惯之后就不会再出现“一个 pull request 里有 40MB 图片输出”的灾难。最后说一个很实在的小技巧如果你在 JupyterLab 里打开一个小型 notebook 卡到不行十次有九次是因为某一个 cell 的输出特别大。快捷键CtrlShiftP打开命令面板输入 “Clear Outputs”先把所有 cell 的输出全部清掉再重新执行你关心的那一段界面会立刻流畅很多。这个操作我没有在任何教程文档里见过特别强调但实测下来它在处理几百 MB 的 notebook 时比提高硬件配置还要管用。.ipynb本身没有自己生病它只是一次次帮你保存了代码、结果和整个上下文。理解了这一点你就明白它不是天生讨厌做版本管理而是你需要有意识地控制它往文件里塞东西的欲望。该清的时候清干净该留的时候留得明白。用好了它依然是 Python 数据分析工作流里最好用的草稿纸和汇报板。 
长河君 · 2026/10/22 15:10:02 · 阅读 1.2k 从JSON到Git冲突：.ipynb文件结构解析与高效管理实战
在 Python 生态里混了一阵子之后我发现自己其实一直把一个最常见的文件类型当“黑盒”在用——.ipynb。每天在 Jupyter 里写代码、跑实验、画图、保存却从来没认真想过这个文件内部到底长什么样。直到有几次分支合并时被一串串不可读的 diff 整得焦头烂额才开始静下心来把这个格式彻底拆了一遍。这篇文章就把我对.ipynb文件的认识从头捋一遍包括它的结构、它在工程协作里为什么这么闹心、日常使用效率极高的几个操作方式以及文件损坏和体积膨胀时的处理思路。如果你也写过 notebook、被 Git 冲突折磨过、或者只是好奇这文件里到底存了什么那这篇值得看完。1. 先搞清楚 .ipynb 到底是个什么JSON 皮囊 交互式内脏很多人以为.ipynb是某种专属二进制格式其实完全不是。它就是一个标准的 JSON 文件只是文件后缀换成了.ipynb全称是 iPython Notebook但现在基本泛指 Jupyter Notebook。这意味着你用任何文本编辑器打开它都能直接看到里面的文字内容没有任何加密和混淆。也正因为它基于 JSONPython、R、Julia 甚至 JavaScript 都有现成的解析库跨语言交换非常方便。一个最简单不过的 notebook 文件结构大概是这样的{ cells: [ { cell_type: code, execution_count: 1, metadata: {}, outputs: [ { name: stdout, output_type: stream, text: hello world\n } ], source: [ print(hello world) ] } ], metadata: { kernelspec: { display_name: Python 3, language: python, name: python3 }, language_info: { name: python, version: 3.11.0 } }, nbformat: 4, nbformat_minor: 4 }粗看这个结构顶层就是三块cells、metadata、nbformat。其中nbformat是格式规范的版本号目前主流是 4不同小版本之间有一些字段上的兼容差异。metadata是文件的元信息保存了内核种类、Python 版本、语言信息等。而cells才是真正承载内容的骨架是一个数组里面每一元素就是一个单元。1.1 code cell 里的四件套source、execution_count、outputs、metadata在.ipynb文件里最关键的还是 code cell。每个 code cell 都有四个主要字段source单元格里的源码一般以字符串数组的形式存在每个数组元素对应一行方便解析器的逐行处理。如果你用程序读取常常需要.join(cell[source])才能拿到完整源码。execution_count这个 cell 最近一次执行的编号。注意是“最近一次执行”不是执行次数。只要你在 notebook 里按一次运行它就会变一次。这个字段是 Git 冲突的常客。outputs执行之后的结果列表。包括纯文本输出、图片 base64、富文本 HTML 等等。典型类型有stream、execute_result、display_data、error等。这个也是导致文件体积膨胀和版本冲突的大头。metadata记录当前 cell 的局部元信息比如是否折叠代码、标签等大多数场景下是空对象。不同 cell 的metadata内容不一定一样比如 markdown cell 可以带tags字段code cell 还可以带collapsed这类 UI 状态。保存这些东西对于用户复现交互状态很有帮助但对于只有代码本身有意义的项目来说又显得多余。1.2 markdown cell 与 raw cell 的区别和应用除了 code cell文件里还经常会看到markdown和raw两种类型的 cell。markdown cell 的source里存的是带#、-等排版的 Markdown 文本用于写说明、标题、公式。它没有outputs和execution_count。很多人在做技术分享时喜欢把README内容直接写成 notebook 的 markdown cell好处是代码和文档共存于一个文件评审的时候可以直接看到上下文。raw cell 则更特殊一点它里面的内容不会被执行也不会被渲染只用于存放你需要“原样保留”的文本比如 LaTeX 源码片段或者某些特定格式的开头。平时我们很少主动创建 raw cell但接触nbconvert这类工具时会遇到它。从本质上讲.ipynb保存的不仅仅是代码还保存了“执行后”的整个世界。source是输入outputs是输出metadata是环境线索整份文件就是一个可以再次打开的完整会话记录。这也是它和纯.py文件最大的差别:.py只有逻辑.ipynb还有故事。2. 为什么 .ipynb 在 Git 里会变成“冲突之王”输出、计数器与元数据的锅如果你和我一样曾经在一个稍微上点规模的项目里把.ipynb提交进了 Git大概率会经历过这种场景两个人各自运行过同一个 notebook然后各自提交各自的分支等到 merge 的时候Git 会直接宣告这个文件冲突而且 diff 里夹杂着一大堆你根本不想看的 base64 图片数据、执行计数和元数据变化。问题不在于 Git而在于.ipynb的默认保存策略太“重”。我们来看几个最容易导致冲突的因素execution_count每次执行都会递增哪怕代码一行没改只要跑过一次文件就变了。outputs里保存了大量输出结果图片转成 base64 后字符串长度吓人任何二次执行都会让输出对象变化。metadata中的language_info版本号、kernel 路径等都可能因为环境不同而变化。有些 UI 操作比如折叠某个 cell也会写进metadata导致无意义的 diff。我用一个真实场景说明。你新建一个 notebook写三行代码执行完保存提交到 Git。同事拉下来也执行一遍保存提交。此时同一个 cell 的execution_count从1变成2outputs里的文本前面多了个Out[2]标记metadata[language_info][version]也换了。Git 拿到两个版本它不知道你到底改了源码还是只是重新跑了一下只能把所有变化都当作真实修改来处理。结果就是一个友好 diff 都没有全屏大红大绿。2.1 把源头掐掉提交前清除输出的几种方案既然冲突主要来自outputs和execution_count最直接的办法就是让它们不出现在版本控制里。最原始的操作是在 Jupyter 里手动选择 Kernel - Restart Clear Output然后保存。但手动操作的问题在于容易忘而且多人协作时无法保证每个人都遵守。更保险的方法是使用nbconvert的命令行能力在提交前统一处理jupyter nbconvert --to notebook --ClearOutputPreprocessor.enabledTrue --inplace your_notebook.ipynb这条命令会在原文件上清除所有输出同时保留源码和 markdown。如果你希望顺便把execution_count也重置掉再加上一行--ClearMetadataPreprocessor.enabledTrue也能做到。把这条命令写进项目的Makefile或者 CI 的脚本里每次合并前统一跑一遍冲突能少掉大半。还有一种思路是让 Git 在提交的时候自动“清洗”文件和真实入库的版本。用一个叫nbstripout的命令行工具它可以注册一个 Git filter 到当前仓库本地提交时自动过滤掉输出但工作区里的文件仍然是带输出的互不干扰。安装和使用都很简单pip install nbstripout然后进入你的 git 仓库执行nbstripout --install它会自动修改.git/config给*.ipynb配上clean和smudge过滤器。之后再提交 notebook入库的内容就不会包含 output。但前提是团队所有人都要在本地做一次这个操作否则没装的人还是会把输出提交上去。2.2 如果真要 review notebook别用普通 diff用同类工具就算你清掉了所有输出代码层面的 diff 依然可能因为大段的 markdown 和分散的metadata而显得难读。拿普通文本 diff 去看一个 notebook 的 JSON等于让一个眼科医生用放大镜看一整首诗词拼成的字谜极不直观。你真正想要的是按 cell 的维度来看变化哪个 cell 的代码改了哪个 cell 是新增的哪一行 markdown 文字被删掉了。有没有专门做这件事的工具有。Jupyter 生态里有一个叫 nbdime 的对比工具可以按 cell 为单位展示两个 notebook 的差异还能在 JupyterLab 里以 web 界面呈现。命令行来看两个核心命令就够了nbdiff --insecure notebooks/old.ipynb notebooks/new.ipynb nbdiff-web notebooks/old.ipynb notebooks/new.ipynbnbdiff输出的是文本对比nbdiff-web会打开浏览器在你眼前并排显示两个 notebook 的差异块支持一键 merge。用它来做 code review比在 GitHub 上直接看原始 JSON diff 要好用太多。我个人的经验是如果你在一个团队里做数据分析最好把“提交前清空输出”和“用 nbdime 做 review”这两件事都固定成流程。前者让文件变小变干净后者让变化点变得可读。这两步在线索清晰度上的提升远超你想象。3. 十行最实活的 .ipynb 日常技巧转脚本、命令行运行、批量操作聊完了底层结构和协作痛点这一部分说点日常真正用得上、能让你效率提高不少的操作。很多人只知道双击打开 Jupyter然后在网页里点点点实际上.ipynb文件在命令行里也能玩出花样。3.1 把 notebook 一键变成纯 Python 脚本有时候你辛辛苦苦在 notebook 里调好了一个分析流程最后要放进生产环境或者给别人跑一个干净的.py文件。使用nbconvert的--to script参数可以快速转换jupyter nbconvert --to script your_nb.ipynb你会在同目录下得到一个your_nb.py。这个脚本保留了每个 cell 里的代码并自动加上# In[1]:这样的注释标记表明每个代码块原属于哪个 notebook cell。如果 notebook 里有 markdown cell它们会被转换成#注释不会影响脚本运行。但是注意转换出来的脚本是纯顺序执行的notebook 里那种“先跑 cell 1再回过去改 cell 2”的交互状态不会被保留。如果代码里存在跨 cell 的变量依赖脚本执行顺序仍然是从上到下只要你的 notebook 是干净顺序运行的一般没问题。如果你想顺便执行转换后的脚本并验证结果可以在nbconvert命令后面加--execute。这样它会把整个 notebook 从头到尾执行一遍把输出记录下来。适合用来检测代码在“全新内核”下是否能完整跑通某种程度上就是自动化回归测试。3.2 把 notebook 变成 HTML、Markdown 或 PDF分享给不装 Jupyter 的人团队里不是每个人都装了 Jupyter、熟悉 Python。把 notebook 转成静态格式比让他们自己搭环境要划算得多jupyter nbconvert --to html your_nb.ipynb jupyter nbconvert --to markdown your_nb.ipynb转换成 HTML 后你可以直接在浏览器里打开代码、输出、Markdown 渲染效果都在。转换成 Markdown 后你还能继续用其他 Markdown 工具加工、发布到博客平台。如果你的机器上装了 LaTeX甚至可以用--to pdf直接生成 PDF 报告。不过 PDF 转换对中文支持稍麻烦一般需要额外配置字体我的经验是不如在浏览器里打印 HTML 来得省事。还有一个容易被忽略的场景用nbconvert做批量转换在自动化报告、定时邮件通知里特别有用。比如每天早上跑一个数据更新脚本然后把结果 notebook 转成 HTML 发给团队就是一条命令的事jupyter nbconvert --to html --execute report.ipynb --output report.html--execute让 notebook 在执行完所有 cell 之后再导出 HTML输出的就是带最新数据的报告比截图和文件搬运优雅得多。3.3 不打开 Jupyter直接在命令行里执行 notebookJupyter 现在已经不是单纯一个网页 IDE它提供了 CLI 入口。以 Jupyter 7 为例你可以这样做jupyter execute notebook.ipynb它会在不打开浏览器的情况下用当前默认内核执行整个 notebook。如果某个 cell 抛出异常执行会停止并返回非零退出码你也可以配上--inplace让执行结果直接写回原文件。在 CI 里想跑一个 notebook 回归测试这一条命令足够。另外如果你需要对一批 notebook 做统一操作比如清理输出、统一转脚本别手动一个一个跑命令写个几十行的 Python 脚本一次性处理是更高效的做法。我经常会用下面这段代码遍历目录把每个 notebook 里的outputs清空并重新写回import json from pathlib import Path for ipynb_path in Path(.).rglob(*.ipynb): nb json.loads(ipynb_path.read_text(encodingutf-8)) for cell in nb[cells]: if cell[cell_type] code: cell[outputs] [] cell[execution_count] None ipynb_path.write_text( json.dumps(nb, indent1, ensure_asciiFalse) \n, encodingutf-8 )脚本执行速度极快不会因为你双击打开过 Jupyter 而产生额外状态。配合 Cron 或者定时任务可以做成每个项目内部的“提交前清洗”步骤。4. 从一块损坏的 .ipynb 说起JSON 报错、校验与修复实操用.ipynb用久了几乎每个人都会遇到一次打不开文件的情况。最常见的是 Jupyter 启动后点击某个 notebook网页上直接跳出一行刺眼的红字“Unreadable Notebook: Notebook JSON is invalid”。这类错误之所以发生本质上吃透了.ipynb的 JSON 属性。任何能破坏 JSON 结构的操作都会让文件失效比如在笔记本保存的过程中强行断电、磁盘空间写满导致文件截断、某些同步盘把文件部分同步上传、用未保存好就关掉的编辑器覆盖了文件等等。另外冷启动 Jupyter 时如果正好在自动检查点写入期间崩溃也容易出现这种问题。4.1 快速定位 JSON 的第几行出了什么错JSON 的语法错误通常带有具体行号和列号所以第一步先用标准工具校验一下python -m json.tool broken.ipynb如果你足够幸运它会在终端里明确指出Expecting property name enclosed in double quotes: line 62 column 5 (char 1234)这个报错通常意味着某行的 key 或者 value 没有闭合引号或者在数组末尾多了个逗号。带着这个线索打开原始文本文件在指定位置前后检查缺失符号一般能找到问题。如果错误不是那么明显你还可以用json.loads在一个 Python 脚本里尝试解析然后用except json.JSONDecodeError as e拿到e.lineno和e.colno。这比肉眼在一大堆 JSON 里扫要快得多。另外别忘了 Jupyter 自己的自动检查点文件。在你编辑 notebook 期间Jupyter 会定期生成文件名-checkpoint.ipynb通常隐藏在与原文件同级的.ipynb_checkpoints目录下。这个文件是最接近崩溃前状态的备份。我的建议是遇到损坏先去.ipynb_checkpoints目录里找找xxx-checkpoint.ipynb。如果它可用直接用nbformat.read读取再写回一个新名字就行。4.2 常见 JSON 异常形态和手工修复套路在我拆过的坏文件里大概出现得最多的是下面这几类现象常见原因快速处理Unterminated string文件被截断字符串没有结束引号找备份或者自动检查点恢复行尾多了一个逗号比如} , }手动编辑过 JSON或某种同步工具合并出错删掉多余的逗号Non-ASCII characters乱码文件编码被破坏UTF-8 内容被转成其他编码尝试用encodingutf-8读取必要时忽略错误数组括号不闭合]缺失同步或截断导致括号丢失在文件末尾手动补上缺失的]和}NaN/Infinity出现在 JSON 里某些旧工具写入非法数字将它们替换成合法 JSON 数字或null这里给你一个稍微暴力一点的修复示例。假设你的文件缺少了最后一个大括号报错是Expecting , delimiter: line 800 column 1。你可以先用文本文件读取全部内容然后在末尾强制补上缺失的}from pathlib import Path import json path Path(broken.ipynb) text path.read_text(encodingutf-8, errorsignore) # 简单粗暴先清理可能存在的非法末尾逗号 text text.rstrip() if text.endswith(,): text text[:-1] # 补上最外层的闭合大括号只用于确定缺一个需要注意实际情况 text \n} path.write_text(text, encodingutf-8)这当然不是一个万能恢复器但它大概率能救回大部分只是在写文件时掉了最后几个字符的 notebook。真正被底层截断到中间位置的文件想完整复原几乎不可能这时候最靠谱的仍然是最初的-checkpoint.ipynb。4.3 用 nbformat 把合法的 JSON 修复成规范 notebook还有一种情况文件本身是合法 JSON但内部结构不符合 nbformat 规范比如缺少nbformat字段、cells里出现了未知类型或者outputs字段结构错乱。这种时刻nbformat.read能帮你诊断import nbformat with open(notebook.ipynb, r, encodingutf-8) as f: nb nbformat.read(f, as_version4)如果它抛出了NotebookValidationError意味着 notebook 的结构存在硬伤。部分字段缺失时你还能手动重建如果缺失严重唯一合适的思路就是从历史提交或同事手里找一份版本。再提供一个更通用的保险策略每次打开一个 notebook 时都检查一下是否包含nbformat和cells字段没有就立刻报错提醒不要带病运行。这能避免你拿着一个结构缺失的文件跑一整天最后才发现数据全没保存。5. 定位 .ipynb 的“隐藏体积”为什么一个代码文件能有几十MB以及如何瘦身我见过一个 200 行的代码 notebook体积却超过了 80MB。打开文件80% 的内容都是一大段 base64 字符串。如果不去看文件的原始内容你很难想象代码文件也能胖成这样子。这里面的大头基本是图片输出用matplotlib画个图Jupyter 默认会把渲染之后的 PNG 甚至 SVG 以 base64 编码直接嵌进 notebook 的outputs里。一张像素高、DPI 高的图编码后字符串轻松达到几百 KB 甚至数 MB。如果你一年 365 天都在 notebook 里跑同一个小图你就会得到一个体积爆炸的“时间胶囊”。其实不仅是图片文本输出也可能是巨大无比的。比如你在一个 cell 里print(df.head())结果 DataFrame 有几百列每列的字符串都很长Jupyter 会用 HTML 表格的形态把整个结果塞进输出里体积也会很可观。5.1 输出里的图片、文本和 HTML 是怎么塞进去的用一个简单方式可以看到输出对象的原始结构。比如你画了一个图然后打开.ipynb文件搜索data:image/png;base64你会看到类似这样的字段{ data: { image/png: iVBORw0KGgoAAAANSUhEUg..., text/plain: Figure size 640x480 with 1 Axes }, metadata: {}, output_type: display_data }Jupyter 后端为了让你在网页界面上看到图形会把图片编码成 Data URL。这个东西对你和你的团队肉眼阅读毫无意义占空间却是实打实的。文本输出则长成另一个模样{ name: stdout, output_type: stream, text: Running step 1\nRunning step 2\n... }如果你在循环里重复打印了 10 万行日志这个text数组就可能膨胀得非常夸张。这类输出在渲染时是合理的但一旦写进 JSON 文件里就成了体积负担。5.2 三种实用的瘦身策略不存、外置、或者只存源码第一种策略最简单提交到版本库之前清空所有输出。这等于删掉了所有outputs字段文件重归苗条。此前的第 2 章已经提供了方式就不再重复。但是要注意如果你需要在本地随时看到输出又在提交时只提交源码那么“清空输出”这件事一定要发生在提交前的 filter 流程里不能直接在工作区手动乱删。第二种策略是把大图输出到文件而不是直接内嵌在 notebook 里。拿 matplotlib 举例不推荐把大图渲染成 base64 放进 notebook 里而是把图片保存成磁盘文件然后在 notebook 里用 Markdown 或者IPython.display.Image来引用。这样 notebook 本身只保存一小段相对路径图片作为独立资源文件存在体积小、也方便其他工具复用。import matplotlib.pyplot as plt import IPython.display as display fig, ax plt.subplots(figsize(8, 6)) ax.plot([1, 2, 3], [4, 5, 6]) fig.savefig(result.png, dpi80, bbox_inchestight) plt.close(fig) # 防止 notebook 自动内嵌输出 display.Image(filenameresult.png)这里面的关键点是我把dpi从默认的 100 降到了 80同时关闭了plt.show()让图形不会进入 inline 输出再手动存到文件。这样你的 notebook 体积不会因为一两个图就被撑爆。第三种策略是在项目目录规范中约定notebook 只放业务代码和可复用片段最终数据结果放入 JSON 或 CSV 目录图片放入 assets 目录。大家的.ipynb变得轻量审查代码时也更容易聚焦。这个策略更接近一个工程规范问题但它带来的可维护性提升是很直接的。5.3 体积已经爆炸了怎么办批量压缩历史文件如果你之前已经有一批体积庞大的.ipynb提交在了仓库里可以先写一个脚本批量清洗。直接读取 JSON把所有outputs清空并重写文件import json from pathlib import Path from copy import deepcopy def strip_outputs(nb): new_nb deepcopy(nb) for cell in new_nb.get(cells, []): if cell.get(cell_type) code: cell[outputs] [] cell[execution_count] None return new_nb for p in Path(.).rglob(*.ipynb): with open(p, r, encodingutf-8) as f: nb json.load(f) with open(p, w, encodingutf-8) as f: json.dump(strip_outputs(nb), f, indent1, ensure_asciiFalse)注意这个脚本会直接改写原文件。跑之前一定先备份否则你丢掉所有历史输出再想找就没地方找了。如果要让 git 历史里的旧版本也都瘦下来那就要涉及改写历史提交操作更复杂一般也不建议随意做。更稳妥的办法是从今天开始让所有 notebook 保持小体积入库旧的超大文件在必要时用git filter-repo这类工具单独处理而不是写进日常流程。6. 从“看到”到“管理”给 .ipynb 的文件治理几条务实建议到这里.ipynb的内部结构、协作痛点和批量操作都梳理清楚了。剩下我想聊一点自己踩过坑之后的工程体会。第一对待 notbook 的定位要想清楚它到底是“报告草稿”还是“生产代码”如果是前者保留 outputs 是合理的因为你想让别人直接看到结果如果是后者那它的核心资产应该是源码和 markdownoutputs 只是过程中级产物直接丢弃才是最佳选择。在我见过的大部分失败项目里最典型的错误就是把两端混在一起既想让 notebook 成为日常分析报告又想把它当成稳定的数据管道。结果就是文件里堆满了执行结果、图片和临时状态谁都不敢乱动。第二代码还是值得抽模块。如果 notebook 里有很长一段数据处理逻辑而且这段逻辑以后还要复用那就该趁早把它挪进.py模块notebook 只负责调用和展示。这样做之后单元测试可以针对.py文件写notebook 的变化就只剩调用方式和讨论内容无论是 review 还是排查问题都会轻松不少。第三团队协作里固定一个“提交前动作”非常有价值。我的做法是在项目根目录放一个Makefile里面放一条clean-notebooks命令统一执行清空输出、重置执行计数、格式化 JSON。以后任何人想把代码合进主干先跑一下这条命令。就算最初忘了几次养成习惯之后就不会再出现“一个 pull request 里有 40MB 图片输出”的灾难。最后说一个很实在的小技巧如果你在 JupyterLab 里打开一个小型 notebook 卡到不行十次有九次是因为某一个 cell 的输出特别大。快捷键CtrlShiftP打开命令面板输入 “Clear Outputs”先把所有 cell 的输出全部清掉再重新执行你关心的那一段界面会立刻流畅很多。这个操作我没有在任何教程文档里见过特别强调但实测下来它在处理几百 MB 的 notebook 时比提高硬件配置还要管用。.ipynb本身没有自己生病它只是一次次帮你保存了代码、结果和整个上下文。理解了这一点你就明白它不是天生讨厌做版本管理而是你需要有意识地控制它往文件里塞东西的欲望。该清的时候清干净该留的时候留得明白。用好了它依然是 Python 数据分析工作流里最好用的草稿纸和汇报板。