Python输出分析报告，Jupyter导出HTML/PDF教程

本文深入解析了如何用 Jupyter 的 nbconvert 工具专业、可控地导出高质量分析报告——HTML 优先用于交互分享，PDF 仅限正式交付；强调摒弃 Notebook 界面“下载为 HTML”的简陋方式，转而通过命令行精准控制（如 --no-input 剔除代码、--embed-images 避免图片丢失、--template basic 提升兼容性），并直击常见痛点：PDF 导出失败多因系统缺失 pdflatex 或编码配置不当，HTML 样式简陋则推荐导出后注入 CSS 而非硬套模板，同时详解 Plotly/Bokeh/Altair 等交互图表在导出中“消失”的根源与修复方案，助你告别空白页、方块字、404 图片和错位公式，真正产出开箱即用、美观可靠的技术报告。

用 nbconvert 命令行导出 HTML，别在 Notebook 里点“下载为”

Jupyter 自带的“File → Download as → HTML”生成的是带大量调试信息、无样式、无法自定义的原始页面，几乎不能当报告用。nbconvert 才是真正可控的导出方式，它默认调用内置模板，但支持指定主题、过滤输出、剔除代码单元等关键操作。

常见错误现象：nbconvert 导出空白页或报 TemplateNotFound 错误——通常因为没装 pip install jupyter_contrib_nbextensions 或漏了 --to html 参数；PDF 导出失败则大概率缺 pdflatex 环境。

• 基础命令：jupyter nbconvert --to html --no-input report.ipynb（--no-input 剔除代码块，只留输出和 Markdown）
• 加样式更稳：jupyter nbconvert --to html --no-input --template basic report.ipynb（basic 模板轻量、兼容性好，比默认 lab 模板更少报错）
• 想嵌入本地图片或 CSS？必须加 --embed-images，否则 HTML 里全是相对路径，打开即 404

导出 PDF 时 LaTeX 报错：不是 Notebook 的问题，是系统缺编译链

PDF 导出本质是把 Notebook 转成 LaTeX 再调 pdflatex 编译。Jupyter 不自带 LaTeX，所以 nbconvert --to pdf 失败，99% 是环境问题，不是代码写错了。

使用场景：需要打印、提交正式文档、插入公式且要求排版精准时才用 PDF；日常分享优先选 HTML —— 加载快、字体保真、图表交互保留。

• Mac 用户装 MacTeX（别用 BasicTeX，缺 ucs 包易报错）；Windows 用 MiKTeX（勾选“始终安装缺少的包”）
• 验证是否就绪：pdflatex --version 能返回版本号，且 which pdflatex 有输出
• 仍报 ! Package inputenc Error: Unicode char …？加参数：--pdf-engine=xelatex，并确保 Notebook 元数据里设了 "kernelspec": {"name": "python3", "language": "python"}

让 HTML 报告“看起来像报告”：改 CSS 比换模板更直接

官方模板（basic / classic）样式简陋，但硬套第三方模板（如 jupyter-sphinx）反而容易破坏数学公式渲染或交互图表。最可靠的方式是导出后手动注入 CSS，或用 --CSSHTMLHeader 注入内联样式。

性能影响：大报告（>50 个 cell）加复杂 CSS 动画会拖慢加载；兼容性上，@media print 规则对 PDF 导出无效，只作用于 HTML 浏览器打印。

• 快速美化标题和字体：jupyter nbconvert --to html --no-input --HTMLExporter.exclude_input=True --HTMLExporter.template_name=basic report.ipynb，再用 --HTMLExporter.extra_template_basedirs 指向含自定义 custom.css 的目录
• 更省事：导出后用 Python 读取 HTML 文件，用 BeautifulSoup 插入