应使用绝对路径的 --output-dir 参数指定输出目录，或用 --output 指定完整路径和自定义文件名；相对路径易因工作目录不一致而失败，且 --output 与 --output-dir 不可混用。
导出 HTML 时怎么指定输出目录
直接用 --output-dir 参数就行，但路径必须是绝对路径。相对路径（比如 ./html_out 或 ../export）在多数环境下会失败——因为 nbconvert 的工作目录不一定是你当前 shell 所在目录，尤其在 CI/CD 或容器中更不可靠。
- 推荐做法：先
cd进 notebook 所在目录，再用绝对路径指定输出位置，例如：jupyter nbconvert --to html --output-dir /home/user/reports notebook.ipynb - 如果路径含空格或中文，务必用英文路径；
nbconvert对非 ASCII 字符支持不稳定，容易卡在文件打开阶段 - 注意：该参数只控制目录，不改文件名；生成的 HTML 默认和 notebook 同名（
notebook.html），想改名得额外加--output
怎么让导出的 HTML 文件名自定义
--output 参数用于指定完整输出路径+文件名，它会覆盖 --output-dir 的影响。如果你既要控制位置又要改名，就只用 --output，别混用两个参数。
- 正确写法：
jupyter nbconvert --to html --output /tmp/my_report.html notebook.ipynb - 错误写法：
jupyter nbconvert --to html --output-dir /tmp --output my_report.html notebook.ipynb→ 这样会报错或忽略--output-dir - 文件名里不能带扩展名以外的点（如
report.v1.html可以，report.2026.08.html在某些旧版本 nbconvert 中可能被截断）
为什么导出后 HTML 打不开或显示空白
常见原因是资源路径没嵌入，尤其是图表、本地图片、MathJax 公式等依赖外部加载的内容。默认导出的 HTML 是“链接式”的，所有图片、JS、CSS 都是相对路径引用，一旦挪动文件或离线打开就会 404。
- 加
--embed-images：把 PNG/JPEG 图片 base64 编码进 HTML，避免图片丢失 - 公式渲染问题？加
--html-mathjax-url指向本地 MathJax（比如file:///usr/share/mathjax/MathJax.js），否则 CDN 失效时公式全变源码 - 空白页还可能是 notebook 内核没运行过，没输出内容；此时必须加
--execute，否则只转代码块，不执行也不渲染输出
配置全局默认导出路径靠谱吗
nbconvert 没有类似 jupyter_notebook_config.py 那样的全局导出路径配置项。所谓“默认路径”其实是 shell 当前工作目录，而它每次执行都可能不同——所以硬编码路径比依赖“默认”更可控。
立即学习“前端免费学习笔记（深入）”；
- 别试图改
jupyter_nbconvert_config.py来设默认输出目录，这个文件不支持output_dir这类选项 - 真要批量处理，建议写个 shell 脚本封装常用参数，比如：
nb2html() { jupyter nbconvert --to html --execute --embed-images --output "$1.html" "$1.ipynb"; } - 最容易被忽略的一点：导出前确认 notebook 已保存。nbconvert 读的是磁盘文件，不是浏览器里未保存的修改
