1. 一个困扰了我很久的问题长 notebook 里找不到自己写过的东西先说说我自己的场景。我经常在一份 notebook 里同时塞下数据清洗、特征工程、模型调参、结果可视化这些内容跑着跑着整个文件就奔着几百个 cell 去了。等几天后回来看最痛苦的不是代码报错而是我记得我写过一段处理缺失值的代码到底在哪然后就是一遍又一遍地用鼠标上下滚动在密密麻麻的输出结果里找那个曾经熟悉的 Markdown 标题。用过很多编辑器的人应该都有这种感觉在 IDE 里写长文件靠的是目录树和代码折叠在 notebook 里写长文档靠的却是记忆力。Jupyter Notebook 原生的界面里你只能看到一个 cell 接一个 cell 往下铺没有任何侧边栏可以告诉你当前看到的是哪一节、这一节下面有哪些子内容。文件越长这种迷失感越强烈。直到我发现了 Jupyter Notebook 自带的 Outline 功能以及一个叫 jupyter-contrib-nbextensions 的插件包里的 Table of Contents 插件通常简称 toc2这个问题才算彻底解决。装上之后长 notebook 也能像 Word 文档一样拥有清晰的目录层级点击任意标题就能瞬间跳转到对应位置配合 JupyterLab 自带的 Table of Contents 面板体验完全不输现代 IDE。这篇文章就是从让笔记本拥有可跳转目录这个需求出发把我在配置过程中踩过的坑、试过的方法、以及最终稳定的方案全部梳理一遍。内容主要分为三个部分先讲清楚 Jupyter 生态里目录功能到底是怎么运作的再给出 Notebook 和 JupyterLab 两套环境下的配置实操最后整理几个高频问题的排查思路包括 tqdm 报错、单元格无法被执行、以及装了插件但打开网页没有反应这类看起来诡异、实际上原因很简单的故障。不管你用的是 Notebook 老界面、JupyterLab还是最近流行的 VSCode 联动方案这篇文章里都会有一个适合你的做法。2. 目录功能的实现原理Markdown 标题与 HTML 锚点的映射关系在动手配置之前我觉得有必要先把原理讲清楚。很多人以为目录是插件抓取出来的其实不是它是基于一个非常朴素的机制Jupyter Notebook 本身就会把 Markdown 单元格渲染成 HTML而 Markdown 里的各级标题#、##、###会被自动转换成 HTML 里对应的 h1、h2、h3 标签同时生成带有 id 属性的锚点元素。目录插件做的事情就是扫描当前 notebook 里所有渲染后的标题元素提取它们的层级关系和文本内容在侧边栏生成一个树状列表再给每个条目绑定一个点击跳转事件。这里有一个很关键的细节目录能否正常工作完全取决于 Markdown 标题有没有被正确渲染。如果你在 Markdown 单元格里写了# 标题但前面有缩进空格或者写成了代码块里的#Jupyter 就不会把它当成标题目录里自然也不会出现。这也是很多人在利用 GPT 生成 notebook 内容时经常遇到的坑——AI 生成的 Markdown 有时会在标题前多一个空格肉眼看起来一模一样但 Jupyter 的渲染规则是标题必须顶格写一旦不满足跳转就是失败。另外一个值得知道的概念是锚点。当插件扫描到## 数据清洗这个标题时它会在 HTML 里生成类似h2 id数据清洗的结构点击目录条目时浏览器会通过 JavaScript 直接滚动到该 id 对应的 DOM 元素上。所以逻辑上只要标题的 id 唯一且正确跳转就 100% 可靠反过来如果你在同一个 notebook 里写了两个完全一样的标题就会出现跳转到第一个标题的诡异现象。我后面在排查问题的时候才发现重复标题是很多人明明装了插件却跳转异常的隐藏原因。理解了这套机制再去看目录插件的各种设置项就会发现其实并不复杂。比如 toc2 插件里的标题编号功能就是在抓取到 h2、h3 标题文本后用 JavaScript 在文本前面拼接一个1.、1.1这样的序号折叠目录功能则是控制侧边栏列表的展开状态。知道原理之后遇到问题你会有更清晰的排查方向而不是只能靠卸载重装这种一招鲜。## 3. Notebook 环境jupyter-contrib-nbextensions 插件安装与 toc2 配置 如果你还在使用传统的 Jupyter Notebook 界面就是那个左上角写着 jupyter、文件列表是树的版本最主流的目录方案是通过 jupyter_contrib_nbextensions 这个插件包来安装 toc2。先说结论**这个方法目前依然有效但在新版 Python 和 Jupyter 环境下安装时容易踩坑建议使用 conda 环境或者提前装好依赖**。 整个安装流程分四步我按照实际操作顺序列出来并把每个步骤的注意点单独说明。 第一步是安装插件包本体。打开终端激活你平时运行 Jupyter 的 Python 环境执行 bash pip install jupyter_contrib_nbextensions如果这条命令运行很慢或者报错可以用清华镜像源加速pip install jupyter_contrib_nbextensions -i https://pypi.tuna.tsinghua.edu.cn/simple这里要提醒一句这个包依赖 jupyter-nbextensions-configurator正常情况 pip 会自动帮你装好但如果你用的是 Python 3.11 或更高版本可能会遇到依赖冲突报错信息大多是cannot import name Mapping from collections。这个问题的根源是旧版包没有兼容新版本 Python 的 collections.abc 模块。解决办法是手动安装一个兼容版本pip install jupyter-contrib-nbextensions0.7.0如果依然报错建议直接用 conda 安装conda 会自动解析依赖组合conda install -c conda-forge jupyter_contrib_nbextensions第二步是安装 JavaScript 和 CSS 资源文件。这一步经常被很多人忽略导致插件管理器里找不到 toc2jupyter contrib nbextension install --user第三步是启动配置器并开启 toc2。安装完成后重新启动 Jupyter Notebook你会看到笔记本首页新增了一个名为Nbextensions的标签页。点进去勾选Table of Contents (2)即可。这里有一个常见问题如果你的 Nbextensions 页面打开后所有插件都显示为灰色不可勾选说明配置器没有正确察觉到你的 notebook 版本通常是旧版 bug。可以尝试更新到最新版本pip install --upgrade jupyter_nbextensions_configurator第四步是配置 toc2 的具体参数。勾选之后回到 notebook 编辑界面你会看到工具栏上多了一个目录按钮点击就会在左侧展开一个带层级结构的目录面板。到这里基本的目录跳转功能已经可用了。但是想真正用得舒服我建议你花 30 秒做两个调整。打开菜单栏的Edit - nbextensions config找到Table of Contents (2)章节把以下几个选项勾上Add notebook cells允许在 notebook 顶部自动插入一个 TOC 单元格这样别人打开你的 notebook 时第一眼就能看到全篇结构。Number headings自动给各级标题编号生成类似1.、1.1、1.1.1的层级序号配合目录使用非常直观。Collapse sections允许点击目录条目时折叠/展开代码块这个功能对超长 notebook 特别友好。这几个配置项都可以实时生效不需要重启 Jupyter。唯一要注意的是如果你勾选了 Add notebook cells 并且插入了 TOC 单元格这张表只会在 notebook 保存时自动更新如果你在编辑中反复增删标题最好在目录面板右上角点一下刷新按钮或者重新执行 TOC 单元格。## 4. JupyterLab 用户不需要插件原生自带 Table of Contents 如果你已经切换到 JupyterLab 界面就是那种左侧有文件树、可以多标签打开多个 ipynb 的现代化界面有个好消息**JupyterLab 原生就内置了 Table of Contents 功能根本不需要安装任何插件**。很多从 Notebook 老界面迁移过来的用户会习惯性地去装 nbextensions其实完全没有必要反而会引入兼容性问题。 启用方式很简单 1. 打开任意一个 .ipynb 文件。 2. 点击左侧边栏的目录图标外观像一个带层级的列表如果没有看到可以通过菜单栏 **View - Show Left Sidebar** 呼出侧边栏然后在面板列表中找到它。 3. 面板会自动根据当前 notebook 的 Markdown 标题生成层级目录点击任意条目即可跳转。 基础的目录面板虽然好用但如果你希望目录跟 Word 一样支持拖拽调整章节顺序或者需要给标题自动编号就要另辟蹊径。这里推荐一个 JupyterLab 扩展插件**jupyterlab/toc** 的增强版 **jupyterlab-toc**社区维护版支持更多自定义选项。 安装方式为 bash pip install jupyterlab-toc jupyter lab build安装完成后需要重启 JupyterLab。这个增强版插件可以做到目录跟随滚动、点击标题跳转后高亮当前章节以及与标签页联动等高级功能。我用 JupyterLab 一段时间后最大的感受是原生目录面板虽然轻量好用但它在标题编号和目录折叠层级上不如老版 toc2 灵活。如果你对目录编号有刚需又没有精力折腾增强插件可以尝试在 Markdown 里手动给标题加编号虽然维护起来麻烦一点但在原生环境下兼容性最好。## 5. 一个血泪教训运行代码没反应、插件不加载到底卡在哪里 这个部分专门聊故障排查。因为我在整理这篇文章的过程中翻到很多热搜词涉及类似jupyter notebook 单元格执行代码没有任何反应jupyter notebook 打不开jupyter notebook 无法运行再加上我自己在配置目录插件时也遇到过装了插件但网页端完全没反应的怪问题所以这里把几条真实的排查链路写出来希望对你有参考价值。 ### 5.1 单元格执行代码没有任何反应的原因与排查 首先明确一个概念你在 Jupyter Notebook 里点击 Run 按钮执行代码背后发生的是 **Jupyter 内核Kernel接收到执行请求然后返回结果显示在界面上**。如果你点了执行但一点反应都没有问题往往出在内核和前端通信上而不是你的代码本身有问题。 我遇到过最典型的情况是notebook 能正常打开Markdown 目录也显示出来了但一执行代码就卡死转圈转个不停最后显示 [*] 或 Kernel Restarting。排查思路如下 1. **打开内核日志**。在终端里启动 Jupyter Notebook 时会持续输出日志执行代码后去看日志里面通常会有 Python 报错的堆栈信息。最常见的错误是前面提到过的 ImportError: DLL load failed while importing rpds。这个 rpds 库其实是 referencing 这个重量级依赖的 Rust 扩展出现在 Jupyter 里通常与 jsonschema 相关。处理办法是在当前环境里重装一遍相关包 bash pip install --upgrade jsonschema referencing rpds-py如果重装后仍然报错强烈建议直接为 Jupyter 新建一个干净的 conda 环境很多莫名其妙的 DLL 错误都是环境里包版本太混乱导致的。检查内核是否挂掉。在界面上方的Kernel - Change Kernel里确认当前选中的是正确环境的 Python。这个问题在用户同时装了 Anaconda 和系统 Python 的情况下特别常见——不要问我为什么知道。关闭浏览器扩展干扰。我第一次遇到单元格执行没反应时死磕了半天内核最后发现是浏览器端的一个翻译插件把 Jupyter 的 WebSocket 内容给劫持了。你在排查这个问题时如果代码在隐身模式或无痕窗口下执行正常那就可以确定是浏览器扩展的问题。5.2 打开网页版 Jupyter 打不开 或页面空白VSCode 里集成的 Jupyter 功能越用越多很多人现在都习惯了在 VSCode 里写 notebook然后忘了自己电脑上还跑着一个原生 Jupyter 服务。当你双击jupyter notebook后一直卡在启动页面或者浏览器打开http://localhost:8888显示空白常见原因有两个。一是端口被占用了。默认端口 8888 被其他进程占用时Jupyter 会自动切换到 8889、8890 等可用端口但浏览器里的标签页还停留在旧 URL。解决办法很简单启动时直接指定一个新端口jupyter notebook --port 9999二是配置文件损坏。如果你之前手动改过~/.jupyter/jupyter_notebook_config.py比如自定义过密码、修改过 root_dir某个配置项写错就可能让页面加载失败。排查方法是临时用干净配置启动一次jupyter notebook --config如果这样能正常启动就说明问题出在你的自定义配置上检查每一项配置即可。5.3 目录插件装了没反应先看 JavaScript 控制台这是我在配置 toc2 时个人踩过最困惑的坑。明明 Nbextensions 页面里 toc2 已经勾选了回到 notebook 界面却找不到目录按钮。后来我在浏览器开发者工具F12里的 Console 面板看到了一行红色的报错信息提示某个 JS 文件 404 找不到。这类问题的根源通常有两个插件安装路径和 Jupyter 实际扫描路径不一致。解决办法是重新执行一遍jupyter contrib nbextension install --user并确保执行这条命令的 Python 环境和启动 Jupyter 的环境是同一个。浏览器缓存了旧的 Jupyter 页面资源。解决办法是强制刷新CtrlShiftR或者干脆换个无痕窗口打开目 录按钮一般立刻就能回来。如果你的浏览器控制台没有任何报错但仍然看不到目录按钮可以检查一下当前 notebook 里是不是没有任何 Markdown 标题。toc2 在检测到零个标题时工具栏上的目录图标会自动隐藏这个设计很反直觉但确实存在。我在一篇文章里就试过新建的空白 notebook 里看不到目录按钮往里写一个# 标题之后按钮就出现了。## 6. 目录跳转的进阶玩法给标题编号、点击目录折叠代码、自动生成 TOC 单元格 基础跳转功能搞定之后如果再往下钻研有几个设置能让你的 notebook 使用体验产生质变。我把最实用的进阶玩法整理一下这里不分 Notebook 还是 JupyterLab大家按自己所在的环境对号入座。 ### 6.1 给标题自动编号 长文档里没有编号目录再清晰也总觉得少了点什么。toc2 的 Number headings 选项可以给所有标题自动加上 1.、1.1 这样的层级序号。开了之后你会看到正文里的标题文本也被同步加了前缀而且这个序号是动态计算的调整层级后刷新目录就会同步更新。 需要注意的是如果你在 Markdown 里手动写了数字编号比如 ## 1. 数据清洗再开启自动编号就会出现 ## 1. 1. 数据清洗 这种双重编号。建议二选一要么手动编号、不勾选此选项要么所有标题都不带数字交给插件去加。 ### 6.2 点击目录折叠代码块 Collapse sections 功能开启以后目录里的章节会对应到一组连续的 cell。点击章节条目时该章节下的所有代码和 Markdown 单元格会整体折叠只剩一个标题条。这个功能对整理报告类 notebook 极其有用因为别人阅读你的文件时可以先用目录浏览整体结构需要看细节再展开对应的代码单元格不会被几百行代码淹没。 我自己用这个功能最常见的场景是写数据分析报告开头放项目背景Markdown中间是清洗代码Python末尾是可视化图表。开启折叠后阅读者可以先看目录判断每个章节讲什么再按需展开体验非常接近阅读一篇结构良好的文档。 ### 6.3 在 notebook 顶部插入一个 TOC 单元格 toc2 的 Add notebook cells 功能会在文件最顶部插入一个特殊的目录单元格里面实时渲染出整篇文档的目录。这样做的好处是**即便把 notebook 分享给别人对方没有安装任何目录插件也能通过这个单元格知道全篇结构并且点击目录条目一样可以跳转**。 这个 TOC 单元格本质上是把目录数据以 Markdown 链接的形式写进了 notebook 文件里所以分享时不需要额外传递任何插件。唯一的注意事项是每当你的标题发生变化增删、改名、调整层级需要手动重新执行这个单元格来刷新目录内容否则分享出来的目录可能是过时的。7. VSCode 里的 Jupyter 目录方案与跨平台同步问题最后再聊一下很多人关心的 VSCode 场景。我自己现在有相当一部分 dict 类的工作是在 VSCode 里完成的因为它集成了 Jupyter 内核、Git 版本管理和 AI 辅助插件体验非常顺滑。不过 VSCode 里的 Jupyter 目录功能有一个先天限制它默认读取的也是 Markdown 标题的层级结构但 VSCode 的 Jupyter 扩展并不支持老版 toc2 插件所以如果你在 VSCode 里打开一个用 toc2 插入过 TOC 单元格的 notebook那个目录单元格是可以正常显示和跳转的但你在 VSCode 里没法通过侧边栏看到类似 Notebook 老界面的目录面板。好在 VSCode 自己有一个隐藏技巧可以替代在命令面板CtrlShiftP里搜索Outline: Focus然后回车VSCode 会打开一个基于当前文件符号Outline的面板。对于.ipynb文件来说这个 Outline 面板会自动把 Markdown 标题按层级列出来点击同样可以跳转。虽然它不会像 toc2 那样自动展开成侧边栏但保留在资源管理器旁边足够了。如果你在 VSCode 和浏览器两个环境之间来回切换注意不要同时打开同一个.ipynb文件做编辑因为两边同时保存时很容易产生文件冲突。我自己踩过一次坑在 VSCode 里给 notebook 加了几个标题没有保存就切回浏览器编辑浏览器里使用的是旧版本文件等我保存后 VSCode 的未保存内容直接覆盖了浏览器里的修改。无论你多喜欢切换环境同一个文件在同一时间内只保留一个 Jupyter 服务持有它这是避免文件冲突的底线原则。有一说一如果你还停留在老版 Notebook 界面我强烈建议给你现在的工作流做一个升级评估先把目录插件和 TOC 单元格搞定这会直接影响你回溯工作内容的效率等习惯之后再尝试迁移到 JupyterLab 或 VSCode你会发现在不同环境里写 notebook 的体验差距其实没有想象中那么大。## 8. 我的个人建议到底选哪种目录方案最省心 写到这里可以收个尾了但我不想做什么总结归纳就分享一个我目前在用的组合方案算是实践经验。 我现在的主力环境是 JupyterLab偶尔用 VSCode。JupyterLab 里我直接用原生的 Table of Contents 面板不装任何额外插件同时保持所有 Markdown 标题手动带编号习惯比如 ## 2. 数据清洗、### 2.1 缺失值处理。这样做的好处有三个原生面板稳定不折腾、不管在什么环境里打开文件层级都不会乱、分享给同事时任何人都能通过标题结构快速理解内容。 如果你还在用老版 Notebook 界面那 toc2 插件确实是当前唯一的体面方案。安装时记住要在同一 Python 环境里执行 pip install 和 jupyter contrib nbextension install遇到页面没反应先开浏览器控制台看报错遇到异常导入错误优先检查环境依赖包版本这几个排查方向能覆盖掉九成以上的问题。 另外还有一个可以长期受益的小习惯写完 notebook 分享前从头到尾点一遍目录里的每个条目确认所有跳转都到位。这个动作看起来浪费时间但它能在 30 秒内暴露所有标题重复、标题层级错乱、锚点失效的问题。我在实际交付分析报告时靠这一步避免了至少三次被阅读者指出目录点了没反应的尴尬。 目录功能说到底是一个细节但这个细节决定了一份长 notebook 能不能被你自己和别人真正读进去。花十几分钟配置好之后每天省下的寻路时间绝不止这些。