Windows 安装与使用 XeLaTeX

一、前言

LaTeX 是学术界广泛使用的排版系统，而 XeLaTeX 是基于 XeTeX 引擎的 LaTeX 编译方式，它的核心优势在于：

原生支持 Unicode：无需额外配置即可处理中文、日文、韩文等多语言内容
直接使用系统字体：通过 fontspec 宏包调用 Windows 系统已安装的字体（如微软雅黑、Times New Roman）
现代字体技术支持：支持 OpenType、TrueType 等现代字体格式

对于中文用户而言，XeLaTeX 几乎是处理中文文档的首选引擎。

二、安装篇：Windows 下 TeX Live 的完整安装

2.1 选择发行版：TeX Live vs MiKTeX

Windows 平台主要有两个 LaTeX 发行版：

特性	TeX Live（推荐）	MiKTeX
跨平台	Windows / macOS / Linux	主要为 Windows
安装方式	完整镜像安装（约 3-9 GB）	基础安装 + 按需下载
包管理	`tlmgr` 命令行工具	MiKTeX Console GUI
更新周期	年度大版本 + 日常滚动更新	持续更新
社区支持	最广泛，CTAN 官方维护	活跃，Windows 友好
推荐场景	学术写作、中文文档、长期项目	快速上手、磁盘空间有限

强烈推荐新手选择 TeX Live，原因如下：

中文支持更完善（ctex 宏包等开箱即用）
避免 MiKTeX 首次编译时频繁弹窗安装缺失宏包的困扰
与各类编辑器（VS Code、TeXstudio）兼容性更好

2.2 TeX Live 2025/2026 安装步骤

步骤 1：下载安装镜像

访问国内镜像站下载（推荐）：

清华大学镜像：https://mirrors.tuna.tsinghua.edu.cn/CTAN/systems/texlive/Images/
中科大镜像：https://mirrors.ustc.edu.cn/CTAN/systems/texlive/Images/

下载 texlive2025.iso（或最新版本），文件大小约 4-5 GB。

步骤 2：挂载镜像并运行安装程序

方法一：GUI 安装（推荐新手）

右键点击下载的 .iso 文件 → 选择“装载”
在资源管理器中打开虚拟光驱（如 Z: 盘）
双击运行 install-tl-windows.bat
安装向导启动后，建议保持默认的 “完整安装方案”（Full Scheme）

方法二：命令行安装（适合精简安装）

# 在 PowerShell 或 cmd 中执行，Z: 替换为实际的虚拟光驱盘符
Z:\install-tl-windows.bat --no-gui

步骤 3：精简安装配置（可选）

如果磁盘空间有限（< 10 GB），可以在命令行安装时选择精简组件：

# 进入安装程序后，按 C 进入组件选择
# 可以取消的组件（根据需求）：
# - d: ConTeXt（另一种排版系统，与 LaTeX 无关）
# - e: Additional fonts（额外字体，可选）
# - i: Games typesetting（游戏排版）
# - I: Music packages（乐谱排版）
# - L: PSTricks（较老的绘图方案，可用 TikZ 替代）
# - N: Windows-only support programs（Linux 安装时无此选项）

精简后安装体积可控制在 3 GB 左右。

步骤 4：完成安装并配置环境变量

安装完成后，需要将 TeX Live 的 bin 目录添加到系统环境变量 PATH 中：

# 默认安装路径下的 bin 目录
C:\texlive\2025\bin\windows

# 添加到系统环境变量 PATH 的步骤：
# 1. 右键"此电脑" → 属性 → 高级系统设置
# 2. 环境变量 → 系统变量 → 找到 Path → 编辑
# 3. 新建 → 粘贴上述路径 → 确定

步骤 5：验证安装

打开 PowerShell 或 cmd，执行：

xelatex -v

如果正确输出版本信息（类似 XeTeX 3.141592653...），说明安装成功。

# 同时验证其他工具
tex -v          # 基础 TeX 引擎
latex -v        # LaTeX 引擎
pdflatex -v     # pdfLaTeX 引擎
lualatex -v     # LuaLaTeX 引擎
tlmgr --version # 包管理器

三、基础使用篇：第一个 XeLaTeX 文档

3.1 编辑器选择

编辑器	特点	推荐指数
VS Code + LaTeX Workshop	功能最强，免费，支持正向/反向搜索	⭐⭐⭐⭐⭐
TeXstudio	专为 LaTeX 设计，开箱即用	⭐⭐⭐⭐
TeXworks	TeX Live 自带，极简	⭐⭐⭐
Overleaf	在线编辑，无需本地安装	⭐⭐⭐⭐

推荐新手使用 VS Code + LaTeX Workshop，配置方法见下文。

3.2 创建第一个中文文档

新建文件 hello.tex：

\documentclass{ctexart}  % ctexart 是中文文章文档类

\title{我的第一个 XeLaTeX 文档}
\author{你的名字}
\date{\today}

\begin{document}

\maketitle

\section{引言}
这是第一段文字。XeLaTeX 原生支持中文，无需额外配置！

\section{数学公式}
行内公式：$E = mc^2$

行间公式：
\[
    \int_{-\infty}^{+\infty} e^{-x^2} \, dx = \sqrt{\pi}
\]

\section{结语}
\LaTeX{} 的排版效果非常专业。

\end{document}

3.3 编译文档

命令行编译：

# 基础编译（生成 PDF）
xelatex hello.tex

# 完整编译（含参考文献、交叉引用）
# 通常需要多次编译
xelatex hello.tex
xelatex hello.tex

VS Code + LaTeX Workshop 配置：

在项目文件夹下创建 .vscode/settings.json：

{
    "latex-workshop.latex.recipe.default": "latexmk (xelatex)",
    "latex-workshop.latex.autoBuild.run": "never",
    "editor.wordWrap": "on"
}

然后按 Ctrl+Alt+B 即可编译，按 Ctrl+Alt+V 预览 PDF。

3.4 使用系统字体

XeLaTeX 的强大之处在于可以直接使用 Windows 系统字体：

\documentclass{ctexart}
\usepackage{fontspec}

% 设置正文字体
\setmainfont{Times New Roman}  % 英文
\setsansfont{Arial}
\setmonofont{Consolas}

% 中文字体（ctex 宏包已自动处理）
% 如需手动设置：
% \setCJKmainfont{SimSun}     % 宋体
% \setCJKsansfont{SimHei}    % 黑体

\begin{document}
这是 Times New Roman 字体。
\textbf{这是粗体。}
\textit{这是斜体。}
\end{document}

四、进阶篇：`-shell-escape` 的使用

4.1 参数原理详解

-shell-escape（或 --shell-escape）是一个安全相关的编译参数。启用后，LaTeX 编译器可以执行外部系统命令。这在以下场景中至关重要：

使用场景	典型宏包/功能	说明
代码高亮	`minted`	调用 Python 的 Pygments 库进行语法高亮
外部图像处理	`tikz` 的 `external` 库	将 TikZ 图形编译为独立图片以加速后续编译
动态数据获取	`texosquery`	查询操作系统信息（如当前日期、文件列表）
自动图表生成	`gnuplot`	调用 Gnuplot 生成数学函数图像
字体缓存	`fontspec` 首次运行	某些情况下需要外部程序辅助字体处理

安全警告：-shell-escape 允许 LaTeX 执行任意系统命令。永远不要对来源不明的 .tex 文件启用此参数，以防恶意代码执行。

安全等级

模式	参数	行为
禁用（默认）	无	禁止所有外部命令
受限模式	（默认内部）	只允许白名单内的程序
完全启用	`-shell-escape`	允许所有外部命令
管道模式	`--enable-pipes`	允许管道命令（MiKTeX）

命令格式

# 标准格式
xelatex -shell-escape yourfile.tex

# 多个参数组合
xelatex -shell-escape -interaction=nonstopmode -file-line-error yourfile.tex

# 使用 latexmk 自动化编译（推荐）
latexmk -xelatex -shell-escape yourfile.tex

4.2 场景一：使用 `minted` 进行代码高亮

minted 是 LaTeX 中最强大的代码高亮宏包，底层依赖 Python 的 Pygments 库。

前置要求

# 确保已安装 Python 和 Pygments
python --version
pip install Pygments

示例文档

\documentclass{ctexart}
\usepackage{minted}

\begin{document}

\section{Python 代码示例}

\begin{minted}{python}
def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)

# 打印前 10 个斐波那契数
for i in range(10):
    print(f"F({i}) = {fibonacci(i)}")
\end{minted}

\section{C 语言示例}

\begin{minted}{c}
#include <stdio.h>

int main() {
    printf("Hello, XeLaTeX!\n");
    return 0;
}
\end{minted}

\end{document}

编译命令

# 必须添加 -shell-escape，否则报错：
# "Package minted Error: You must invoke LaTeX with the -shell-escape flag."
xelatex -shell-escape code-demo.tex

进阶：`minted` 自定义样式

\usepackage{minted}

% 设置全局样式
\setminted{
    frame=single,
    framesep=2mm,
    baselinestretch=1.2,
    fontsize=\small,
    linenos=true,      % 显示行号
    breaklines=true    % 自动换行
}

% 自定义颜色主题
\usemintedstyle{vs}  % 可选：default, vs, monokai, tango 等

4.3 场景二：TikZ `external` 库加速编译

对于包含大量 TikZ 图形的文档，每次编译都重新生成图形非常耗时。external 库可以将图形缓存为独立图片。

\documentclass{ctexart}
\usepackage{tikz}
\usetikzlibrary{external}

% 启用外部化（需要 -shell-escape）
\tikzexternalize[prefix=tikz-cache/]

\begin{document}

\begin{figure}[htbp]
\centering
\begin{tikzpicture}
    \draw[->] (-2,0) -- (2,0) node[right] {$x$};
    \draw[->] (0,-2) -- (0,2) node[above] {$y$};
    \draw[domain=-1.5:1.5, smooth, variable=\x, blue] 
        plot ({\x}, {\x*\x});
    \node at (1.5,2) {$y = x^2$};
\end{tikzpicture}
\caption{二次函数图像}
\end{figure}

\end{document}

编译命令：

# 首次编译会生成 tikz-cache/ 目录并缓存图形
xelatex -shell-escape tikz-demo.tex

# 后续编译直接读取缓存，速度大幅提升
xelatex -shell-escape tikz-demo.tex

4.4 场景三：动态生成图表（`gnuplot`）

\documentclass{ctexart}
\usepackage{pgfplots}
\pgfplotsset{compat=1.18}

\begin{document}

\begin{figure}[htbp]
\centering
\begin{tikzpicture}
\begin{axis}[
    title={$sin(x)$ 函数图像},
    xlabel=$x$, ylabel=$y$,
    xmin=-6.28, xmax=6.28,
    ymin=-1.5, ymax=1.5,
    grid=major
]
\addplot[blue, thick, samples=100] {sin(deg(x))};
\end{axis}
\end{tikzpicture}
\end{figure}

\end{document}

某些复杂的 pgfplots 图表需要 -shell-escape 来调用 gnuplot 进行计算。

4.5 场景四：使用 `texosquery` 获取系统信息

\documentclass{ctexart}
\usepackage{texosquery}

\begin{document}

当前操作系统：\TeXOSQueryName

当前日期：\today

\end{document}

注意：texosquery 需要 Java 环境，且配置较为复杂，属于高阶用法。

五、工作流进阶：自动化编译配置

5.1 `latexmk` 自动化编译

latexmk 是 Perl 脚本，可以自动处理多次编译、参考文献、交叉引用等：

# 基础用法
latexmk -xelatex yourfile.tex

# 启用 -shell-escape
latexmk -xelatex -shell-escape yourfile.tex

# 持续监视文件变化并自动编译
latexmk -xelatex -shell-escape -pvc yourfile.tex

# 清理辅助文件
latexmk -c

# 清理所有生成文件（包括 PDF）
latexmk -C

5.2 配置 `.latexmkrc` 文件

在项目根目录创建 .latexmkrc 文件（Perl 语法）：

# 使用 XeLaTeX 编译
$pdf_mode = 5;  # 5 = xelatex -> xdvipdfmx

# 配置 xelatex 参数
$xelatex = "xelatex -shell-escape -file-line-error -halt-on-error -interaction=nonstopmode -no-pdf -synctex=1 %O %S";

# 配置 xdvipdfmx 参数
$xdvipdfmx = "xdvipdfmx -q -E -o %D %O %S";

# 自动清理辅助文件（可选）
$clean_ext = "xdv log aux out toc nav snm vrb";

$pdf_mode = 5 是 XeLaTeX 的高效编译模式：先多次调用 xelatex 生成 .xdv 文件，最后调用 xdvipdfmx 一次性生成 PDF，比传统模式更快。

5.3 VS Code 完整配置

.vscode/settings.json 完整配置示例：

{
    // 默认使用 latexmk (xelatex) 编译
    "latex-workshop.latex.recipe.default": "latexmk (xelatex)",
    
    // 不自动编译，手动触发
    "latex-workshop.latex.autoBuild.run": "never",
    
    // 工具链配置
    "latex-workshop.latex.tools": [
        {
            "name": "xelatex",
            "command": "xelatex",
            "args": [
                "-shell-escape",
                "-synctex=1",
                "-interaction=nonstopmode",
                "-file-line-error",
                "%DOC%"
            ]
        },
        {
            "name": "latexmk",
            "command": "latexmk",
            "args": [
                "-xelatex",
                "-shell-escape",
                "-synctex=1",
                "-interaction=nonstopmode",
                "-file-line-error",
                "%DOC%"
            ]
        }
    ],
    
    // 编译方案（Recipes）
    "latex-workshop.latex.recipes": [
        {
            "name": "latexmk (xelatex)",
            "tools": ["latexmk"]
        },
        {
            "name": "xelatex",
            "tools": ["xelatex", "xelatex"]
        }
    ],
    
    // PDF 预览设置
    "latex-workshop.view.pdf.viewer": "tab",
    "latex-workshop.view.pdf.invertMode.enabled": "auto",
    
    // 编辑器设置
    "editor.wordWrap": "on",
    "editor.formatOnSave": false
}

5.4 处理大型项目：模块化编译

对于大型文档（如毕业论文），建议采用模块化结构：

project/
├── main.tex          # 主文档
├── chapters/
│   ├── chapter1.tex
│   ├── chapter2.tex
│   └── chapter3.tex
├── figures/
│   ├── fig1.png
│   └── fig2.pdf
├── references.bib    # 参考文献数据库
└── .vscode/
    └── settings.json

main.tex 示例：

\documentclass[12pt,a4paper]{ctexbook}

% 导言区
\usepackage{geometry}
\geometry{left=2.5cm, right=2.5cm, top=2.5cm, bottom=2.5cm}

\usepackage{graphicx}
\usepackage{amsmath}
\usepackage{hyperref}

% 参考文献
\usepackage[backend=biber,style=gb7714-2015]{biblatex}
\addbibresource{references.bib}

% 启用外部图形缓存（需要 -shell-escape）
\usepackage{tikz}
\usetikzlibrary{external}
\tikzexternalize[prefix=cache/]

\begin{document}

\frontmatter
\tableofcontents

\mainmatter
\include{chapters/chapter1}
\include{chapters/chapter2}
\include{chapters/chapter3}

\backmatter
\printbibliography

\end{document}

编译命令：

# 使用 latexmk 自动处理所有依赖
latexmk -xelatex -shell-escape -synctex=1 main.tex

六、常见问题与故障排除

6.1 “Package minted Error: You must invoke LaTeX with the -shell-escape flag”

原因：使用了 minted 等需要外部命令的宏包，但未启用 -shell-escape。

解决：

xelatex -shell-escape yourfile.tex

或在 VS Code 的 settings.json 中确保工具链包含 -shell-escape 参数。

6.2 “fontspec error: font not found”

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

解决：

# 查看系统可用字体（Windows）
fc-list : family

# 或在 LaTeX 中使用正确字体名称
\setmainfont{Times New Roman}  % 确保名称拼写正确

6.3 编译中文时显示乱码或报错

原因：未使用 XeLaTeX 编译，或文件编码不是 UTF-8。

解决：

确保使用 xelatex 而非 pdflatex
确保 .tex 文件保存为 UTF-8 编码（VS Code 右下角可查看/切换）
使用 ctex 文档类或宏包：\documentclass{ctexart}

6.4 “I can’t write on file xxx” 权限错误

原因：Windows 权限限制，或文件被其他程序占用。

解决：

以管理员身份运行终端
关闭正在预览的 PDF 文件
检查杀毒软件是否拦截了编译过程

6.5 编译速度过慢

优化建议：

优化手段	方法	效果
使用 `external` 缓存 TikZ	`\tikzexternalize`	⭐⭐⭐⭐⭐
使用 `draft` 模式	`\documentclass[draft]{...}`	⭐⭐⭐⭐
禁用实时预览	VS Code 设置 `autoBuild.run: "never"`	⭐⭐⭐
使用 `latexmk` 的 `-pvc`	持续编译模式	⭐⭐⭐
精简宏包加载	只加载必要的宏包	⭐⭐

6.6 MiKTeX 与 TeX Live 冲突

如果系统中同时安装了 MiKTeX 和 TeX Live，可能导致命令冲突。

解决：

# 查看当前使用的 xelatex 路径
where xelatex

# 确保 PATH 中 TeX Live 的 bin 目录在 MiKTeX 之前
# 或直接卸载其中一个

总结与进阶路线

新手入门路线

安装 TeX Live（完整安装）
安装 VS Code + LaTeX Workshop
编写第一个中文文档（使用 ctexart）
掌握基础编译命令（xelatex file.tex）
学习使用 latexmk 自动化编译

进阶提升路线

掌握 -shell-escape 的安全使用
使用 minted 进行专业代码高亮
使用 TikZ external 优化大型文档
配置 .latexmkrc 实现一键编译
学习 biblatex + biber 管理参考文献
探索 beamer 制作学术幻灯片