VSCode/Jupyter Notebook导出ipynb为PDF报错解决指南（中文字符不显示及通用修复方案）

许多数据科学家和Python开发者在使用Jupyter导出PDF功能时，常遇到因中文字符引起的问题，例如导出的PDF中中文变成空白方框，或直接抛出LaTeX相关错误。这个问题在MacOS和Windows系统上均有发生，但通过正确的配置完全可以解决。本文将提供一套通用方案，涵盖MacOS PDF导出和Windows PDF导出两种环境，并针对中文字符不显示的根源进行剖析。

为什么ipynb转PDF会报错？

Jupyter Notebook默认通过LaTeX引擎将.ipynb文件转换为PDF。当文档中包含中文字符时，如果LaTeX环境没有配置中文支持，就会导致中文字符不显示或编译中断。常见的错误信息包括“! Undefined control sequence”或“CJK package missing”。无论你在VSCode内直接导出，还是通过Jupyter Notebook界面操作，根本原因都是一样的。

通用解决方案：安装LaTeX中文支持

解决Jupyter导出PDF中文问题的核心是让LaTeX能够处理中文。下面分别针对MacOS和Windows给出详细步骤。

MacOS下的配置方法

1. 安装MacTeX：访问MacTeX官网下载安装包（约4GB），或使用Homebrew安装：brew install --cask mactex。安装完成后需重启终端。
2. 安装中文字体：MacOS自带“苹方”等中文字体，LaTeX可通过fontspec宏包调用。但为了兼容性，建议安装Adobe Source Han Sans等开源字体。
3. 配置Jupyter使用xelatex：在终端生成配置文件：jupyter nbconvert --generate-config，然后编辑~/.jupyter/jupyter_nbconvert_config.py，添加：c.PDFExporter.latex_command = ["xelatex", "{filename}"]。这能确保LaTeX引擎正确渲染中文。

经过以上步骤，在VSCode中打开你的ipynb文件，点击右上角“导出”->“PDF”，应该就能正常生成包含中文的PDF了。若仍出现MacOS PDF导出错误，检查是否安装了完整版MacTeX（BasicTeX可能缺少必要宏包）。

Windows下的配置方法

1. 安装MiKTeX或TeX Live：推荐MiKTeX（轻量）或TeX Live（完整）。安装时务必勾选“安装缺失的宏包”选项。
2. 安装中文字体：Windows系统自带“微软雅黑”等字体，LaTeX可通过xeCJK宏包调用。建议安装思源黑体以增强兼容性。
3. 修改Jupyter配置使用xelatex：与MacOS类似，编辑jupyter_nbconvert_config.py，加入c.PDFExporter.latex_command = ["xelatex", "-interaction=nonstopmode", "{filename}"]。同时确保环境变量Path中包含MiKTeX的bin目录。

完成配置后，重启Jupyter或VSCode，再次尝试导出。如果依然报错，请检查LaTeX安装是否完整，特别是Windows PDF导出时常见的“! LaTeX Error: File "xeCJK.sty" not found”错误，这表示缺少xeCJK宏包，需通过MiKTeX Console安装。

替代方案：使用nbconvert配合模板

如果你不想折腾LaTeX，也可以使用nbconvert直接导出HTML再打印为PDF，但这种方法可能丢失一些格式。更推荐的方法是自定义模板，在模板中引入中文支持。创建文件article.tplx，添加如下内容：

((- extends "article.tplx" -))((* block docclass ))\documentclass[11pt]{{article}}\usepackage{{xeCJK}}\setCJKmainfont{{Source Han Sans CN}}(( endblock *))

然后在命令行执行：jupyter nbconvert --to pdf --template article.tplx your_notebook.ipynb。这种方法能精准控制中文字体，彻底解决中文字符不显示问题。

总结

通过安装完整的LaTeX发行版并配置xelatex引擎，无论你在MacOS还是Windows上，都可以顺利实现Jupyter导出PDF且中文字符完美显示。本文提供的方法经过大量用户验证，适用于VSCode和原生Jupyter Notebook环境。如果你在操作中遇到其他问题，欢迎在评论区留言交流。

关键词：Jupyter导出PDF、中文字符不显示、MacOS PDF导出、Windows PDF导出