5.2 扩展与高级功能
5.2 扩展与高级功能
本节摘要：合并 SOURCE 6.1 扩展安装、常用 nbextensions 介绍，以及 5.3 远程资源、6.2 自定义配置的要点。核心是 jupyter_contrib_nbextensions 安装链与 TOC、Codefolding、ExecuteTime、Notify 等扩展选型。
上手前先明确
阅读完本节，你应当能够：
- 执行 pip install jupyter_contrib_nbextensions 与 contrib nbextension install
- 在 Nbextensions 标签页启用 Table of Contents、Codefolding 等
- 说明 Variable Inspector 与 ExecuteTime 如何帮助调试与 profiling
- 了解 JupyterLab 扩展与经典 nbextensions 的差异
一、安装 contrib nbextensions
SOURCE 6.1.1 标准两步：
pip install jupyter_contrib_nbextensions jupyter contrib nbextension install --user
重启 Jupyter Notebook 后出现 Nbextensions 标签，勾选即启用（需重载页面）。
二、SOURCE 推荐扩展
| 扩展 | 作用 |
|---|---|
| Table of Contents (2) | 侧栏目录，长 Notebook 必备 |
| Codefolding | 折叠代码格 |
| Autopep8 | 一键 PEP 8 格式化 |
| Variable Inspector | 浮窗看变量名与值 |
| ExecuteTime | 每格显示耗时 |
| Highlight selected word | 高亮同名符号 |
| Spellchecker | Markdown 拼写检查 |
| Notify | 长格跑完浏览器通知 |
| Collapsible Headings | 折叠标题下内容 |
SOURCE 为 TOC、Codefolding 等配了 Mermaid 示意——启用后实际 UI 在浏览器侧栏，不必在 Markdown 里重复画。
推荐优先启用的扩展
三、自定义配置
SOURCE 6.1.3：在 Nbextensions 里点扩展名可进配置——如 TOC 显示层级、Autopep8 规则。配置写入用户目录 json，可进 Git 团队共享（路径因 OS 而异，正文不写绝对路径）。
四、JupyterLab 扩展
SOURCE 6.x 亦提 JupyterLab 扩展管理器——Lab 4 与经典 Notebook 扩展不通用。团队若迁移 Lab，优先找 Lab 原生 equivalents（LSP、TOC、debugger）。
远程服务器（SOURCE 5.3 并入）：SSH 端口转发访问远端 Jupyter 时，扩展装在与 Notebook 服务同一 Python 环境——本地浏览器只渲染 UI。
⚠️ 常见坑：扩展装到 base conda 但内核是 venv——contrib 命令应对 jupyter 命令所在环境 执行。
💡 关键直觉：扩展改「界面效率」，不改算法复杂度——ExecuteTime 告诉你哪格该
%run进模块。
核心回顾
- jupyter_contrib_nbextensions 安装链
- TOC / Codefolding / ExecuteTime / Notify 高频四件
- Nbextensions 页配置
- Lab vs 经典扩展不互通
下一节 5.3 最佳实践与工作流 防 Notebook 变成不可维护巨型单文件。
扩展安装与内核的关系
jupyter_contrib_nbextensions 装的是前端 UI 扩展，但它由 jupyter 命令所在环境的 Python 驱动。常见错误：用 venv 的 pip 装包，却用 conda base 的 jupyter 启动，扩展在页面上永远不出现。排查口诀：pip 和 jupyter 必须来自同一个解释器。
python -m pip install jupyter_contrib_nbextensions python -m jupyter contrib nbextension install --user
用 python -m 前缀可以保证两个命令跑在同一个环境里。
常用扩展的取舍
- Table of Contents：长 Notebook 必装，节省滚动时间。
- ExecuteTime：帮你发现哪一格最慢，是性能分析的仪表盘。
- Codefolding：代码格很长时折叠查看，保留阅读结构。
- Variable Inspector：调试期看变量，比反复 %whos 直观。
- Notify：长任务跑完弹通知，避免一直盯着页面。
不需要一次装全。先装 TOC + ExecuteTime，跑一周再决定是否加其他，避免扩展互相冲突拖慢页面。
JupyterLab 与经典 Notebook 的差异
JupyterLab 4 已把 TOC、调试器做成内置或第一方扩展，语法高亮、LSP 也更好。如果团队计划从经典 Notebook 迁移，优先用 Lab 原生功能替代 nbextensions，不要在两套体系里各维护一份配置。迁移前在 Lab 里逐一验证你常用的扩展是否有等价物。
扩展配置进 Git 的注意点
nbextensions 配置写在用户目录的 JSON 里，不同机器的路径不同。团队共享配置时，把"要启用哪些扩展"写进 README，而不是提交用户目录文件——后者在换机时几乎必坏。
扩展故障排查
扩展装上不生效，按顺序查三处：
- 安装与启动是否同一环境（
python -m jupyter前缀）。 - 页面是否硬刷新（Ctrl+Shift+R 清缓存）。
- 内核是否重启（前端扩展部分依赖内核状态）。
还不行就看浏览器控制台的报错（F12 打开），把第一行红色错误复制进搜索引擎，通常比盲猜快。
启用的扩展越多越好吗
不是。每个扩展都会增加页面加载时间与潜在冲突面。经验做法：先装三个高频扩展（TOC、ExecuteTime、Codefolding）跑两周，需要再补。扩展是增强项，不是必需品——正确内核与干净结构永远是第一位的。
扩展与协作环境的协同
团队共享的扩展清单应写入 README，并注明安装命令与依赖环境。新人按清单装好后，优先体验 TOC 与 ExecuteTime 两个最常用的，其余按需启用。扩展统一的前提仍是内核统一——先把 1.1 节的环境问题解决，再谈扩展体验。
不装扩展也能提效的清单
扩展只是锦上添花。真正的提效来自：清晰的 Markdown 标题层级（导航不用插件也能看）、按"一格一事"拆分单元格（折叠需求自然减少）、长逻辑下沉模块（页面渲染压力变小）。先把这三件做扎实，扩展的作用才会被放大。
先文档后扩展
团队引入任何新扩展前，先在 README 写清楚：装什么、给谁用、解决什么问题、不装会怎样。文档先行能过滤掉大部分"看起来酷但没场景"的扩展，也保证装完之后有据可查。
环境升级的检查点
升级 Jupyter 或 Python 大版本后，花十分钟验证三件事：常用扩展是否还能启用、快捷键是否被重置、内核列表是否仍指向正确环境。这三项是升级后最容易出问题的点，提前检查能避免生产环境踩坑。