VSCode中配置Jupyter插件,实现Jupyter Notebook转PDF

为什么需要这套配置

常见痛点

如果你尝试过在 VSCode 中将 Jupyter Notebook 导出为 PDF，可能遇到过这些问题：

• 中文乱码：导出的 PDF 中文字显示为方框或乱码
• 缺少 LaTeX：提示找不到 xelatex 或 pdflatex
• 字体问题：即使安装了 LaTeX，中文字体配置也很麻烦
• 环境混乱：不知道该在哪个 conda 环境安装依赖

本教程的解决方案

通过本教程，你将搭建一套完整的工具链：

Jupyter Notebook (.ipynb)
        ↓ nbconvert
LaTeX 源文件 (.tex)
        ↓ xelatex + ctex
PDF 文件 (支持中文)

核心组件：

组件	作用
TeX Live	提供 xelatex 编译器
nbconvert	将 Notebook 转换为 LaTeX
ctex 宏包	提供中文排版支持
自定义字体	确保中文正确显示

---

本教程环境示例

本教程基于以下实际环境编写，已验证可行：

项目	配置
操作系统	Ubuntu 24.04 LTS
IDE	VSCode / Cursor / Windsurf（Remote SSH）
Conda	miniforge3，路径 /home/cpu/miniforge3
LaTeX	TeX Live 2023（APT 安装）
字体	Maple Mono NF CN（等宽编程字体，中英文统一）

关于 IDE：本教程以 VSCode 为例，但同样适用于 Cursor、Windsurf 等基于 VSCode 的 AI IDE。

---

第一部分：安装 TeX Live

TeX Live 是 LaTeX 的发行版，提供编译 Notebook 为 PDF 所需的 xelatex 引擎。

Ubuntu/Debian 系统

# 安装完整版 TeX Live（约 5GB，包含所有宏包）
sudo apt install texlive-full

命令解释：

• texlive-full：完整版 TeX Live，包含所有宏包和字体，避免后续缺包问题

磁盘空间紧张？ 可以选择精简安装：

sudo apt install texlive texlive-latex-extra texlive-lang-chinese texlive-xetex latexmk

精简版约 500MB，但后续可能遇到缺包问题。

验证安装

# 检查 xelatex（中文编译必备）
xelatex --version

# 检查 latexmk（自动化编译工具）
latexmk --version

预期输出：

XeTeX 3.141592653-2.6-0.999995 (TeX Live 2023/Debian)
Latexmk, John Collins, 31 Jan. 2024. Version 4.83

---

第二部分：安装中文字体

方案一：使用系统自带字体

Ubuntu 可以安装开源中文字体：

# 安装 Google Noto CJK 字体（推荐）
sudo apt install fonts-noto-cjk fonts-noto-cjk-extra

# 刷新字体缓存
fc-cache -fv

方案二：使用自定义字体（本教程示例）

本教程使用 Maple Mono NF CN 字体，这是一款支持中英文的等宽编程字体，中英文统一使用。

假设字体已安装在 /usr/local/share/fonts/MapleMono-NF-CN/ 目录下：

# 刷新字体缓存
fc-cache -fv /usr/local/share/fonts/MapleMono-NF-CN

# 验证字体已被识别
fc-list | grep "Maple Mono NF CN"

预期输出：

/usr/local/share/fonts/MapleMono-NF-CN/MapleMono-NF-CN-Regular.ttf: Maple Mono NF CN:style=Regular
/usr/local/share/fonts/MapleMono-NF-CN/MapleMono-NF-CN-Bold.ttf: Maple Mono NF CN:style=Bold
...

重要：记住字体名称 Maple Mono NF CN，后面配置模板时会用到。

---

第三部分：创建专用 Conda 环境

为了不污染 base 环境，建议创建专门的 LaTeX 导出环境：

# 创建名为 latex 的环境，安装必要依赖
conda create -n latex python=3.11 jupyter nbconvert pandoc -y

# 激活环境
conda activate latex

# 验证安装
jupyter --version
jupyter-nbconvert --version
pandoc --version

组件说明：

包名	作用
jupyter	Jupyter 核心组件
nbconvert	Notebook 格式转换工具
pandoc	通用文档转换器

---

第四部分：修改 nbconvert 模板

这是关键步骤！默认的 nbconvert 模板不支持中文，需要修改 index.tex.j2 模板文件。

步骤 1：查找模板文件

# 在 latex 环境中查找模板
find ~/miniforge3/envs/latex -name "index.tex.j2"

示例输出：

/home/cpu/miniforge3/envs/latex/share/jupyter/nbconvert/templates/latex/index.tex.j2

步骤 2：备份原始模板

cp /home/cpu/miniforge3/envs/latex/share/jupyter/nbconvert/templates/latex/index.tex.j2 \
   /home/cpu/miniforge3/envs/latex/share/jupyter/nbconvert/templates/latex/index.tex.j2.bak

步骤 3：修改模板

使用文本编辑器打开 index.tex.j2，找到以下内容：

((*- block docclass -*))
\documentclass[11pt]{article}
((*- endblock docclass -*))

替换为：

((*- block docclass -*))
\documentclass[11pt]{article}
 \usepackage{fontspec, xunicode, xltxtra}
 \setmainfont{Maple Mono NF CN}
 \setmonofont{Maple Mono NF CN}
 \usepackage[UTF8,fontset=none]{ctex}
 \setCJKmainfont{Maple Mono NF CN}
 \setCJKsansfont{Maple Mono NF CN}
 \setCJKmonofont{Maple Mono NF CN}
((*- endblock docclass -*))

配置项说明

配置	作用
\setmainfont{Maple Mono NF CN}	设置英文主字体
\setmonofont{Maple Mono NF CN}	设置英文等宽字体（代码）
\usepackage[UTF8,fontset=none]{ctex}	加载 ctex 宏包，禁用默认字体集
\setCJKmainfont{Maple Mono NF CN}	设置中文主字体
\setCJKmonofont{Maple Mono NF CN}	设置中文等宽字体

字体名称必须与系统中安装的字体完全一致！ 可以用 fc-list 命令查看。

其他常用字体配置示例

使用 Noto 字体（开源推荐）：

\setmainfont{DejaVu Sans}           % 英文字体
\usepackage[UTF8,fontset=none]{ctex}
\setCJKmainfont{Noto Sans CJK SC}   % 中文字体

使用微软雅黑（Windows 字体）：

\setmainfont{Consolas}              % 英文字体
\usepackage[UTF8,fontset=none]{ctex}
\setCJKmainfont{Microsoft YaHei}    % 中文字体

---

第五部分：安装 VSCode 插件

在 VSCode 中安装以下插件：

必需插件

1. Jupyter（Microsoft 官方）

   • 提供 Notebook 编辑和运行功能
   • 提供导出为 PDF 的入口

2. Python（Microsoft 官方）

   • 提供 Python 语言支持

推荐插件

1. LaTeX Workshop（James Yu）
   • 提供 LaTeX 编辑和编译功能
   • 可单独编辑 .tex 文件

安装方式：

• 方式一：Ctrl+Shift+X 打开扩展市场搜索安装
• 方式二：Ctrl+P 输入 ext install ms-toolsai.jupyter

---

第六部分：验证配置

方式一：直接导出 PDF

1. 在 VSCode 中打开任意 .ipynb 文件
2. 确保选择了 latex 环境作为内核
3. 点击右上角的导出按钮（或右键菜单）
4. 选择 “Export to PDF”
5. 等待转换完成，检查生成的 PDF 文件

方式二：先导出 LaTeX 再编译

如果直接导出失败，可以分步操作：

1. 选择 “Export to LaTeX”
2. 生成的 .tex 文件用 LaTeX-Workshop 打开
3. 手动编译（Ctrl+Alt+B）
4. 查看编译日志排查问题

命令行方式

# 激活环境
conda activate latex

# 导出为 PDF（使用 xelatex 引擎）
jupyter-nbconvert --to pdf --pdf-engine=xelatex your_notebook.ipynb

---

常见问题与解决方案

问题 1：导出时提示找不到 xelatex

现象：

xelatex not found on PATH

解决方案：

1. 确认 TeX Live 已安装：

   which xelatex

2. 如果是 Remote SSH 环境，确保环境变量在 ~/.bash_profile 中配置（而非 .bashrc）

3. 重启 VSCode Server：

   • Ctrl+Shift+P → “Remote-SSH: Kill VS Code Server on Host…”

问题 2：中文显示为方框或乱码

原因： 模板中的字体在系统中不存在

解决方案：

1. 检查系统中文字体：

   fc-list :lang=zh

2. 修改 index.tex.j2 中的 \setmainfont{} 为已安装的字体名

3. 刷新字体缓存：

   fc-cache -fv

问题 3：提示缺少 LaTeX 宏包

现象：

! LaTeX Error: File `xxx.sty' not found.

解决方案：

# 安装完整版 TeX Live
sudo apt install texlive-full

# 或单独安装缺失的宏包
sudo apt install texlive-latex-extra

问题 4：多个 conda 环境的模板都需要修改

如果你有多个环境都安装了 nbconvert，需要分别修改每个环境的 index.tex.j2：

# 查找所有模板文件
find ~/miniforge3 -name "index.tex.j2"

# 输出示例：
# /home/cpu/miniforge3/envs/latex/share/jupyter/nbconvert/templates/latex/index.tex.j2
# /home/cpu/miniforge3/envs/jupyter-mcp-server/share/jupyter/nbconvert/templates/latex/index.tex.j2
# /home/cpu/miniforge3/pkgs/nbconvert-core-xxx/share/jupyter/nbconvert/templates/latex/index.tex.j2

建议修改所有找到的文件，确保兼容性。

---

与 LaTeX-Workshop 插件联动

如果你同时使用 LaTeX-Workshop 插件编写 .tex 文档，可以参考我的另一篇教程进行完整配置：

VSCode中配置LaTeX-Workshop插件,实现LaTeX编译为PDF

联动优势：

• Jupyter 导出的 .tex 文件可以用 LaTeX-Workshop 进一步编辑
• 共享同一套 TeX Live 环境和字体配置
• 统一的中文支持方案

---

总结

通过本教程，你已经配置好了完整的 Jupyter Notebook 转 PDF 环境：

1. TeX Live：提供 xelatex 编译引擎
2. 中文字体：Maple Mono NF CN（或其他中文字体）
3. latex conda 环境：隔离的 Python 环境，包含 nbconvert 和 pandoc
4. 修改后的模板：index.tex.j2 支持中文排版

现在你可以：

• 在 VSCode 中直接将 Notebook 导出为带中文的 PDF
• 先导出为 LaTeX，再用 LaTeX-Workshop 精细调整
• 使用命令行批量转换多个 Notebook

有问题或建议？欢迎留言！