WSL(Linux) / MacOS 环境下使用 VSCode 写 LaTeX 的环境配置教程

本文介绍在 Windows + WSL（Linux 应该是相同的） 以及 MacOS 下面的环境配置。

安装 TeX Live

建议安装 TeX Live 这个包，它可以一键安装 TeX 的相关程序。它的安装过程很简单，而且基本不需要额外再安装什么东西。大小大概在 4.4 GiB 左右。

WSL/Linux: 参考这篇文章：在WSL中安装LaTeX，从 TeX 用户组官网下载 TeX Live 的 ISO 镜像并挂载，随后即可从 WSL 中访问安装脚本。Linux 虚拟机用户请自行参考自己所使用的虚拟机软件的 ISO 挂载方式；Linux 实体机用户可以直接 mount。

Mac OS 也可以从 TeX 用户组官网下载 Tex Live 的 Mac OS 安装包。这个安装包是经过签名的，可以直接安装。

环境变量配置

对于 MacOS 用户，这一节可以直接跳过，翻阅下面的“MacOS 用户专属”一节即可。

这一部分比较关键，因为这里有不少坑。
我们需要将 TeX Live 的安装位置加入到环境变量 PATH，但添加环境变量的位置却不能随便选。比如说，对于 zsh 用户，/etc/zprofile, /etc/zshenv, ~/.zshenv, 甚至 ~/.zshrc 等这些配置文件中都可以修改 PATH，但并不是每个文件都会被我们将要使用的 VSCode 扩展识别。如果在错误的地方修改 PATH，那么这个更改是不会被 VSCode 扩展识别到的，从而导致它找不到对应的 tex 程序，报出 ENOENT 错误。这是因为在不同的模式下，shell 的启动文件的执行顺序乃至是否执行，都是有差别的。下面我们详细解释 shell 启动文件的执行方式。

分析：shell 的启动文件的执行顺序

shell 在启动之前，会提前按顺序执行一些启动文件，这些文件实际上是脚本。比如上面提到的，对于 zsh，有 /etc/zprofile, /etc/zshenv, ~/.zshenv, ~/.zshrc等等。

在不同的启动方式下，执行的启动文件会有所不同。参考这篇文章：Zsh/Bash startup files loading order (.bashrc, .zshrc etc.)，zsh 的文件执行顺序如下：

+----------------+-----------+-----------+------+
|                |Interactive|Interactive|Script|
|                |login      |non-login  |      |
+----------------+-----------+-----------+------+
|/etc/zshenv     |    A      |    A      |  A   |
+----------------+-----------+-----------+------+
|~/.zshenv       |    B      |    B      |  B   |
+----------------+-----------+-----------+------+
|/etc/zprofile   |    C      |           |      |
+----------------+-----------+-----------+------+
|~/.zprofile     |    D      |           |      |
+----------------+-----------+-----------+------+
|/etc/zshrc      |    E      |    C      |      |
+----------------+-----------+-----------+------+
|~/.zshrc        |    F      |    D      |      |
+----------------+-----------+-----------+------+
|/etc/zlogin     |    G      |           |      |
+----------------+-----------+-----------+------+
|~/.zlogin       |    H      |           |      |
+----------------+-----------+-----------+------+
|                |           |           |      |
+----------------+-----------+-----------+------+
|                |           |           |      |
+----------------+-----------+-----------+------+
|~/.zlogout      |    I      |           |      |
+----------------+-----------+-----------+------+
|/etc/zlogout    |    J      |           |      |
+----------------+-----------+-----------+------+

对于 bash, 可以参考这张图片：

VSCode 的扩展在执行脚本时，使用的是 non-login non-interactive 方式（shell 的 login/non-login 的区别详见 该链接）。所以在某些地方写入的环境变量是不会生效的。例如，在 ~/.zshrc 写入的环境变量就不会生效。根据上面的表格可以看出，我们应当在 ~/.zshenv 中写入环境变量。

写入环境变量

写入的位置

对于 zsh 用户，根据上面的表格，应当在 ~/.zshenv 中写入 TeX 相关的环境变量。

对于 bash 用户，根据上面的图，应当在 $BASH_ENV 中指定环境变量文件，然后在那个文件中写入 TeX 相关的环境变量。这个环境变量来自调用脚本的用户。

所以你应该在在login interactive模式下的启动文件中写入一条 export BASH_ENV={你的环境变量文件}，这样 VSCode 的扩展才能正确找到 TeX 程序的位置。

当然，如果你有在交互式 shell 中使用 TeX 命令的需求，可以自己在 login interactive 模式的启动文件中把 TeX 的环境变量加进去。

写入的内容

TeX Live 会把文件安装在 /usr/local/texlive/2021/bin/{platform}，这个 {platform} 是根据不同平台而定的，对于 Mac OS 用户，这个值是 universal-darwin, 对于 Linux/WSL 用户，这个值是 x86_64-linux。

因此我们在上一节提到的文件中添加一行：
export PATH=/usr/local/texlive/2021/bin/{platform}，注意将 {platform} 替换掉，还有，不要忘了替换路径中的 2021！

Mac OS 用户专属

对于 Mac OS 用户，上面的配置原理依然是正确的，然而 VSCode 扩展并不会去读取 non-login non-interactive 模式下的环境变量，所以配了也没什么用。不过如果你想要在交互式环境下访问 pdflatex 等 TeX 程序，那么可以部分参考上面章节。

那么 Mac OS 用户的环境变量写在哪里才会被识别到呢？答案是 /etc/paths.d/目录中。
这个目录中的文件，其内容是由一行行路径组成的。比如 Tex Live 会在安装的时候将其程序目录写进 /etc/paths.d/TeX, 文件内容如下：

/Library/TeX/texbin

**但是不知道为什么，这一条配置不管用。 VSCode 的扩展能够识别到这条环境变量，但依然找不到二进制文件。**如果有人知道为什么可以告诉我。

因此我们需要手动添加一个文件，名字起什么都可以，比如 tex-custom, tex-fixed 等等。

/usr/local/texlive/2021/bin/universal-darwin

后来的读者注意了，你需要把上面内容中的 2021 替换成你安装时 TeX Live 的版本！！！

这样就完成了环境变量的配置。

扩展安装

我们在 VSCode 中安装 LaTeX Workshop 扩展，并对其进行一定的配置。

请参考 使用VSCode编写LaTeX - 知乎专栏 进行配置。

有了上一节提到的环境变量设置，这个扩展应该能够正常识别 TeX 程序。如果在编译时报了 ENOENT 的错误，请在扩展的输出中检查 $PATH 的值，扩展会在刚开始运行时将这个变量打印出来的。

如何保持工作区清洁

如果你打算使用 Git 管理 TeX 项目，不想让生成的文件污染工作区，那么按照上面的链接配置好后，可以 在他的配置的基础上进行一些修改：

"latex-workshop.latex.outDir": "%WORKSPACE_FOLDER%/bld",  # 增加该项，将输出文件统一放到 bld 目录
"latex-workshop.latex.tools": [
    {
        // 编译工具和命令
        "name": "xelatex",
        "command": "xelatex",
        "args": [
            "-synctex=1",
            "-interaction=nonstopmode",
            "-file-line-error",
            "-pdf",
            // 增加下面两项是为了让 xelatex, pdflatex 等程序找到上一环节生成的中间文件的位置，下同
            "-aux-directory=%WORKSPACE_FOLDER%/bld",
            "-output-directory=%WORKSPACE_FOLDER%/bld",
            "%DOCFILE%"
        ]
    },
    {
        "name": "pdflatex",
        "command": "pdflatex",
        "args": [
            "-synctex=1",
            "-interaction=nonstopmode",
            "-file-line-error",
            // 原有设置不变，增加下面两项，理由同上 
            "-aux-directory=%WORKSPACE_FOLDER%/bld",
            "-output-directory=%WORKSPACE_FOLDER%/bld",
            "%DOCFILE%"
        ]
    },
    {
        "name": "bibtex",
        "command": "bibtex",
        "args": [
            "%DOCFILE%"
        ]
    }
],
"latex-workshop.latex.recipes": [
    {
        "name": "xelatex",
        "tools": [
            "xelatex"
        ],
    },
    {
        "name": "pdflatex",
        "tools": [
            "pdflatex"
        ]
    },
    {
        "name": "xe->bib->xe->xe",
        "tools": [
            "xelatex",
            "bibtex",
            "xelatex",
            "xelatex"
        ]
    },
    {
        "name": "pdf->bib->pdf->pdf",
        "tools": [
            "pdflatex",
            "bibtex",
            "pdflatex",
            "pdflatex"
        ]
    }
],

另外，建议在 .gitignore 中忽略 *.log，从而忽略某些错误日志。