VSCode 或 Jupyter 的图形界面导出 PDF 失败，根本原因是未配置 LaTeX 环境且右键导出不执行单元格；必须通过命令行运行 jupyter nbconvert --to pdf --execute --pdf-engine=xelatex 并验证 pdflatex/xelatex 可用。
pdflatex 找不到、中文变方块、图表被截断、导出卡在“Exporting…”——这些问题不是你操作错了，而是 VSCode 或 Jupyter 的图形界面按钮绕过了关键控制点。直接点“Export as PDF”几乎必然失败，除非你已配好完整 LaTeX 环境且 notebook 已全部执行。
为什么 VSCode 右键导出 PDF 总是失败
VSCode 的 Jupyter 扩展不自带 pdflatex 或 xelatex，它只是调用系统命令行工具 jupyter nbconvert。没装 LaTeX 发行版时，你会看到错误：PDF export failed: Command 'pdflatex' not found，或者界面卡住不动。
更隐蔽的问题是：右键菜单默认**不重新运行单元格**。如果你之前没手动运行过，导出的 PDF 里全是空输出、NameError 或 “Output not found”。
- 图形按钮 ≠ 全自动流程，它只是封装了
nbconvert --to pdf命令，底层完全依赖环境和参数 - Windows 用户装
MiKTeX（选 Complete + 允许自动下载包）；macOS 用户装mactex（brew install --cask mactex）；Linux 用户装texlive-xetex等核心包 - 装完后务必在终端运行
xelatex --version或pdflatex --version验证，否则后续所有操作都无效
jupyter nbconvert --execute 是唯一可靠方式
必须用命令行加 --execute 参数强制运行所有单元格，这是避免空白图、变量未定义、路径报错的硬性前提。
典型命令：
jupyter nbconvert --to pdf --execute my_notebook.ipynb
-
--execute：逐单元执行，遇到错误默认中断；加--allow-errors可跳过个别失败单元 -
--no-input：隐藏代码块，只保留 Markdown 和输出（适合交付终稿） - 务必先
cd进 notebook 所在目录再执行命令，否则相对路径（如pd.read_csv("data.csv")）会报错 - 若 notebook 含中文，必须用
xelatex引擎（nbconvert默认可能调pdflatex），加参数：--pdf-engine=xelatex
中文支持不是加个字体就行，关键在引擎和模板
中文乱码或方块，本质是 LaTeX 编译器没加载中文字体支持宏包，跟 notebook 里是否用了思源宋体无关。
- Mac 上
mactex自带ctex和xeCJK，但需确保nbconvert调用的是xelatex（不是pdflatex） - Windows 上
MiKTeX安装时勾选 “Install missing packages on-the-fly”，首次编译会自动补全ctex、fontspec等 - 不要手动改
article.tplx；推荐新建自定义模板文件夹（如cn），含conf.json和继承base_template: "latex"的index.tex.j2，并在命令中指定：--template cn - 验证是否生效：导出后 PDF 中任意中文段落能正常显示，且数学公式（如
$\alpha + \beta = 1$）不混排错位
浏览器打印法仅限临时应急，不能替代 nbconvert
快捷键 Ctrl+P（Win/Linux）或 Cmd+P（macOS）→ “Save as PDF”，确实零配置，但它只是把当前网页快照转成 PDF。
- 动态内容（如 Plotly 交互图、ipwidgets 控件）完全丢失，只留静态图
- 长表格自动分页错乱，LaTeX 公式渲染质量差，页眉页脚不可控
- 代码块超出页面宽度时不会自动换行，常被截断
- 书签（outline）虽有，但层级混乱，无法跳转到具体标题
真正需要交付、归档、投稿的 PDF，必须走 nbconvert + xelatex 流程——它生成的是排版级 PDF，不是网页截图。
