vscode 下 LaTeX 使用配置

环境

windows11 + wsl2 (ubuntu) + vscode

latex 环境安装

当前仍然无法直接通过 conda 安装 latex, 原因是 mktexlsr.pl 未包含在发行版中 (2025-07-02 12:15:31). 但一个单独的 conda 环境仍然是有必要的, 因为 latex 部分功能依赖于 perl

conda create -n latex -y
conda activate latex
conda install perl
# conda install -c conda-corge texlive 你可以试, 但运行不了
# conda install -c anaconda texlive-core 这个版本新一点 (2024 的)

texlive 安装

安装的时候无需 root 权限, 因为可以修改安装目录

conda activate latex
wget https://mirror.ctan.org/systems/texlive/tlnet/install-tl-unx.tar.gz
tar -xzf install-tl-unx.tar.gz # 用完记得删
cd install-tl-2*
perl ./install-tl 

随后进入安装界面:

======================> TeX Live installation procedure <===========================>   Letters/digits in <angle brackets> indicate   <=======
======>   menu items for actions or customizations      <=======
= help>   https://tug.org/texlive/doc/install-tl.html   <=======Detected platform: GNU/Linux on x86_64<B> set binary platforms: 1 out of 15<S> set installation scheme: scheme-full<C> set installation collections:40 collections out of 41, disk space required: 8897 MB (free: 600102 MB)<D> set directories:TEXDIR (the main TeX directory):!! default location: /usr/local/texlive/2025!! is not writable or not allowed, please select a different one!TEXMFLOCAL (directory for site-wide local files):/usr/local/texlive/texmf-localTEXMFSYSVAR (directory for variable and automatically generated data):/usr/local/texlive/2025/texmf-varTEXMFSYSCONFIG (directory for local config):/usr/local/texlive/2025/texmf-configTEXMFVAR (personal directory for variable and automatically generated data):~/.texlive2025/texmf-varTEXMFCONFIG (personal directory for local config):~/.texlive2025/texmf-configTEXMFHOME (directory for user-specific files):~/texmf<O> options:[ ] use letter size instead of A4 by default[X] allow execution of restricted list of programs via \write18[X] create all format files[X] install macro/font doc tree[X] install macro/font source tree[ ] create symlinks to standard directories<V> set up for portable installationActions:<I> start installation to hard disk<P> save installation profile to 'texlive.profile' and exit<Q> quitEnter command:

按安装界面的提示, 可以按 D 修改安装路径, 直接修改 TEXDIR (the main TeX directory) 至其他目录即可.
我的安装路径是 $CONDA_PREFIX/include/texlive/2025, 输入时需将 $CONDA 替换为完整路径.

接下来继续运行安装程序, 结束后升级:

tlmgr update --all --reinstall-forcibly-removed

并将该路径添加到环境, 这里仅添加到 conda 环境:

conda env config vars set PATH="$CONDA_PREFIX/include/texlive/2025/bin/x86_64-linux:$PATH"

latexindent 运行设置

latexindent 依赖两个 perl 包, 可以 conda 安装

conda install perl-file-homedir perl-yaml-tiny

运行:

latexindent -wd latex/src/main.tex latex/src/contents/*.tex

运行后可能用 Tab 调整缩进

tex-fmt 运行设置

tex-fmt 直接 conda 安装即可

conda install tex-fmt -y
tex-fmt latex/src/main.tex latex/src/contents/*.tex

运行后默认用两个空格作为缩进, 同时调整空行数

latex 运行

假设是要在一个 latex 模板上进行修改, 直接将其压缩包下载到当前目录并解压即可. 示例命令: latexmk -synctex=1 -interaction=nonstopmode -file-line-error -pdf -outdir=../output main. 以下是可能的问题

无法找到路径

latex 导入是相对运行路径而非主文件的, 如果希望在任意路径都可以编译指定位置上的文件, 以下命令效果相同:

cd latex/src; latexmk -synctex=1 -interaction=nonstopmode -file-line-error -pdf -outdir=../output main

以及:

(cd latex/src; latexmk -synctex=1 -interaction=nonstopmode -file-line-error -pdf -outdir=../output main)
TEXINPUTS=latex/src:$TEXINPUTS latexmk -synctex=1 -interaction=nonstopmode -file-line-error -pdf -outdir=latex/output latex/main
(export TEXINPUTS=latex/src:$TEXINPUTS; latexmk -synctex=1 -interaction=nonstopmode -file-line-error -pdf -outdir=latex/output latex/src/main)

uniyou7c 找不到

kpathsea: Running mktexpk --mfmode / --bdpi 600 --mag 1+123/600 --dpi 723 uniyou7c
mktexpk: don't know how to create bitmap font for uniyou7c.
mktexpk: perhaps uniyou7c is missing from the map file.
kpathsea: Appending font creation commands to %WORKSPACE_FOLDER%/latex/output/missfont.log.!pdfTeX error: pdflatex (file uniyou7c): Font uniyou7c at 723 not found==> Fatal error occurred, no output PDF file produced!
Latexmk: Getting log file '%WORKSPACE_FOLDER%/latex/output/main.log'
Latexmk: Examining '%WORKSPACE_FOLDER%/latex/output/main.fls'
Latexmk: Examining '%WORKSPACE_FOLDER%/latex/output/main.log'
Latexmk: Found input bbl file '%WORKSPACE_FOLDER%/latex/output/main.bbl'
Latexmk: References changed.
Latexmk: References changed.
Latexmk: Using biber to make bibliography file(s).
Latexmk: Bibliography file(s) from .bcf file:refs.bib
Sources for biberrefs.bib%WORKSPACE_FOLDER%/latex/output/main.bcf
Latexmk: Errors, so I did not complete making targets
Collected error summary (may duplicate other messages):pdflatex: Command for 'pdflatex' gave return code 1Refer to '%WORKSPACE_FOLDER%/latex/output/main.log' and/or above output for detailsLatexmk: Sometimes, the -f option can be used to get latexmkto try to force complete processing.But normally, you will need to correct the file(s) that caused theerror, and then rerun latexmk.In some cases, it is best to clean out generated files before rerunninglatexmk after you've corrected the files.

这个问题可能是由于 unicode 8 矢量字体未生成对应的位图文件, 可以改用 xelatex:

TEXINPUTS=latex/src/:$TEXINPUTS xelatex -synctex=1 -interaction=nonstopmode -file-line-error -output-directory=latex/output latex/src/main

注意 -output 应改为 -output-directory

documentclass 找不到

如果报错某些包找不到, 则需要确认 TEXMFHOME 是否正确, 如

LaTeX2e <2025-06-01> patch level 1
L3 programming layer <2025-06-09>! LaTeX Error: File `XXX.cls' not found.Type X to quit or <RETURN> to proceed,
or enter new name. (Default extension: cls)

则需要修改 TEXMFHOME 参数:

TEXMFHOME=latex/src/texmf:$TEXMFHOME TEXINPUTS=latex/src/:$TEXINPUTS xelatex -synctex=1 -interaction=nonstopmode -file-line-error -output-directory=latex/output latex/src/main

插件参数设置

编译参数

兜底解决方案:

{"latex-workshop.latex.tools": [{"name": "xelatex_bash","command": "bash","args": ["-c","(cd `realpath -m \"%DOC%/..\"` && PATH=$CONDA_PREFIX/include/texlive/2025/bin/x86_64-linux:$CONDA_PREFIX/bin:$PATH && xelatex -synctex=1 -interaction=nonstopmode -file-line-error -output-directory=\"%OUTDIR%\" \"%DOCFILE%\"; sleep 1)"],"env": {}}],"latex-workshop.latex.recipes": [{"name": "latexmk (xelatex bash)","tools": ["xelatex_bash","xelatex_bash"]}]
}

说明:

• 使用 bash 而不是 xelatex 是因为我无论如何都无法对 xelatex 设置正确的 TEXMFHOME 参数, 而使用 bash 时无此问题.
• sleep 1 是因为如果 xelatex 运行中遇见不影响生成 pdf 的错误时不会停止, 但 vscode extension 仍会因 returncode 非零而报错.
• 输入时需将 $CONDA 替换为完整路径.
• recipes 连续运行两次 xelatex, 因为第一次运行结束后会有 warning, 重复运行即消失

  LaTeX Warning: Label(s) may have changed. Rerun to get cross-references right.Package rerunfilecheck Warning: File `main.out' has changed.
  (rerunfilecheck)                Rerun to get outlines right
  (rerunfilecheck)                or use package `bookmark'.)
  (see the transcript file for additional information)
  Output written on main.pdf (53 pages).
  SyncTeX written on main.synctex.gz.
  Transcript written on main.log.
  

格式化

{"latex-workshop.formatting.latex": "tex-fmt","latex-workshop.formatting.tex-fmt.path": "$CONDA_PREFIX/bin/tex-fmt",
}

同上