命令行 jupyter nbconvert --to html 比 gui 导出更可靠，因其纯后端执行、不依赖浏览器、支持自动化与路径控制；需加 --execute --embed-images 才能导出含图表和公式的完整 html。
直接用 jupyter nbconvert --to html 命令，别点菜单栏“Download as”——后者常卡死、漏输出、不渲染公式，纯属误导。
为什么命令行比 GUI 导出更可靠
GUI 导出（File → Download as → HTML）本质是前端触发一个临时转换流程，依赖当前浏览器环境、内核响应状态和前端 JS 加载；一旦内核没响应、MathJax CDN 被拦截、或 notebook 里有异步 Plotly 图表，就容易生成空白页或只含代码框架的残缺 HTML。
而 jupyter nbconvert 是纯后端执行：读取 .ipynb JSON 结构 → 执行（若加 --execute）→ 渲染模板 → 写出 HTML 文件。只要文件能打开，就能出结果，不卡、不弹窗、不依赖浏览器。
- 适合自动化：可写进 CI 脚本、定时任务、Docker 构建阶段
- 路径可控：支持
--output-dir指定绝对路径，避免相对路径导致的“文件生成了但找不到”问题 - 失败可定位：报错信息明确，比如
TemplateNotFound: basic直接指向环境配置问题，不是 notebook 本身有 bug
导出带图表和公式的完整 HTML
默认命令 jupyter nbconvert --to html notebook.ipynb 只转结构，不运行代码，所以图表、print() 输出、LaTeX 公式都不会出现。
要嵌入实际执行结果，必须加 --execute；若还希望图片离线可用（比如双击打开 file:// 协议），再加 --embed-images：
jupyter nbconvert --to html --execute --embed-images notebook.ipynb
-
--execute：启动内核运行所有单元格，把输出（包括 matplotlib/plotly 图、表格、日志）固化进 HTML -
--embed-images：把 PNG/SVG 图片 Base64 编码写进 HTML，避免导出后图片路径失效 - Plotly 图表需额外配合
plotly.offline.init_notebook_mode()（旧版）或fig.write_html(..., include_plotlyjs='cdn')，否则交互功能丢失
中文路径、公式不显示、空白页的典型修复
常见现象：$$E=mc^2$$ 显示为原始文本、右键无 MathJax 菜单、HTML 打开一片空白——基本都和加载资源有关。
-
中文路径报错：Windows 或某些 shell 下，路径含中文会导致
nbconvert解析失败。改用英文路径，或显式用--output指定英文文件名：jupyter nbconvert --to html --output report.html notebook.ipynb -
公式不渲染：默认从 CDN 加载 MathJax，但
file://协议下因 CORS 被浏览器拦截。解决方法是本地化 MathJax：--html-mathjax-url="./mathjax/tex-chtml.js"（需提前下载 MathJax 到本地目录） -
空白页 + TemplateNotFound：多出现在 conda/virtualenv 混用环境。先运行
jupyter nbconvert --generate-config，再检查~/.jupyter/jupyter_nbconvert_config.py是否误删了c.Exporter.template_name = 'basic'；或临时加--template basic绕过
导出后还能不能手动改 HTML
能改，但不推荐——尤其别动内联脚本、data:image/png 的 Base64 图片块、或 MathJax 初始化逻辑。这些是 nbconvert 渲染时动态注入的，手动删改容易破坏交互或样式。
真正需要定制样式（比如隐藏代码块、调字体、改配色），应该走正向流程：
- 用
--no-input剔除代码单元：jupyter nbconvert --to html --no-input --execute notebook.ipynb - 用
--template指向自定义 Jinja2 模板（需提前写好.tpl文件） - 导出后注入 CSS：在 HTML
里加<style></style>块，比改 body 内元素安全得多
最易被忽略的一点：导出动作本身不保存 notebook 的当前状态。如果 notebook 里有未运行的单元格、未保存的修改，nbconvert 读的是磁盘上最后一次保存的内容——务必先 Ctrl+S 或 File → Save and Checkpoint。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
