Sublarge

// 安全研究 · 2026-06-24

Windows 安装与使用 XeLaTeX

本文介绍了 Windows 下使用 XeLaTeX 的完整指南,主要内容包括: 安装篇:推荐使用 TeX Live 发行版,详细说明从镜像下载、安装配置到环境变量设置的全过程,并对比了 TeX Live 与 MiKTeX 的优缺点。 基础使用篇:指导创建第一个中文文档,推荐 VS Code + LaTeX Workshop 作为编辑器,展示基本文档结构和编译方法,介绍如何调用系统字体。 进阶篇:重点讲解 -shell-escape 参数的作用与安全注意事项,以 minted 宏包为例演示代码高亮的实现方法。

一、前言

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:下载安装镜像

访问国内镜像站下载(推荐):

下载 texlive2025.iso(或最新版本),文件大小约 4-5 GB。

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

方法一:GUI 安装(推荐新手)

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

方法二:命令行安装(适合精简安装)

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

步骤 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 安装时无此选项)
text8 行

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

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

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

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

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

步骤 5:验证安装

打开 PowerShell 或 cmd,执行:

xelatex -v
powershell1 行

如果正确输出版本信息(类似 XeTeX 3.141592653...),说明安装成功。

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

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

3.1 编辑器选择

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

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

3.2 创建第一个中文文档

新建文件 hello.tex:

3.3 编译文档

命令行编译:

# 基础编译(生成 PDF)
xelatex hello.tex

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

VS Code + LaTeX Workshop 配置:

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

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

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

3.4 使用系统字体

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


四、进阶篇:-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
powershell8 行

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

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

前置要求

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

示例文档

编译命令

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

进阶:minted 自定义样式

\usepackage{minted}

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

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

4.3 场景二:TikZ external 库加速编译

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

编译命令:

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

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

4.4 场景三:动态生成图表(gnuplot)

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

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

\documentclass{ctexart}
\usepackage{texosquery}

\begin{document}

当前操作系统:\TeXOSQueryName

当前日期:\today

\end{document}
latex10 行

注意: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
powershell14 行

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";
perl11 行

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

5.3 VS Code 完整配置

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

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

对于大型文档(如毕业论文),建议采用模块化结构:

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

main.tex 示例:

编译命令:

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

六、常见问题与故障排除

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

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

解决:

xelatex -shell-escape yourfile.tex
powershell1 行

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

6.2 “fontspec error: font not found”

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

解决:

# 查看系统可用字体(Windows)
fc-list : family

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

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 之前
# 或直接卸载其中一个
powershell5 行

总结与进阶路线

新手入门路线

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

进阶提升路线

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

推荐资源


本文基于 TeX Live 2025/2026 版本编写,适用于 Windows 10/11 系统。如有更新或错误,欢迎指正。

原文 https://blog.csdn.net/2301_79518550/article/details/162278513