LaTeX Windows 环境配置指南（TeX Live + VS Code）

写学术论文、课程作业或技术文档时，本地编译 LaTeX 比依赖在线服务更稳定可控，也能离线工作。本指南目标：在新电脑上快速搭好一个本地 LaTeX 编译环境，用 VS Code 编辑、编译、预览 PDF。采用 TeX Live（最小版 scheme-small）+ VS Code LaTeX Workshop 方案，默认编译引擎用 pdflatex（纯英文/数学公式的标准引擎；含参考文献用 bibtex）。下载量约 400 MB（完整版约 5 GB）。

〇、方案概览

组件	作用
TeX Live	LaTeX 发行版（含 pdflatex、xelatex、latexmk、bibtex 等编译器）
scheme-small	最小安装方案
VS Code	编辑器
LaTeX Workshop	VS Code 扩展

引擎怎么选：纯英文 / 数学公式（含 ACM / ASPLOS 的 acmart 模板）用 pdflatex；需要中文或系统字体（fontspec）时用 xelatex（见「附录 A」）。

一、下载 TeX Live 安装器

# 创建目录并下载
$dir = "$env:USERPROFILE\texlive-install"
New-Item -ItemType Directory -Force $dir | Out-Null
curl.exe -L -o "$dir\install-tl.zip" `
  "https://mirrors.tuna.tsinghua.edu.cn/CTAN/systems/texlive/tlnet/install-tl.zip"

# 解压
Expand-Archive -Path "$dir\install-tl.zip" -DestinationPath "$dir\installer" -Force

解压后记住安装器目录名（形如 install-tl-2026xxxx），后面要用。

二、编写安装配置文件（免交互）

在安装器目录下新建 texlive.profile 文件，内容如下：

selected_scheme scheme-small
TEXDIR C:/Users/<你的用户名>/texlive/2026
TEXMFCONFIG ~/.texlive2026/texmf-config
TEXMFHOME ~/texmf
TEXMFLOCAL C:/Users/<你的用户名>/texlive/texmf-local
TEXMFSYSCONFIG C:/Users/<你的用户名>/texlive/2026/texmf-config
TEXMFSYSVAR C:/Users/<你的用户名>/texlive/2026/texmf-var
TEXMFVAR ~/.texlive2026/texmf-var
instopt_adjustpath 1
instopt_adjustrepo 1
tlpdbopt_autobackup 1
tlpdbopt_install_docfiles 0
tlpdbopt_install_srcfiles 0

关键说明：
把 <你的用户名> 换成真实用户名。
scheme-small = 最小方案（纯英文/公式）。如需中文，改成 scheme-full 或装完后再补装（见「附录 A」）。
tlpdbopt_install_docfiles 0 和 srcfiles 0 = 不装文档和源码，省磁盘空间（省约 1 GB）。
instopt_adjustpath 1 = 自动加入系统 PATH。实测 PATH 可能不立即生效（未重启/未刷新终端），故本指南后续一律用绝对路径调用编译器，最稳。

三、运行安装（从镜像下载）

在 PowerShell 中执行（注意：--% 停止解析符避免 PowerShell 5.1 破坏 &&）：

$dir = "$env:USERPROFILE\texlive-install\installer\install-tl-20XXXXXX"  # 换成实际目录名
cmd /c --% "cd /d $dir && install-tl-windows.bat --profile texlive.profile --repository https://mirrors.tuna.tsinghua.edu.cn/CTAN/systems/texlive/tlnet/ --no-interaction"

注意：--% 后面的字符串要原样写死绝对路径（不能用 $dir 变量），例如：

cmd /c --% "cd /d C:\Users\MLTZ\texlive-install\installer\install-tl-20260814 && install-tl-windows.bat --profile texlive.profile --repository https://mirrors.tuna.tsinghua.edu.cn/CTAN/systems/texlive/tlnet/ --no-interaction"

安装约 3–5 分钟（清华镜像，400 MB）。完成后会看到「欢迎进入 TeX Live 的世界！」。

四、安装 VS Code 和扩展

下载安装 VS Code：https://code.visualstudio.com/
命令行一键安装 LaTeX Workshop 扩展：

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

（或打开 VS Code → 扩展商店 Ctrl+Shift+X → 搜索 LaTeX Workshop → 安装）

五、配置 VS Code 编译链

打开 VS Code 设置文件（Ctrl+Shift+P → 输入 Preferences: Open User Settings (JSON)），写入以下配置（保留原有内容）：

{
  // —— 以下为 LaTeX 配置 ——
  // 编译产物输出到 build/ 子目录，根目录只留源码
  "latex-workshop.latex.outDir": "%DIR%/build",
  "latex-workshop.latex.clean.subfolder.enabled": true,

  "latex-workshop.latex.recipes": [
    {
      "name": "pdflatex ➞ bibtex ➞ pdflatex×2",
      "tools": ["pdflatex", "bibtex", "pdflatex", "pdflatex"]
    },
    {
      "name": "pdflatex only",
      "tools": ["pdflatex"]
    }
  ],
  "latex-workshop.latex.tools": [
    {
      "name": "pdflatex",
      "command": "C:/Users/<你的用户名>/texlive/2026/bin/windows/pdflatex.exe",
      "args": [
        "-synctex=1",
        "-interaction=nonstopmode",
        "-file-line-error",
        "-output-directory=%OUTDIR%",
        "%DOC%"
      ]
    },
    {
      "name": "bibtex",
      "command": "C:/Users/<你的用户名>/texlive/2026/bin/windows/bibtex.exe",
      "args": ["%OUTDIR%/%DOCFILE%"]
    }
  ]
}

为什么用绝对路径：即使系统 PATH 没刷新（未重启电脑），VS Code 也能直接找到编译器，稳定可靠。 outDir 的两个要点：① 必须设置 latex-workshop.latex.outDir，并且 ② 在 pdflatex 的 args 里写 -output-directory=%OUTDIR%、bibtex 的 args 写 %OUTDIR%/%DOCFILE% —— 光设 outDir 变量而不用占位符，bibtex 会找不到 .aux 文件。需要中文时，把上面的 pdflatex 换成 xelatex（命令路径改 xelatex.exe），见「附录 A」。

六、验证编译

新建 test.tex：

\documentclass{article}
\usepackage{amsmath, amssymb}
\usepackage{hyperref}

\title{A Minimal Compile Test}
\author{Test}
\date{\today}

\begin{document}
\maketitle

\section{Math}
Inline: $E = mc^2$. Display:
\[
  \int_{0}^{\infty} e^{-x^2}\, dx = \frac{\sqrt{\pi}}{2}.
\]

\section{Reference}
See \url{https://tug.org/texlive/}.

\end{document}

命令行验证（确认工具链本身可用）：

cd C:\path\to\your\project
C:\Users\<你的用户名>\texlive\2026\bin\windows\pdflatex.exe -interaction=nonstopmode test.tex

成功则生成 test.pdf。

VS Code 内验证：

打开 test.tex
按 Ctrl+Alt+B（或点击右侧 ▶）→ 选 pdflatex only recipe
按 Ctrl+Alt+V 预览 PDF

七、编译 ACM 论文（acmart 模板）

投稿 ACM 会议（如 ASPLOS、MICRO 等）用 acmart 文档类，需要额外装一个包，且 TeX Live 2026 移除了 acmart 依赖的三个旧包，必须手动补，否则会反复报 File ... .sty not found。

7.1 安装 acmart 及其依赖

$tlmgr = "C:\Users\<你的用户名>\texlive\2026\bin\windows\tlmgr.bat"
& $tlmgr install acmart
# acmart 不会自动带齐全部依赖，缺哪个补哪个（本次实测需要这些）：
& $tlmgr install totpages environ setspace framed zref hyperxmp libertine inconsolata newtx pifont comment algorithm2e multirow ifoddpage relsize endfloat tocbibind

7.2 手动补装 TL2026 已移除的三个包（重点坑）

manyfoot / nccfoots（同属 ncctools）和 balance（属 preprint）在 TeX Live 2026 里被移除了，tlmgr 装不到，需从 CTAN 下载源码（.dtx + .ins）用 latex 生成 .sty，再放进 texmf-local：

$tl = "C:\Users\<你的用户名>\texlive\2026\bin\windows"

# 1) ncctools（产出 manyfoot.sty 与 nccfoots.sty）
$work = "$env:TEMP\ncctools-build"; New-Item -ItemType Directory -Force $work | Out-Null
$src = "https://mirrors.ctan.org/macros/latex/contrib/ncctools/source/"
foreach ($f in @("manyfoot.dtx","nccfoots.dtx","ncctools.ins")) {
  Invoke-WebRequest -Uri ($src + $f) -OutFile "$work\$f" -UseBasicParsing
}
Push-Location $work; & "$tl\latex.exe" -interaction=nonstopmode ncctools.ins; Pop-Location
Copy-Item "$work\manyfoot.sty","$work\nccfoots.sty" "C:\Users\<你的用户名>\texlive\texmf-local\tex\latex\ncctools\" -Force

# 2) preprint（产出 balance.sty）
$work = "$env:TEMP\balance-build"; New-Item -ItemType Directory -Force $work | Out-Null
$src = "https://mirrors.ctan.org/macros/latex/contrib/preprint/"
foreach ($f in @("balance.dtx","balance.ins")) {
  Invoke-WebRequest -Uri ($src + $f) -OutFile "$work\$f" -UseBasicParsing
}
Push-Location $work; & "$tl\latex.exe" -interaction=nonstopmode balance.ins; Pop-Location
Copy-Item "$work\balance.sty" "C:\Users\<你的用户名>\texlive\texmf-local\tex\latex\balance\" -Force

# 3) 刷新文件名数据库
& "$tl\texhash.exe"

装完用 & "$tl\kpsewhich.exe" balance.sty 验证能找到即可。

7.3 用 pdflatex 编译 acmart（不是 xelatex）

acmart 默认针对 pdflatex 设计；用 xelatex 会报 LibertinusMath-Regular 字体找不到。含参考文献（模板用 \bibliographystyle{plain} + \bibliography{references}）时，编译链为：

pdflatex -output-directory=build main.tex
bibtex build/main
pdflatex -output-directory=build main.tex
pdflatex -output-directory=build main.tex

八、一键编译（latexmk）与输出目录

不想手敲多遍命令，用 latexmk。在项目根目录放一个 .latexmkrc：

$pdf_mode = 1;   # 用 pdflatex
$pdflatex = 'C:/Users/<你的用户名>/texlive/2026/bin/windows/pdflatex.exe -synctex=1 -interaction=nonstopmode -file-line-error %O %S';
$bibtex   = 'C:/Users/<你的用户名>/texlive/2026/bin/windows/bibtex.exe %O %B';
$out_dir  = 'build';   # 所有产物进 build/，根目录只留源码

然后：

latexmk main.tex     # 编译（自动多轮 + bibtex）
latexmk -c           # 清理辅助文件（保留 PDF）
latexmk -C           # 清理所有产物（含 PDF）

九、日常使用备忘

操作	快捷键 / 命令
编译	`Ctrl+Alt+B`（VS Code）或命令行 `latexmk main.tex`
预览 PDF	`Ctrl+Alt+V`
从 PDF 跳回源码	预览窗口 `Ctrl+点击` 文字（需 `-synctex=1`）
清理辅助文件	`latexmk -c`
更新宏包	`tlmgr update --self --all`

附录 A：如需支持中文（改用 xelatex）

最小版不含中文字体包，补装即可（约 50 MB）：

C:\Users\<你的用户名>\texlive\2026\bin\windows\tlmgr.bat install ctex xecjk fontspec fandol

然后在文档里用：

\documentclass{article}
\usepackage{ctex}
\begin{document}
你好，世界！
\end{document}

编译引擎换用 xelatex（VS Code 里把 pdflatex.exe 换成 xelatex.exe，或命令行 xelatex xxx.tex）。

附录 B：踩坑记录

PowerShell 5.1 下 cmd /c "... && ..." 失败 → 用 --% 停止解析符让参数原样传递（见第三步）。
中文报错乱码 → 是 GBK 编码显示问题，不影响实际执行；用 [System.Text.Encoding]::GetEncoding(936) 可正确解码查看。
VS Code 找不到编译器 → 用绝对路径写 command（见第五步），无需重启电脑。
.bat 文件「不是内部或外部命令」 → 多因工作目录未切换成功，务必用 cd /d <绝对路径> && 在同一 cmd 进程内切换。
acmart 反复报 File ... .sty not found → 依次是缺依赖 + TL2026 移除了 manyfoot/nccfoots/balance 三个包，按「第七节」补装即可。
acmart 用 xelatex 报 LibertinusMath-Regular 找不到 → 换 pdflatex（acmart 默认引擎）。
设置了 outDir 但 bibtex 找不到 .aux → bibtex 的 args 要写 %OUTDIR%/%DOCFILE%，且 pdflatex 要带 -output-directory=%OUTDIR%。
bibtex 报 I found no \citation commands → 正文还没有 \cite{}，属正常，不影响出 PDF；写了引用后自动消失。

最后更新于 2026-08-15