Jupyter导出HTML详细步骤教程

本文详解了如何通过命令行工具 `jupyter nbconvert` 稳定、可控地将 Jupyter Notebook 导出为 HTML 文件，强调其相比界面操作的可靠性与可复现性：只需一条基础命令即可生成静态网页，添加 `--execute` 可嵌入运行结果，配合绝对路径、模板指定和资源嵌入参数（如 `--embed-images`）能完美支持 Matplotlib 和 Plotly 等图表；同时系统梳理了常见陷阱——如模板缺失、图表不显示、CSS 错乱及环境版本冲突，并给出精准排查与升级方案，最后提醒读者坚守“不手动修改 HTML”的工程原则，让导出过程真正成为可重复、可追踪、可交付的自动化环节。

直接用 jupyter nbconvert 命令就行，不用开界面、不依赖浏览器环境，也比在 Jupyter Lab 里点菜单导出更可控。

用命令行导出 HTML：最稳的路径

很多人卡在「点了 File → Download as → HTML」却没反应，其实是前端渲染失败或内核没响应；而 nbconvert 是纯后端转换，只要 notebook 文件能读，就能出 HTML。

• 基础命令：jupyter nbconvert --to html notebook.ipynb，生成同名 notebook.html
• 想带输出（含图表、打印结果）？必须加 --execute 参数，否则只转代码块，不跑单元格：jupyter nbconvert --to html --execute notebook.ipynb
• 输出目录用 --output-dir，别用相对路径如 ./out，容易因工作目录混乱失败；建议用绝对路径或先 cd 进目标文件夹
• 默认用内置模板，若需定制样式（比如去掉左栏、改字体），得配合 --template 指向自定义 .tpl 文件，但普通需求完全没必要碰

导出空白/报错 TemplateNotFound: basic 怎么办

这通常不是 notebook 问题，而是环境里 nbconvert 模板注册异常，尤其多 Python 环境（conda/virtualenv）混用时常见。

• 先确认版本：jupyter nbconvert --version，低于 7.0 的旧版对新内核兼容差，建议升级：pip install --upgrade jupyter nbconvert
• 报 TemplateNotFound 时，别急着重装，先运行：jupyter nbconvert --generate-config，再检查生成的 jupyter_nbconvert_config.py 里有没有误删或覆盖了 c.Exporter.template_name
• 临时绕过：加 --template basic 显式指定，能跑通说明是模板路径错位，不是缺文件
• Conda 用户特别注意：不同 env 的 jupyter 可能指向不同 nbconvert，用 which jupyter 和 python -m jupyter.nbconvert --version 双重验证实际调用的是哪个

导出 HTML 后图表不显示、CSS 错乱

本质是资源加载方式问题——Jupyter 默认把图片、CSS、JS 打包进 HTML 单文件（--no-prompt --embed-images），但某些绘图库（如 Plotly、Bokeh）默认生成外部 JS 调用，离线打开就挂了。

• Matplotlib 图表正常，但 Plotly 需加 --no-input --embed-images 并确保 notebook 里用了 plotly.offline.init_notebook_mode() 或 fig.show(renderer="html")
• 如果 HTML 打开后控制台报 require is not defined，大概率是用了 JupyterLab 插件式渲染（如 @jupyter-widgets/jupyterlab-manager），这种交互组件无法静态导出，得换用 voilà 或部署为服务
• 字体/排版异常？别动 HTML 源码，那是 nbconvert 渲染器写的；真正该调的是 --css-files 加自定义 CSS，或改 custom.css（位置见 jupyter --paths 输出的 config 目录）

真正麻烦的不是怎么导，而是导出后要不要再手动改 HTML —— 一旦你开始删