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 和 Pygmentspython--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-escapelatexmk-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进行专业代码高亮
使用 TikZexternal优化大型文档
配置.latexmkrc实现一键编译
学习biblatex+biber管理参考文献
探索beamer制作学术幻灯片