Windows 安装与使用 XeLaTeX

一、前言LaTeX 是学术界广泛使用的排版系统而XeLaTeX是基于 XeTeX 引擎的 LaTeX 编译方式它的核心优势在于原生支持 Unicode无需额外配置即可处理中文、日文、韩文等多语言内容直接使用系统字体通过fontspec宏包调用 Windows 系统已安装的字体如微软雅黑、Times New Roman现代字体技术支持支持 OpenType、TrueType 等现代字体格式对于中文用户而言XeLaTeX 几乎是处理中文文档的首选引擎。二、安装篇Windows 下 TeX Live 的完整安装2.1 选择发行版TeX Live vs MiKTeXWindows 平台主要有两个 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 programsLinux 安装时无此选项精简后安装体积可控制在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 设计开箱即用⭐⭐⭐⭐TeXworksTeX 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 编译文档命令行编译# 基础编译生成 PDFxelatex hello.tex# 完整编译含参考文献、交叉引用# 通常需要多次编译xelatex hello.tex xelatex hello.texVS Code LaTeX Workshop 配置在项目文件夹下创建.vscode/settings.json{latex-workshop.latex.recipe.default:latexmk (xelatex),latex-workshop.latex.autoBuild.run:never,editor.wordWrap:on}然后按CtrlAltB即可编译按CtrlAltV预览 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-interactionnonstopmode-file-line-error yourfile.tex# 使用 latexmk 自动化编译推荐latexmk-xelatex-shell-escape yourfile.tex4.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(fF({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{ framesingle, framesep2mm, baselinestretch1.2, fontsize\small, linenostrue, % 显示行号 breaklinestrue % 自动换行 } % 自定义颜色主题 \usemintedstyle{vs} % 可选default, vs, monokai, tango 等4.3 场景二TikZexternal库加速编译对于包含大量 TikZ 图形的文档每次编译都重新生成图形非常耗时。external库可以将图形缓存为独立图片。\documentclass{ctexart} \usepackage{tikz} \usetikzlibrary{external} % 启用外部化需要 -shell-escape \tikzexternalize[prefixtikz-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.tex4.4 场景三动态生成图表gnuplot\documentclass{ctexart} \usepackage{pgfplots} \pgfplotsset{compat1.18} \begin{document} \begin{figure}[htbp] \centering \begin{tikzpicture} \begin{axis}[ title{$sin(x)$ 函数图像}, xlabel$x$, ylabel$y$, xmin-6.28, xmax6.28, ymin-1.5, ymax1.5, gridmajor ] \addplot[blue, thick, samples100] {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.1latexmk自动化编译latexmk是 Perl 脚本可以自动处理多次编译、参考文献、交叉引用等# 基础用法latexmk-xelatex yourfile.tex# 启用 -shell-escapelatexmk-xelatex-shell-escape yourfile.tex# 持续监视文件变化并自动编译latexmk-xelatex-shell-escape-pvc yourfile.tex# 清理辅助文件latexmk-c# 清理所有生成文件包括 PDFlatexmk-C5.2 配置.latexmkrc文件在项目根目录创建.latexmkrc文件Perl 语法# 使用 XeLaTeX 编译$pdf_mode5;# 5 xelatex - xdvipdfmx# 配置 xelatex 参数$xelatexxelatex -shell-escape -file-line-error -halt-on-error -interactionnonstopmode -no-pdf -synctex1 %O %S;# 配置 xdvipdfmx 参数$xdvipdfmxxdvipdfmx -q -E -o %D %O %S;# 自动清理辅助文件可选$clean_extxdv 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,-synctex1,-interactionnonstopmode,-file-line-error,%DOC%]},{name:latexmk,command:latexmk,args:[-xelatex,-shell-escape,-synctex1,-interactionnonstopmode,-file-line-error,%DOC%]}],// 编译方案Recipeslatex-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.jsonmain.tex示例\documentclass[12pt,a4paper]{ctexbook} % 导言区 \usepackage{geometry} \geometry{left2.5cm, right2.5cm, top2.5cm, bottom2.5cm} \usepackage{graphicx} \usepackage{amsmath} \usepackage{hyperref} % 参考文献 \usepackage[backendbiber,stylegb7714-2015]{biblatex} \addbibresource{references.bib} % 启用外部图形缓存需要 -shell-escape \usepackage{tikz} \usetikzlibrary{external} \tikzexternalize[prefixcache/] \begin{document} \frontmatter \tableofcontents \mainmatter \include{chapters/chapter1} \include{chapters/chapter2} \include{chapters/chapter3} \backmatter \printbibliography \end{document}编译命令# 使用 latexmk 自动处理所有依赖latexmk-xelatex-shell-escape-synctex1 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”原因指定的字体在系统中不存在。解决# 查看系统可用字体Windowsfc-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实现一键编译学习biblatexbiber管理参考文献探索beamer制作学术幻灯片推荐资源《LaTeX入门》刘海洋中文 LaTeX 经典教材lshort-zh-cn免费的中文简明教程texdoc lshort-zh-cnCTeX 论坛https://www.ctex.orgLaTeX 工作室https://www.latexstudio.netTeX Stack Exchangehttps://tex.stackexchange.com本文基于 TeX Live 2025/2026 版本编写适用于 Windows 10/11 系统。如有更新或错误欢迎指正。