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

为什么需要这套 LaTeX 开发环境

在开始配置之前，让我们先聊聊为什么要在 VSCode 里写 LaTeX，以及这套环境能给你带来什么。

传统 LaTeX 写作的痛点

如果你之前用过 LaTeX，可能遇到过这些让人头疼的问题：

软件笨重：传统的 TeXstudio、TeXworks 等 IDE 界面老旧，启动慢，功能单一
环境割裂：写代码用 VSCode，写论文换 TeXstudio，来回切换心累
中文支持差：配置中文字体是个大坑，一不小心就乱码或编译失败
远程开发难：想在服务器上写 LaTeX？传统工具几乎无解
协作不便：多人协作时，环境配置不统一导致各种奇怪问题

VSCode + LaTeX-Workshop 带来的改变

通过本教程搭建的环境，你将获得以下体验：

统一的开发环境：无论是写代码、写文档还是写论文，都在同一个编辑器里完成
现代化的编辑体验：语法高亮、智能补全、代码片段、格式化，一应俱全
实时预览：保存即编译，PDF 预览窗口自动刷新
双向跳转：点击 PDF 跳到源码，点击源码跳到 PDF 对应位置（SyncTeX）
远程开发：通过 VSCode Remote SSH，可以在任何一台服务器上愉快地写 LaTeX
中文无忧：本教程会手把手教你配置中文支持，告别乱码

这套方案的技术架构

整个系统包含三个核心组件：

TeX Live (LaTeX 发行版)  →  提供编译引擎和宏包
        ↓
LaTeX-Workshop (VSCode 插件)  →  提供编辑和预览功能
        ↓
XeLaTeX + ctex (中文方案)  →  提供中文排版支持

简单来说：TeX Live 是”后厨”，负责把 .tex 源码”烹饪”成 PDF；LaTeX-Workshop 是”服务员”，负责在 VSCode 里呈现一切；XeLaTeX 是专门处理中文的”大厨”。

本教程适用场景

本教程专为以下情况设计：

你通过 VSCode Remote SSH 连接到一台 Ubuntu 服务器
服务器是全新安装的，还没有配置 LaTeX 环境
你希望在 VSCode 里获得现代化的 LaTeX 写作体验
你需要编写包含中文的文档（论文、报告、笔记等）

本教程环境示例：

项目	配置
操作系统	Ubuntu 24.04 LTS
连接方式	VSCode / Cursor / Windsurf 等 IDE 的 Remote SSH
插件路径	`~/.vscode-server/extensions/`、`~/.cursor-server/extensions/` 或 `~/.windsurf-server/extensions/`
Conda（可选）	miniforge3，路径 `/home/cpu/miniforge3`

关于 IDE 的说明：本教程以 VSCode 为例，但同样适用于 Cursor、Windsurf 等基于 VSCode 的 AI IDE。它们的插件系统和配置方式与 VSCode 基本一致，只是远程服务器上的目录名不同（如 .cursor-server、.windsurf-server）。后文提到的「VSCode」均可替换为你使用的 IDE。

相关资源：

LaTeX-Workshop 插件 - VS Code Marketplace
LaTeX-Workshop GitHub - 官方仓库和文档
Jupyter 插件 - 如果你还需要 Notebook 支持

第一部分：安装 TeX Live

TeX Live 是 LaTeX 的”心脏”——没有它，LaTeX-Workshop 只是个空壳。TeX Live 包含了编译 LaTeX 文档所需的一切：编译引擎（pdflatex、xelatex 等）、数千个宏包（用于实现各种排版功能）、以及配套工具。

为什么选择 TeX Live？

市面上有几种 LaTeX 发行版：TeX Live、MiKTeX、MacTeX 等。我们选择 TeX Live 的原因是：

跨平台：Linux、Windows、macOS 都能用，环境一致性好
包最全：完整安装包含 4000+ 宏包，基本不会遇到”缺包”问题
更新及时：每年发布新版本，宏包保持最新
官方推荐：LaTeX-Workshop 官方文档强烈推荐使用 TeX Live

方案一：使用 APT 安装（推荐新手）

这是最简单的安装方式，一行命令搞定，适合”我只想赶紧用起来”的你。

步骤 1：更新软件包列表

1	sudo apt update

命令解释：

sudo：以管理员权限执行（安装软件需要权限）
apt update：刷新软件源的索引，确保安装的是最新版本

步骤 2：安装 TeX Live 完整版

1	sudo apt install texlive-full

命令解释：

apt install：安装软件包
texlive-full：TeX Live 完整版，约 5GB

安装过程说明：

下载和安装需要 10-30 分钟，取决于网速
会占用约 5GB 磁盘空间
包含所有宏包，不会遇到”缺包”问题

磁盘空间紧张？ 可以选择精简安装：
1
sudo apt install texlive texlive-latex-extra texlive-lang-chinese texlive-xetex latexmk
这只安装基础组件 + 中文支持 + XeLaTeX + latexmk，约 500MB。

重要：latexmk 在 Ubuntu 上是独立的包，精简安装时必须显式包含，否则后面配置的 latexmk 相关 recipes 将无法使用。

如果你还需要使用 biber（现代参考文献工具，配合 biblatex 使用），也需要单独安装：
1
sudo apt install biber
精简安装后续可能遇到其他缺包问题，届时按提示安装即可。如果不想折腾，直接用 texlive-full 是最省心的选择。

步骤 3：验证安装

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

# 检查 pdflatex（英文编译常用）
pdflatex --version

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

预期输出： 如果看到版本号信息，说明安装成功。例如：

1	XeTeX 3.141592653-2.6-0.999995 (TeX Live 2023/Debian)

方案二：使用 ISO 镜像安装（获取最新版本）

如果你需要最新版的 TeX Live（比如 2025 版），或者 APT 源里的版本太旧，可以使用官方 ISO 镜像安装。

步骤 1：下载 ISO 镜像

1 2	# 使用清华镜像加速下载（国内速度快） wget https://mirrors.tuna.tsinghua.edu.cn/CTAN/systems/texlive/Images/texlive.iso

命令解释：

wget：命令行下载工具
清华镜像是国内最快的 CTAN 镜像站之一

文件约 4GB，下载时间取决于网速。

步骤 2：挂载并安装

# 创建挂载点
sudo mkdir -p /mnt/texlive

# 挂载 ISO 文件
sudo mount -o loop texlive.iso /mnt/texlive

# 进入目录并运行安装程序
cd /mnt/texlive
sudo perl ./install-tl --no-interaction

# 安装完成后卸载 ISO
cd ~
sudo umount /mnt/texlive

命令解释：

mount -o loop：将 ISO 文件当作虚拟光驱挂载
perl ./install-tl：运行 Perl 编写的安装脚本
--no-interaction：非交互模式，使用默认配置自动安装

步骤 3：配置环境变量（关键！）

ISO 安装的 TeX Live 不会自动添加到系统 PATH，需要手动配置。

重要提示： 对于 VSCode Remote SSH 连接，需要编辑 ~/.bash_profile 而非 ~/.bashrc。这是因为 VSCode 的远程扩展主机启动时读取的是非交互式 shell 配置。

1 2	# 编辑配置文件 nano ~/.bash_profile

首先，查看实际安装的版本目录：

1	ls /usr/local/texlive

假设输出是 2024（或其他年份），则在文件末尾添加：

# TeX Live 环境变量（请将 2024 替换为你实际的版本年份）
export PATH=/usr/local/texlive/2024/bin/x86_64-linux:$PATH
export MANPATH=/usr/local/texlive/2024/texmf-dist/doc/man:$MANPATH
export INFOPATH=/usr/local/texlive/2024/texmf-dist/doc/info:$INFOPATH

重要提示：TeX Live 的年份目录取决于你下载的 ISO 版本（如 2023、2024、2025），请务必根据 ls 命令的实际输出来填写，不要直接复制示例中的年份。

保存后使配置生效：

1	source ~/.bash_profile

为什么是 .bash_profile 而不是 .bashrc？

这是个常见的坑！VSCode/Cursor/Windsurf 等 IDE 的 Remote SSH 扩展主机启动时，运行的是“登录 shell”，它读取 .bash_profile；而普通终端通常是“交互式非登录 shell”，读取 .bashrc。详见 LaTeX-Workshop FAQ。

步骤 4：重启远程服务器（关键！）

仅仅 source 配置文件并不足以让 VSCode 的远程扩展主机生效。你需要彻底重启远程服务器：

按 Ctrl+Shift+P 打开命令面板
输入并选择 “Remote-SSH: Kill VS Code Server on Host…”
选择你的服务器
等待连接断开后，重新连接 Remote SSH

为什么要 Kill Server？

VSCode 的远程扩展主机是常驻进程，它在首次连接时读取环境变量。如果你只是“断开再连接”，服务器上的进程可能仍在运行，使用的还是旧的 PATH。只有 Kill 掉服务器进程，再重新连接，才能让新的环境变量生效。详见 LaTeX-Workshop FAQ。

对于 Cursor，命令是“Cursor: Kill Cursor Server on Host…”；对于 Windsurf，命令类似为“Windsurf: Kill Server on Host…”。

第二部分：安装中文字体

LaTeX 本身不包含中文字体。如果你的文档需要显示中文，必须确保系统安装了中文字体，并在 LaTeX 文档中正确引用。

为什么需要单独安装字体？

当你使用 XeLaTeX 编译中文文档时，它会调用系统字体。如果系统没有中文字体，你会看到两种结果：

编译报错：提示”Font ‘xxx’ not found”
乱码/方框：PDF 生成了，但中文显示为方框或乱码

步骤 1：安装开源中文字体

# 安装 Google Noto CJK 字体（推荐，覆盖中日韩三语）
sudo apt install fonts-noto-cjk fonts-noto-cjk-extra

# 安装文泉驿字体（备选）
sudo apt install fonts-wqy-microhei fonts-wqy-zenhei

命令解释：

fonts-noto-cjk：Google 开源的 Noto 字体，质量高，覆盖全
fonts-wqy-*：文泉驿字体，中文开源社区经典作品

字体选择建议：

字体名称	特点	适用场景
Noto Serif CJK SC	衬线字体，类似宋体	正文、论文
Noto Sans CJK SC	无衬线字体，类似黑体	标题、幻灯片
WenQuanYi Micro Hei	开源微米黑	通用场景

步骤 2：刷新字体缓存

1	fc-cache -fv

命令解释：

fc-cache：字体缓存工具
-f：强制刷新
-v：显示详细信息

步骤 3：查看已安装的中文字体

1	fc-list :lang=zh

命令解释：

fc-list：列出系统字体
:lang=zh：过滤出支持中文的字体

示例输出：

1 2	/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc: Noto Sans CJK SC:style=Regular /usr/share/fonts/opentype/noto/NotoSerifCJK-Bold.ttc: Noto Serif CJK SC:style=Bold

重要：记住这些字体名称，后面写 LaTeX 文档时会用到。

（可选）步骤 4：安装 Windows 字体

如果你的文档需要使用宋体（SimSun）、黑体（SimHei）等 Windows 字体，可以从 Windows 系统复制：

# 创建字体目录
sudo mkdir -p /usr/local/share/fonts/windows

# 将字体文件复制到该目录（需要你自己准备字体文件）
# 常用字体：simsun.ttc(宋体), simhei.ttf(黑体), simkai.ttf(楷体)

# 刷新缓存
sudo fc-cache -fv

版权提示：Windows 字体受版权保护，请确保你有合法使用权。开源字体（如 Noto）不存在此问题。

第三部分：安装 VSCode 插件

环境准备好了，现在让我们把 VSCode 变成一个强大的 LaTeX 编辑器。

核心插件：LaTeX Workshop

LaTeX Workshop 是 VSCode 上最流行的 LaTeX 插件，GitHub 上有 11.7k Star。它提供了你需要的一切功能：

语法高亮：让 LaTeX 代码五彩缤纷，易于阅读
智能补全：输入 \ 自动弹出命令提示
自动编译：保存文件自动触发编译
内置 PDF 预览：不用切换窗口，VSCode 里直接看 PDF
SyncTeX：源码和 PDF 双向跳转
错误提示：编译错误直接在编辑器里显示

安装方法（三选一）：

方法 1：通过扩展市场搜索（推荐）

在 VSCode/Cursor/Windsurf 中按 Ctrl+Shift+X 打开扩展市场
搜索 “LaTeX Workshop”
选择作者为 “James Yu” 的插件
点击“安装”

方法 2：通过 Quick Open 安装

按 Ctrl+P 打开 Quick Open 面板
输入以下内容并按回车：
1
ext install James-Yu.latex-workshop

注意：这个命令是在 VSCode 的 Quick Open 面板（Ctrl+P）中输入，而不是在终端里输入。如果你在终端里执行这个命令，会报错 “command not found”。

方法 3：通过命令行安装（适合脚本化）

如果你喜欢在终端中操作，可以使用 VSCode 的 CLI 工具：

# VSCode
code --install-extension James-Yu.latex-workshop

# Cursor
cursor --install-extension James-Yu.latex-workshop

# Windsurf
windsurf --install-extension James-Yu.latex-workshop

这个命令需要在本地终端执行，且需要确保 IDE 的 CLI 工具已添加到系统 PATH。参见 VSCode CLI 文档。

推荐插件：Jupyter（可选）

如果你还需要使用 Jupyter Notebook，可以一并安装 Jupyter 插件。这样可以实现：

在 VSCode 里运行 Notebook
将 Notebook 导出为 LaTeX/PDF

安装方法： 搜索 “Jupyter”，安装 Microsoft 官方插件。

验证插件安装

按 Ctrl+Shift+P 打开命令面板，输入 “LaTeX”，你应该能看到很多 LaTeX Workshop 的命令，如：

LaTeX Workshop: Build LaTeX project
LaTeX Workshop: View LaTeX PDF
LaTeX Workshop: Clean up auxiliary files

如果能看到这些命令，说明插件安装成功。

第四部分：配置 LaTeX-Workshop

LaTeX-Workshop 开箱即用，但如果你想获得更好的体验（尤其是中文支持），需要做一些配置。

理解配置的两个层面

LaTeX-Workshop 的核心配置有两个概念：

Tools（工具）：定义”怎么调用编译器”，比如用什么参数调用 xelatex
Recipes（配方）：定义”编译流程”，比如先运行 xelatex，再运行 bibtex，再运行两次 xelatex

打个比方：Tools 是”切菜”、”炒菜”、”装盘”这些单独的动作；Recipes 是”先切菜，再炒菜，最后装盘”这样的完整流程。

打开设置文件

推荐方式： 按 Ctrl+Shift+P，输入 “Preferences: Open User Settings (JSON)”，打开 settings.json 文件。这种方式适用于所有 IDE，无需关心具体路径。

如果你想直接编辑文件，路径如下（取决于你使用的 IDE）：

IDE	设置文件路径
VSCode	`~/.vscode-server/data/Machine/settings.json`
Cursor	`~/.cursor-server/data/Machine/settings.json`
Windsurf	`~/.windsurf-server/data/Machine/settings.json`

基础配置

以下是我推荐的基础配置，每一项都有详细注释：

{
    // ========== 自动编译设置 ==========
    // "onSave": 保存文件时自动编译（推荐）
    // "onFileChange": 文件变化时编译（更激进）
    // "never": 从不自动编译（手动党）
    "latex-workshop.latex.autoBuild.run": "onSave",

    // ========== 清理设置 ==========
    // 编译完成后自动清理辅助文件（.aux, .log 等）
    // 保持工作目录整洁
    "latex-workshop.latex.autoClean.run": "onBuilt",
    
    // 要清理的文件类型
    "latex-workshop.latex.clean.fileTypes": [
        "*.aux", "*.bbl", "*.blg", "*.idx", "*.ind",
        "*.lof", "*.lot", "*.out", "*.toc", "*.acn",
        "*.acr", "*.alg", "*.glg", "*.glo", "*.gls",
        "*.fls", "*.log", "*.fdb_latexmk", "*.snm",
        "*.nav", "*.synctex.gz"
    ],

    // ========== PDF 预览设置 ==========
    // "tab": 在 VSCode 标签页中预览（推荐）
    // "browser": 在系统浏览器中打开
    // "external": 使用外部 PDF 阅读器
    "latex-workshop.view.pdf.viewer": "tab",

    // ========== SyncTeX 设置 ==========
    // 编译完成后启用双向跳转
    "latex-workshop.synctex.afterBuild.enabled": true,

    // ========== 默认编译方案 ==========
    // 使用 XeLaTeX 作为默认（中文友好）
    "latex-workshop.latex.recipe.default": "XeLaTeX"
}

配置编译工具（Tools）

Tools 定义了每个编译器的调用方式。将以下配置添加到 settings.json：

{
    "latex-workshop.latex.tools": [
        {
            "name": "xelatex",
            "command": "xelatex",
            "args": [
                "-synctex=1",
                "-interaction=nonstopmode",
                "-file-line-error",
                "-output-directory=%OUTDIR%",
                "%DOC%"
            ],
            "env": {}
        },
        {
            "name": "pdflatex",
            "command": "pdflatex",
            "args": [
                "-synctex=1",
                "-interaction=nonstopmode",
                "-file-line-error",
                "-output-directory=%OUTDIR%",
                "%DOC%"
            ],
            "env": {}
        },
        {
            "name": "latexmk-xelatex",
            "command": "latexmk",
            "args": [
                "-synctex=1",
                "-interaction=nonstopmode",
                "-file-line-error",
                "-xelatex",
                "-outdir=%OUTDIR%",
                "%DOC%"
            ],
            "env": {}
        },
        {
            "name": "latexmk",
            "command": "latexmk",
            "args": [
                "-synctex=1",
                "-interaction=nonstopmode",
                "-file-line-error",
                "-pdf",
                "-outdir=%OUTDIR%",
                "%DOC%"
            ],
            "env": {}
        },
        {
            "name": "bibtex",
            "command": "bibtex",
            "args": [
                "%DOCFILE%"
            ],
            "env": {}
        },
        {
            "name": "biber",
            "command": "biber",
            "args": [
                "--input-directory=%OUTDIR%",
                "--output-directory=%OUTDIR%",
                "%DOCFILE%"
            ],
            "env": {}
        }
    ]
}

参数解释：

参数	含义
`-synctex=1`	生成 SyncTeX 文件，用于双向跳转
`-interaction=nonstopmode`	遇到错误不停下来等待输入，继续编译
`-file-line-error`	错误信息包含文件名和行号，便于定位
`%DOC%`	LaTeX-Workshop 占位符，代表文档路径（不含扩展名）
`%OUTDIR%`	输出目录
`%DOCFILE%`	文档文件名（不含路径和扩展名）

配置编译方案（Recipes）

Recipes 定义了编译流程。不同场景需要不同的流程：

{
    "latex-workshop.latex.recipes": [
        {
            "name": "XeLaTeX",
            "tools": ["xelatex"]
        },
        {
            "name": "PDFLaTeX",
            "tools": ["pdflatex"]
        },
        {
            "name": "latexmk (XeLaTeX)",
            "tools": ["latexmk-xelatex"]
        },
        {
            "name": "latexmk (PDFLaTeX)",
            "tools": ["latexmk"]
        },
        {
            "name": "XeLaTeX -> BibTeX -> XeLaTeX × 2",
            "tools": ["xelatex", "bibtex", "xelatex", "xelatex"]
        },
        {
            "name": "PDFLaTeX -> BibTeX -> PDFLaTeX × 2",
            "tools": ["pdflatex", "bibtex", "pdflatex", "pdflatex"]
        }
    ]
}

Recipe 选择指南：

Recipe	适用场景
XeLaTeX	中文文档，单次编译
PDFLaTeX	纯英文文档，单次编译
latexmk (XeLaTeX)	中文文档，自动处理交叉引用
XeLaTeX -> BibTeX -> XeLaTeX × 2	中文文档 + 参考文献（传统 BibTeX）

BibTeX vs Biber：如何选择参考文献工具？

BibTeX：传统工具，配合 \usepackage{natbib} 或原生 \bibliography 使用。大多数老教程和模板都用这个。

Biber：现代工具，配合 \usepackage{biblatex} 使用。功能更强大，Unicode 支持更好，但配置稍复杂。

简单原则：看你的 .tex 文件用的是什么宏包。如果是 biblatex，就用 Biber；否则用 BibTeX。如果你需要 Biber，记得安装它：sudo apt install biber。

为什么要编译多次？

LaTeX 的交叉引用（如 \ref{}、\cite{}）需要多次编译才能正确解析。第一次编译生成引用信息，后续编译才能正确显示。latexmk 工具可以自动处理这个问题。

第五部分：编写你的第一个 LaTeX 文档

配置完成！现在让我们写一个中文文档来验证环境是否正常工作。

创建测试文件

在 VSCode 中创建一个名为 test.tex 的文件，输入以下内容：

% !TEX program = xelatex
% 上面这行是 Magic Comment，告诉 LaTeX-Workshop 使用 xelatex 编译

\documentclass[12pt,a4paper]{article}

% ===== 中文支持 =====
% ctex 宏包是处理中文的瑞士军刀，自动配置字体和排版
\usepackage[UTF8]{ctex}

% ===== 字体设置（可选） =====
% 如果你想指定具体字体，取消下面的注释
% \usepackage{fontspec}
% \setmainfont{Noto Serif CJK SC}  % 主字体
% \setsansfont{Noto Sans CJK SC}   % 无衬线字体

% ===== 其他常用宏包 =====
\usepackage{amsmath}    % 数学公式增强
\usepackage{graphicx}   % 插入图片
\usepackage{hyperref}   % 超链接（目录可点击）
\usepackage{geometry}   % 页面设置

% ===== 页面设置 =====
\geometry{
    top=2.5cm,
    bottom=2.5cm,
    left=2.5cm,
    right=2.5cm
}

% ===== 文档信息 =====
\title{我的第一个 \LaTeX{} 文档}
\author{你的名字}
\date{\today}

% ===== 正文开始 =====
\begin{document}

\maketitle  % 生成标题

\begin{abstract}
这是一个使用 VSCode + LaTeX-Workshop 编写的中文文档示例。
如果你能看到这段文字，说明环境配置成功了！
\end{abstract}

\tableofcontents  % 生成目录
\newpage

\section{引言}

欢迎使用 \LaTeX{}！这是一个强大的排版系统，特别适合编写：
\begin{itemize}
    \item 学术论文
    \item 技术报告
    \item 数学公式
    \item 书籍和长文档
\end{itemize}

\section{数学公式示例}

\LaTeX{} 最强大的功能之一就是排版数学公式。

行内公式：质能方程 $E = mc^2$ 揭示了质量和能量的关系。

行间公式（带编号）：
\begin{equation}
    \int_{-\infty}^{\infty} e^{-x^2} \, dx = \sqrt{\pi}
\end{equation}

多行公式：
\begin{align}
    (a+b)^2 &= a^2 + 2ab + b^2 \\
    (a-b)^2 &= a^2 - 2ab + b^2
\end{align}

\section{总结}

恭喜你成功配置了 VSCode + LaTeX-Workshop 环境！

现在你可以：
\begin{enumerate}
    \item 在 VSCode 中愉快地写 \LaTeX{}
    \item 保存后自动编译
    \item 在内置预览器中查看 PDF
    \item 使用 SyncTeX 在源码和 PDF 间跳转
\end{enumerate}

\end{document}

编译文档

有多种方式触发编译：

自动编译：直接按 Ctrl+S 保存，如果配置了 autoBuild.run: "onSave"，会自动编译
快捷键：按 Ctrl+Alt+B
命令面板：Ctrl+Shift+P → 输入 “Build LaTeX project”
侧边栏：点击左侧的 TeX 图标 → Build LaTeX project

预览 PDF

编译成功后，查看 PDF：

快捷键：按 Ctrl+Alt+V
命令面板：Ctrl+Shift+P → “View LaTeX PDF”
侧边栏：点击 TeX 图标 → View LaTeX PDF

你应该能看到一个排版精美的中文 PDF 文档。

使用 SyncTeX 双向跳转

这是 LaTeX-Workshop 最酷的功能之一：

从源码跳到 PDF：在 .tex 文件中，把光标放在某行，按 Ctrl+Alt+J
从 PDF 跳到源码：在 PDF 预览中，按住 Ctrl 点击某处（或双击）

这个功能在写长文档时特别有用——你可以快速定位到需要修改的位置。

第六部分：与 Jupyter 插件联动（可选拓展）

说明：本节内容属于可选拓展，与 LaTeX-Workshop 的核心配置无关。如果你不使用 Jupyter Notebook，可以跳过本节。

另外，Jupyter 导出功能涉及 VSCode Jupyter 插件版本、nbconvert、pandoc 等多个组件，配置较为复杂。如果导出失败，通常不是 LaTeX-Workshop 的问题。

如果你同时使用 Jupyter Notebook 进行数据分析或科学计算，可以将 Notebook 导出为 LaTeX 或 PDF。

环境准备

确保已安装必要的工具：

# 使用 conda（如果你有 conda 环境）
conda activate base
conda install jupyter nbconvert pandoc

# 或使用 pip
pip install jupyter nbconvert

组件说明：

jupyter：Jupyter Notebook 核心
nbconvert：格式转换工具
pandoc：通用文档转换器

导出 Notebook 为 LaTeX

在 VSCode 中打开 .ipynb 文件后：

点击右上角的导出按钮（或右键菜单）
选择 “Export to LaTeX”
生成的 .tex 文件可以用 LaTeX-Workshop 进一步编辑

直接导出为 PDF

如果想跳过 LaTeX 中间步骤，直接生成 PDF：

选择 “Export to PDF”
nbconvert 会自动调用 LaTeX 编译

中文支持提示：默认的 nbconvert 模板对中文支持不完善。如需完美支持中文，请参考我的另一篇教程：VSCode中配置Jupyter插件,实现Jupyter Notebook转PDF

第七部分：常见问题与解决方案

在配置和使用过程中，你可能会遇到一些问题。这里整理了最常见的问题及解决方案。

问题 1：找不到 xelatex 命令

现象：

1	xelatex: command not found

原因： TeX Live 没有正确安装，或者没有添加到 PATH。

解决方案：

检查是否安装了 TeX Live：
1
which xelatex
如果没有输出，说明未安装或未配置 PATH。如果是 APT 安装的，重新安装：
1
sudo apt install texlive-xetex
如果是 ISO 安装的，检查 ~/.bash_profile 中的 PATH 配置是否正确。
重要：配置完成后，需要重启 VSCode 或重新连接 Remote SSH。

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

现象： PDF 生成了，但中文显示为方框 □□□ 或乱码。

原因： 字体问题——要么没装中文字体，要么 LaTeX 文档没正确配置。

解决方案：

确认使用的是 XeLaTeX 而非 PDFLaTeX（PDFLaTeX 不支持系统字体）
确认系统安装了中文字体：
1
fc-list :lang=zh | head -5
在文档中使用 ctex 宏包：
1
\usepackage[UTF8]{ctex}
确认源文件编码是 UTF-8（VSCode 右下角可以查看和切换）

问题 3：提示 “Font ‘xxx’ not found”

现象： 编译时报错找不到某个字体。

原因： 文档中指定的字体在系统中不存在。

解决方案：

查看系统安装了哪些字体：
1
fc-list :lang=zh
修改文档中的字体设置，使用已安装的字体名称。例如：
1
\setmainfont{Noto Serif CJK SC}
字体名称必须与 fc-list 输出的完全一致。

问题 4：编译卡住不动

现象： 点击编译后，进度条一直转，没有任何输出。

原因： 通常是 LaTeX 遇到错误，在等待用户输入。

解决方案：

确保配置了 -interaction=nonstopmode 参数
终止当前编译：Ctrl+Shift+P → “Kill LaTeX compiler process”
查看 Output 面板（选择 “LaTeX Workshop” 通道）了解详细错误
常见错误：
- 缺少 \end{document}
- 括号不匹配
- 使用了未安装的宏包

问题 5：PDF 预览空白

现象： PDF 预览窗口打开了，但显示空白。

原因： 可能是 PDF 没生成，或者预览器兼容性问题。

解决方案：

检查 PDF 文件是否存在：
1
ls -la *.pdf

尝试切换预览方式：

1	"latex-workshop.view.pdf.viewer": "browser"

检查是否有 GPU 加速相关问题（某些远程环境可能有此问题）

问题 6：环境变量在 Remote SSH 中不生效

现象： 在服务器终端里可以运行 xelatex，但 VSCode 里不行。

原因： VSCode Remote 扩展主机和普通终端读取不同的配置文件。

解决方案：

根据 LaTeX-Workshop 官方 FAQ：

将环境变量添加到 ~/.bash_profile 或 ~/.profile（而非 ~/.bashrc）
断开并重新连接 Remote SSH

如果还是不行，可以在 Tools 配置中直接指定完整路径：

{
    "name": "xelatex",
    "command": "/usr/local/texlive/2025/bin/x86_64-linux/xelatex",
    ...
}

第八部分：进阶配置

掌握了基础配置后，这里有一些进阶技巧可以进一步提升你的体验。

自定义快捷键

如果你不喜欢默认快捷键，可以在 keybindings.json 中自定义：

[
    {
        "key": "ctrl+alt+b",
        "command": "latex-workshop.build",
        "when": "editorTextFocus && editorLangId == 'latex'"
    },
    {
        "key": "ctrl+alt+v",
        "command": "latex-workshop.view",
        "when": "editorTextFocus && editorLangId == 'latex'"
    },
    {
        "key": "ctrl+alt+j",
        "command": "latex-workshop.synctex",
        "when": "editorTextFocus && editorLangId == 'latex'"
    }
]

使用外部 PDF 查看器（仅限有 GUI 的环境）

重要提示：外部 PDF 查看器需要服务器有图形界面环境（或配置了 X11 转发）。对于大多数 Remote SSH 场景（连接的是无 GUI 的服务器），外部查看器无法使用。请优先使用内置的 tab 或 browser 模式。

如果你的远程服务器有桌面环境，或者你在本地使用，可以配置外部 PDF 阅读器（如 Evince、Okular）：

{
    "latex-workshop.view.pdf.viewer": "external",
    "latex-workshop.view.pdf.external.viewerCommand": "evince",
    "latex-workshop.view.pdf.external.viewerArgs": [
        "%PDF%"
    ]
}

多文件项目

对于大型项目（如书籍、论文），通常会把内容拆分到多个 .tex 文件。

方法 1：Magic Comment

在每个子文件开头添加：

1	% !TEX root = ../main.tex

方法 2：配置 settings.json

1
2
3

{
    "latex-workshop.latex.rootFile.indicator": "\\documentclass"
}

这告诉 LaTeX-Workshop：包含 \documentclass 的文件就是主文件。

使用 Docker 编译（隔离环境，实验性功能）

如果不想在系统中安装 TeX Live，可以使用 Docker 容器进行编译。

注意：Docker 编译是 LaTeX-Workshop 的实验性功能，配置较为复杂，不建议新手使用。

前置条件：

服务器上已安装 Docker 并可正常运行
当前用户有权限运行 docker 命令（通常需要加入 docker 组）
选择的镜像包含你需要的编译工具（如 xelatex、latexmk）

配置示例：

{
    "latex-workshop.docker.enabled": true,
    "latex-workshop.docker.image.latex": "texlive/texlive:latest"
}

说明：

texlive/texlive:latest 是官方提供的完整版镜像，体积较大（约 4GB）
你也可以选择更小的镜像，但需要确保其包含你需要的工具
Docker 编译可能比本地安装慢，因为每次都需要启动容器

详见 LaTeX-Workshop Docker 文档。

参考资源

LaTeX-Workshop 官方 Wiki - 最权威的配置参考
TeX Live 官网 - TeX Live 下载和文档
CTEX 宏集手册 - 中文排版必读
lshort 中文版 - LaTeX 入门最佳教程
一份简短的 LaTeX 安装指南 - 安装问题参考

总结

通过本教程，你已经搭建了一套完整的 LaTeX 开发环境：

TeX Live：提供编译能力，是整个系统的基础
中文字体：让中文显示正常，告别乱码
LaTeX-Workshop：把 VSCode 变成强大的 LaTeX IDE
XeLaTeX + ctex：完美支持中文排版

现在，你可以在 VSCode 里享受现代化的 LaTeX 写作体验了：

写代码和写论文在同一个编辑器里
保存即编译，预览即时刷新
双向跳转，快速定位
远程服务器上也能流畅写作

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