VSCode/Jupyter Notebook中导出ipynb文件为PDF报错解决(中文字符不显示或报错)(MacOS和Windows均适用)

使用VSCode或Jupyter Notebook写完并执行完ipynb文件后，一般要导出为PDF便于分享查看：

ipynb 导出为 PDF

但在导出为PDF的过程中遇到了很多问题：

1. 未安装xelatex

2. 中文字符报错 / 输出的PDF中中文字符不显示

3. ipynb文件中markdown格式出现与latex语法冲突的字符

以此文章记录上述问题的解决过程。

1.xelatex 安装问题

ipynb文件导出为PDF的工作流程是这样的：

（使用nbconvert包）ipynb -> TeX -> PDF

所以如果没有安装TeX直接尝试转换的话是会报错的，

即提示没有安装xelatex (TeX)：

17:11:53.806 [error] If you have not installed xelatex (TeX), you will need to do so before you can export to PDF. For further instructions, please see https://nbconvert.readthedocs.io/en/latest/install.html#installing-tex. 

根据报错一直在搜如何安装xelatex，搜了半天单独安装这个可能不太好搞。点开报错中的链接发现安装macTeX即可。

（建议安装macTeX，不建议安装另一个精简版本的，搞不好又缺这个缺哪个的很麻烦）

macOS使用homebrew工具指令一键安装：

brew install mactex

macTeX体积比较大，建议在稳定的网络环境下安装，耐心安装完成后启动台会出现很多相关APP：

macTeX 安装完成后出现的 APP

 安装完成macTeX后，建议重启电脑，以让相关环境起效。

2. 中文字符不显示或报错问题

如果ipynb文件中不包含中日韩文字符，那么这个时候应该就可以直接进行导出PDF操作了。

如果ipynb文件中包含汉语字符(日韩字符)，输出的PDF文件中并不会显示汉字，并且产生的报错如下：

Missing character: There is no 相 (U+76F8) in font [lmroman10-bold]:mapping=tex- text;!

Missing character: There is no 关 (U+5173) in font [lmroman10-bold]:mapping=tex- text;!

Missing character: There is no 系 (U+7CFB) in font [lmroman10-bold]:mapping=tex- text;!

Missing character: There is no 数 (U+6570) in font [lmroman10-bold]:mapping=tex- text;!

TeX默认配置下是不支持处理中文字符的，所以无论是线上Overleaf工具写文档、本地编译LaTeX项目还是本文ipynb借助TeX导出PDF，如果需要处理中文字符，都需要进行额外配置。

ipynb借助nbconvert包完成ipynb转TeX再导出PDF的操作，所以需要对nbconvert的默认配置进行修改，以使其流程中的TeX支持中文处理。

博主的Python环境使用anaconda配置，所以nbconvert包的配置文件在下面的路径中：

/opt/anaconda3/share/jupyter/nbconvert/templates/latex/index.tex.j2

（路径仅供参考，如果你使用的是Windows或未通过anaconda管理Python环境可以参考这篇文章给出的路径）

使用文本编辑器（VSCode）打开上述文件index.tex.j2，将其中的

\documentclass[11pt]{article}

更改为： 

\documentclass[UTF8]{ctexart}

更改 nbconvert 中关于 LaTeX 模板的默认配置

保存文件、重启电脑。

如果不出意外的话，此时ipynb文件已经可以成功导出为PDF文件，并且正常显示中文字符：

成功导出的 PDF

3. ipynb markdown 与 latex 的语法冲突

在ipynb中的markdown块中编辑表格的时候，我添加了一个反斜杠字符“\”

反斜杠问题

这个字符在ipynb的markdown单元格中能够正常编译显示，

但在LaTeX中，这个符号“\”具有语法含义，代表着指令的开始，例如：

\subsection{}

所以在通过TeX导出PDF时会报错：

! Undefined control sequence. l.408 用户\商品 & 商品 1 & 商品 2 & 商品 3 & 商品 4 \\ ? ! Emergency stop. l.408

这是一个很基本的转义符问题，如果要正常显示符号“\”，只需要连续输入两个“\”即可，即“\\”：

反斜杠转义符

比较具有迷惑性的是，即使是因为错误转义符的原因出错，报错输出也会在最后补上一句安装TeX的提示：

17:11:53.806 [error] If you have not installed xelatex (TeX), you will need to do so before you can export to PDF. For further instructions, please see https://nbconvert.readthedocs.io/en/latest/install.html#installing-tex.

这让我忽视了真正的错误，让我排查了半天以为是TeX环境没装好 😅

最后吐槽一下LaTeX

但凡遇到有关LaTeX的环境问题，总绕不开中文字符配置。Overleaf在线编译、VSCode本地编译、Obsidian导出、还有这次的ipynb导出，来来回回重复感觉踩过不下十次坑了，终于决定这次把解决过程记录下来。