导出 Notebook
完成分析后，通常需要将 Notebook 分享给不安装 Jupyter 的人，或提交为报告。Jupyter 支持多种导出格式。
通过菜单导出
打开 Notebook，点击 File → Download as，选择格式：
| 格式 | 文件扩展名 | 适用场景 |
|---|---|---|
| Notebook | .ipynb | 源文件，可继续编辑 |
| Python | .py | 提取代码，去除 Markdown 和输出 |
| HTML | .html | 静态网页，保留代码和输出，可直接浏览器打开 |
| Markdown | .md | 文档格式，便于 Git 查看 |
| PDF via LaTeX | 学术报告（需要安装 LaTeX） | |
| Reveal.js | .html（幻灯片） | 基于 Web 的演示幻灯片 |
使用 nbconvert 命令行
nbconvert 是更强大的导出工具，支持批量处理和自定义模板：
# 导出为 HTML（最常用） $ jupyter nbconvert --to html analysis.ipynb → analysis.html # 导出为 Python 脚本 $ jupyter nbconvert --to script analysis.ipynb → analysis.py # 导出为 PDF（需要安装 LaTeX + pandoc） $ jupyter nbconvert --to pdf analysis.ipynb # 导出并执行（先运行所有单元格，再导出） $ jupyter nbconvert --to html --execute analysis.ipynb # 批量导出整个目录 $ jupyter nbconvert --to html notebooks/*.ipynb # 导出时不包含代码，只保留输出和文本 $ jupyter nbconvert --to html --no-input analysis.ipynb
TIP
--execute 参数会先从头执行整个 Notebook，再导出。这是生成"可复现报告"的标准做法，常用于 CI/CD 中自动生成定期报告。
分享 Notebook
GitHub 自动渲染
将 .ipynb 文件推送到 GitHub，GitHub 会自动渲染成格式化的页面（包括图表和输出）。
# 在 push 前清除输出（减少 diff 噪音） $ pip install nbstripout $ nbstripout analysis.ipynb # 清除所有输出 # 或者安装 git hook，每次 commit 自动清除 $ nbstripout --install
WARNING
带有输出的 Notebook（尤其是含有 Base64 图片）可能非常大，且 git diff 难以阅读。推荐提交时使用 nbstripout 清除输出，但保留一份"已运行"的版本用于渲染展示。
NBViewer
nbviewer.org 可以在线渲染任何公开的 Notebook URL，无需安装 Jupyter：
- 将 Notebook 上传到 GitHub 或 Gist
- 访问
nbviewer.org - 输入 GitHub URL，即可生成可分享的渲染链接
Google Colab
Google Colab 是免费的云端 Jupyter 环境，无需安装：
- 访问
colab.research.google.com - 上传本地
.ipynb文件，或直接从 GitHub 打开 - 免费提供 GPU/TPU 资源，适合深度学习
JupyterLab：下一代界面
JupyterLab 是 Jupyter 的全新界面，是对经典 Notebook 的重大升级。
# 启动 JupyterLab
$ jupyter lab
JupyterLab vs 经典 Notebook
| 功能 | 经典 Notebook | JupyterLab |
|---|---|---|
| 多面板布局 | ❌ 每个文件独立标签页 | ✅ 可拖拽调整多面板 |
| 文件浏览器 | 仅主页可用 | 始终可见的侧边栏 |
| 终端 | 需要额外打开 | 直接嵌入界面 |
| 代码编辑器 | 仅 Notebook | 内置纯文本编辑器 |
| CSV 预览 | ❌ | ✅ 直接浏览 CSV 文件 |
| 目录树 | ❌ | ✅ 侧边栏显示文档大纲 |
| 扩展生态 | 有限 | 丰富的 npm 扩展 |
| 界面主题 | 有限 | 多种亮/暗主题 |
JupyterLab 特色功能
多面板布局
可以将两个 Notebook 并排显示，左边写代码，右边看结果；或者左边 Notebook，右边是终端：
- 右键点击标签页
- 选择 "Create New View for Notebook"
- 拖拽到侧边，形成分屏布局
命令面板
按 Ctrl+Shift+P（macOS: ⌘+Shift+P）打开命令面板，搜索任何操作，类似 VS Code 的体验。
变量检查器
安装 @jupyterlab/debugger 扩展后，可以在侧边栏实时查看所有变量的值，无需执行 %whos。
推荐扩展工具
| 工具 | 安装 | 功能 |
|---|---|---|
| nbstripout | pip install nbstripout | 提交前清除 Notebook 输出 |
| nbformat | pip install nbformat | 读写 .ipynb 文件的 Python API |
| papermill | pip install papermill | 参数化运行 Notebook（批量实验） |
| nbconvert | 已内置 | 格式转换 |
| jupyter_contrib_nbextensions | pip install | 经典 Notebook 扩展包（目录、代码折叠等） |
参数化 Notebook（papermill）
papermill 可以给 Notebook 中的变量注入参数，实现批量运行：
# 在 Notebook 中，给参数单元格打 "parameters" 标签 # (View → Cell Toolbar → Tags，添加 "parameters" 标签) date = "2026-03-01" # 这个单元格有 parameters 标签 symbol = "AAPL" # 从命令行注入参数并运行 $ papermill analysis.ipynb output/AAPL_march.ipynb \ -p date "2026-03-31" \ -p symbol "AAPL" # 批量运行，生成多份报告 $ for symbol in AAPL GOOG MSFT; do papermill analysis.ipynb output/${symbol}.ipynb -p symbol $symbol done
Notebook 质量检查与 CI/CD 集成
# 用 nbconvert 执行并检查是否报错（CI 中常用）
jupyter nbconvert --to html --execute analysis.ipynb \
--ExecutePreprocessor.timeout=600 \
--output-dir ./reports/
# 失败时 nbconvert 返回非零退出码，CI 可以捕获
# GitHub Actions 中的典型用法：# .github/workflows/notebook-check.yml
name: Notebook QA
on: [push]
jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: pip install jupyterlab nbconvert
- run: |
# 执行所有 Notebook，任何报错都会失败
jupyter nbconvert --execute --to html notebooks/*.ipynb
- uses: actions/upload-artifact@v4
with:
name: notebook-reports
path: notebooks/*.htmlnbval：Notebook 的单元格级测试
nbval 是一个 pytest 插件，将每个 code cell 作为测试用例：执行 cell，对比输出是否与保存的预期输出一致。安装：
pip install nbval；运行：pytest --nbval notebook.ipynb。特别适合需要可复现的科学计算 Notebook——当依赖库升级后，nbval 能检测是否产生了数值差异。用 # NBVAL_IGNORE_OUTPUT 注释标记允许输出变化的 cell（如时间戳）。定期报告自动化（Papermill + Cron）
结合 papermill 和系统 cron 任务，可以实现每日/每周自动生成数据报告。工作流：① 编写参数化的分析 Notebook（带 parameters 标签的单元格）；② cron 每天调用 papermill 注入当天日期参数；③ nbconvert 将执行后的 Notebook 转换为 HTML；④ 发送到邮件或发布到内网。这是将 Jupyter 从实验工具升级为自动化数据管道的常见模式。
nbconvert 的工作原理
nbconvert 的转换流程
nbconvert 读取 .ipynb（JSON 格式）文件，将每个 cell 的 source 和 outputs 通过 Jinja2 模板渲染为目标格式。HTML 模板生成带内联样式的网页，代码高亮通过 Pygments 实现；Python 脚本模板只提取 code cell 的 source，忽略 markdown 和输出；PDF 格式则先转换为 LaTeX，再编译为 PDF（需要系统安装 LaTeX 编译器）。
nbstripout 的 git 集成
nbstripout 通过 git filter 机制工作：在 git 暂存（add）时自动将 .ipynb 文件中的 outputs 和 execution_count 清零，只保留 source 代码。这样 git diff 和 git blame 都只显示代码变更，而不包含每次运行产生的不同图片/输出数据。团队使用时在项目根目录运行
nbstripout --install 配置 .git/config，每个成员安装后都会自动生效。papermill 的参数注入机制
papermill 找到 Notebook 中带有 "parameters" 标签的单元格，在其后插入一个新的单元格（带 "injected-parameters" 标签），用命令行传入的参数值覆盖原始参数变量的赋值。然后使用 nbconvert 执行整个 Notebook 并保存带输出的新文件。原始 Notebook 不被修改，每次执行产生一个新的输出 Notebook，便于追溯不同参数组合的实验结果。
本章小结
本章核心要点
- 导出格式选择：HTML 适合分享静态报告（无需 Python 环境即可浏览）；Python 脚本适合提取代码到生产系统；PDF 适合正式文档（需 LaTeX 环境）；Slides 用 reveal.js 生成幻灯片。日常分享首选 HTML，代码复用首选 Python。
- 在线分享方式：GitHub 自动渲染 .ipynb，但大型 Notebook 或含有交互控件时可能渲染失败；nbviewer (nbviewer.org) 是专门的渲染服务，支持通过 GitHub URL 查看；Google Colab 可以直接打开 GitHub 上的 .ipynb 进行交互式运行。
- 版本控制最佳实践：安装 nbstripout 并配置 git filter，提交前自动清除输出；使用 nbdime 进行 Notebook 专用的 diff 和 merge；提交信息中说明主要更改的 cell（如"优化 cell 7 的数据清洗逻辑"）。
- JupyterLab 的核心优势：多标签+分屏布局（同时查看多个 Notebook）；内嵌文件浏览器和终端；变量检查器侧边栏；更好的扩展生态。新项目建议直接用 JupyterLab，迁移成本几乎为零（命令改为 jupyter lab）。
- papermill 的自动化场景：定期报告生成（每天的日报 Notebook）、超参数扫描实验（批量不同参数组合）、CI/CD 中的数据测试。用 "parameters" 标签标记参数单元格，命令行 -p 注入值，实现 Notebook 即代码的可复现工作流。
导出与分享的常见陷阱
- 交互控件（ipywidgets）无法在 HTML 中使用：nbconvert 导出的 HTML 是静态的，所有 ipywidgets 滑块、按钮都会变成不可交互的静态截图。如果需要分享交互式 Notebook，使用 voila 将 Notebook 转为 Web 应用（保留交互），或使用 nbgitpuller 分享可执行的 Colab 链接。
- PDF 导出需要 LaTeX 环境：在没有安装 LaTeX（如 TeX Live 或 MiKTeX）的机器上，nbconvert --to pdf 会失败。替代方案：先导出为 HTML，再用浏览器的打印功能（Ctrl+P → 保存为 PDF）——这个方案不需要 LaTeX，且页面格式通常更美观。
- 大型 Notebook 的 GitHub 渲染超时：文件超过 10MB 或包含大量 Base64 图片的 Notebook，GitHub 渲染会超时显示"Sorry, something went wrong"。解决方案：提交前用 nbstripout 清除输出（减小文件大小），或用 nbviewer 链接代替直接预览。
完成！你已掌握 Jupyter Notebook 全貌
从基本概念、安装启动、单元格操作，到魔法命令、可视化、快捷键，再到导出分享和 JupyterLab，你已经系统掌握了 Jupyter Notebook 的全部核心功能。下一步，建议将日常数据分析工作迁移到 Jupyter，体验代码与文档一体化的高效工作流——以及 Restart & Run All 始终能复现结果的可靠感！