【学习笔记】从零开始配置本地LaTeX（TeX Live+vs code ...

为正义出发

前言

本文总结了一下本地使用LaTeX前的准备工作，主要包括概念理解与macOS上的环境配置，以方便自己随时能捡起来。如果想跳过这些直接上手，线上版的Overleaf将是不错的选择。
我期望看完本文后，你将

• 形成概念框架，知道需要了解什么，以及去哪里进一步了解
  
• 不再感觉操作黑箱，并拥有一定的定制化能力
  
• （如果你是mac用户）直接开始编写第一个.tex文件
  

不过本文是笔者作为初学者的学习笔记分享，希望谨慎参考，如有阙漏，还请谅解。
概念轰炸

如果我提到“latex”，我有可能是指LaTeX语言作为TeX语言的宏，也可能是在指它的某个发行版，也可能是指编译器latex。与此同时，还有很多带有“tex”（一般读作“tech”）的名称也容易彼此混淆，所以本章先将它们梳理清楚。
排版系统（Document Preparation Systems）

排版系统包含<语言,宏>，是一组事先约定好的关键字集，其中宏（macros）是在底层语言上的进一步封装，比如成语可以类比为汉语的宏。
TeX、LaTeX、ConTeXt等都可以被称作排版系统，这个语境强调的是关键字的约定。其中TeX只包含“元指令”，自由但十分繁琐晦涩；而LaTeX是在TeX基础上封装了若干常用的宏，它们不那么自由但容易上手。
LaTeX的前一个版本为LaTeX2.09，当前版本为LaTeX2e，epsilon意为在2版本之后，但距离3版本还遥遥无期。值得一提的是，排版系统的新旧概念与快速迭代的程序不同，LaTeX2e这个“最新版”诞生于1994年。
关于LaTeX项目，可以在官网找到各种帮助文档（链接），也可以在英文版wikibooks找到超级无敌事无巨细的电子书（链接），它们尤其是后者是我进一步学习的首选。但如果仅仅查阅简单语法的话，我十分推荐《不太简短的LaTeX2e介绍》（链接），英文版为The Not So Shot Introduction to LaTeX2e（链接），下文将其简称为lshort。
注意lshort有很多版本，目前最新的是2021年版。下载的发行版中应该会附带，至少TeX Live与MacTeX是这样。
发行版（Distributions）

发行版包含<引擎,字体,宏包>，是使用排版系统的软件套装。其中引擎（Engines）是核心，负责“代码+字体+宏包->可打印文件”这一过程。
特别地，LaTeX的发行版有TeX Live、MacTeX、MiKTeX。

TeX Live	跨平台
MacTeX	主要面向macOS
MiKTeX	主要面向Windows

这些发行版的官网外观可能比较简陋，但其实文档都很完整。以我选择的TeX Live为例，目前只需要读标准文档（链接）中的安装方法。
另外，如果你已经下载、配置好了TeX Live，也可以在命令行直接打开lshort的英文或中文版。
% texdoc lshort
% texdoc lshort-zh-cn引擎（Engines）

引擎也就是编译器，负责将你的源代码转化为可打印文件，同时还需要你提供自己用到的字体和宏包，不过在发行版中已经打包好了。
可打印文件主要有.dvi与.pdf，TeX编译器主要有tex、pdftex、xetex、luatex等。类似地，如果名称为**latex，则是LaTeX的编译器。（但是我找到二进制文件latex与tex，发现latex的原身就是tex，我现在还不理解为什么调用后会有区别。）

tex, latex	输出dvi文件
pdftex, pdflatex	输出pdf文件
xetex, xelatex	对字体与符号的支持更强大
luatex, lualatex

字体（Fonts）

这里我还没弄懂。但根据我有限的了解，字体的坑似乎很深，且普通用户根本不需要了解。
宏包（Packages）

宏包是包含额外LaTeX指令的文件，不过从某种程度上讲，LaTeX本身就是一个宏包。
发行版中会自带一些宏包，例如amsmath等。很多都是可选项，安装时可以选择动态下载以节省空间。但为了省心，我个人建议一次性下载。
如果有特殊需求，也可以到CTAN平台（链接）寻找你需要的第三方包，例如绘制棋盘、乐谱、化学式等。与宏包相关的文件必须严格按照规则存放，所以有专门包管理器来负责下载、卸载，例如TeX Live的包管理器是tlmgr。
我的工具选择（跨平台）

概念介绍结束，下面进入正题。
使用LaTeX，原则上只需要下载发行版，就可以在命令行里写论文了。但有没有一种方法，让写论文还能享受到图形界面、代码补全、双向定位、版本控制等特性呢？可以，这就需要配备合适的代码编辑器、预览器了。它们之间的大致关系如下图所示。


在工具的选择上，我的第一需要是通用、跨平台，不追求对专业人士最高效，只追求例外情形最少。于是我果断选了一个至少不会错的方案：TeX Live + vs code + Zotero（沿用的文献管理器） + Viewer（vs code插件或系统自带的预览器）。最主要的选择是前两个，接下来我会说我的理由。

如果想选择不同的工具，wiki电子书（链接）的2.3-2.5节列举了许多其他选择，不过可能有些老旧了，酌情参考。

TeX Live

如上文介绍中提到的，TeX Live面向全平台，如果我未来某个时候需要在集群或者PC上使用，那么操作也差不多。由于是Linux用户的首选，它在许多教程中也是默认选择。
MacTeX类似于某种TeX Live plus，对macOS有更多支持，我以后可能会尝试。
vs code

vs code社区大、轻量、可拓展性强，这意味着原则上你可以用它做任何事情，并且比较容易获得帮助。不过最最重要的还是跨平台，它可以远程登录集群，同时其他操作都不需要变。
对于各种代码相关的任务，会有人推荐各种不同的编辑器，但我现在尽量在把所有事情都放到vs code做。尽管有时学习成本比较陡峭，需要弄懂原理，但长远来看我不后悔。因为其他编辑器或者IDE基本只是多做了一些自动化，不懂原理的话还是可能出问题，懂了的话本质上都一样。
Zotero（沿用）

这里继续选择它算是一种沿用。如果原先就没有文献管理的需要，那这里也可以跳过。
Viewer（自带）

意思就是不额外下载预览器。可以使用vs code插件里自带的，具备双向定位功能，也可以空格呼出系统自带的。这些对我入门级使用已经足够了，如果要更换也等有明确需求再说。
下载并配置工具（macOS）

其实关键配置只有两步：1）把三行代码复制到bash_profile里完成Tex Live配置；2）把一揽子代码复制到setting.json里完成vs code配置。但我打算多说几句，希望把做了什么说清楚。
TeX Live

• 下载
  
• 安装
  
• 配置环境变量
  

1&2 下载并安装
下载可以选择挂梯从官网下，也可以选择清华镜像（链接），得到的是texlive.iso虚拟光驱。在清华源的检索方法是：CTAN社区 -> TeX Live系统 -> image镜像。
打开虚拟光驱可以看到一个名为install-tl的可执行文件，这就是安装器。双击运行，按照默认方式安装。这时候考虑清楚什么包更有用是不太现实的，而且安装完再进行包管理可能会出现更多问题，所以我不打算考虑节省空间。
TeX Live主体会被安装到/usr/local/texlive，这一点符合规范，但是为了允许同时存在多个版本，TeX Live的子目录结构会有所不同。

更加定制化的安装方式，可以参考TeX Live官方文档（链接）。

3 配置环境变量
这时在终端查询tex引擎版本
% tex --version 会发现报错了，这是因为没有找到名为tex的程序，还需要配置所谓的“环境变量”。环境变量有很多，最主要的是“PATH”，它们类似于你的“视野”，而配置环境变量则是让路径下的文件可以被“看到”。
为直观感受这一点，可以打开Finder，按下cmd+shift+G，输入/usr/local/texlive进入TeX Live的主目录、然后依次进入.../20**/bin/**-darwin文件夹（星号取决于下载的版本），在这里可以看到很多可执行文件


其中就有上文提到的tex、pdftex、xetex等引擎。不管未来使用什么软件，本质上都是在终端调用这些引擎。
而在终端打印一下环境变量PATH
% echo $PATH会发现其中并不包括这条路径，这就是为什么之前终端找不到tex引擎。现在不妨把它添加进去（下面以我的路径为例，记得换成自己的）
% PATH=/usr/local/texlive/2022/bin/universal-darwin:$PATH export PATH在输入路径时，可以直接把**-darwin文件夹拖进来避免出错。这时再次输入
% tex --version就可以成功得到tex引擎的版本了。
不过这只是临时添加，重启终端后PATH就会恢复原状。为了修改环境变量的默认值，需要打开Finder，按“cmd+shift+G”输入“~”进入用户路径，按“cmd+shift+句号”显示隐藏文件，打开名为“.bash_profile”的文件，把以下命令添加进去（其中第一行是关键，后两行是为了一些手册文件能被找到）
PATH=/usr/local/texlive/2022/bin/universal-darwin:$PATH export PATH
MANPATH=/usr/local/texlive/2022/bin/universal-darwin/doc/man:$MANPATH export MANPATH
INFOPATH=/usr/local/texlive/2022/bin/universal-darwin/doc/info:$INFOPATH export INFOPATH保存后重启终端，PATH中依旧保留了目标路径，这意味着环境变量就配置好了。这一步一般用vim完成，但这里暂且不涉及它。

我参考的是TeX Live官方文档（链接）3.4.1节中Unix的配置方式，在macOS中仅略有不同。

vs code

• 下载插件
  
• 配置插件
  

1 下载插件
假设已经下载了vs code本体。在左侧活动栏（Activity Bar）找到插件项，搜索并下载LaTeX Workshop插件，注意看准是哪个


下载完成后，打开一个.tex文件，活动栏中就会自动出现一个TEX项。展开commands可以看到各种操作


其中最常用的就是

• 编译（Build），快捷键cmd+opt+B
  
• 定位（Navigate），快捷键cmd+opt+J
  
• 反向定位，快捷键cmd+click
  

2 配置插件
插件目前并不确定如何完成这些操作，也就是说还需要进行配置。
我对“配置”的粗浅理解是：为了让vs code自动在终端输入命令、可视化输出结果，所需要完成的提前约定。
首先，在vs code界面按下“cmd+shift+P”打开命令板（command palette）——这将会经常用到——搜索“User Settings”，可以看到两个可选项，一个是打开设置界面，另一个则是打开名叫settings的.json文件，我们选择后者。


如果没有经过任何配置，那么应当看到文件中只有两个孤零零的大括号。接下来所有的配置条目应该都被写在中间，并且由逗号隔开，这是json的语法要求。在settings文件中，我们可以预设所有vs code插件的行为，这等价于在设置界面中逐条修改，但只会更方便。
先展示两条基本配置。
{  
    "latex-workshop.latex.tools": [    // 编译工具列表
        {                              // 工具一：
            "name": "pdflatex",        //   名称
            "command": "pdflatex",     //   命令
            "args": [                  //   参数列表
                "-synctex=1",
                "-interaction=nonstopmode",
                "-file-line-error",
                "%DOCFILE%"
            ]
        },
                                       // 编译工具二（以下省略）
    ],

    "latex-workshop.latex.recipes": [  // 编译方案列表
        {                              // 方案一：
            "name": "pdflatex",        //   名称
            "tools": [                 //   使用的工具列表
                "pdflatex"
            ]
        },
                                       // 方案二（以下省略）                        
    ],
}它们造成的影响是：一个名为pdflatex的编译方案将会在commands栏中出现


执行这个方案将使用一次名为pdflatex的编译工具，而使用这个工具相当于在终端执行含参命令
% pdflatex CURR_FILE.tex -synctex=1 -interaction=nonstopmode -file-line-error %DOCFILE%这样一来，插件就明确知道该如何编译了。现在再按下快捷键“cmd+opt+B”，插件将自动调用pdflatex引擎，以约定的方式编译出pdf文件。
接下来再来看几条锦上添花的配置。
{
    // 默认的编译链方案为“首个”
    // 可选项：first, lastUsed
    "latex-workshop.latex.recipe.default": "first",

    // 永不自动编译
    // 可选项：onFileChange, onSave, never
    "latex-workshop.latex.autoBuild.run": "never",

    // 永不清理辅助文件
    // 可选项：onBuilt, onFailed, never
    "latex-workshop.latex.autoClean.run": "never",

    // 自动填充
    "latex-workshop.intellisense.package.enabled": true,

    // 反向定位
    "latex-workshop.view.pdf.internal.synctex.keybinding": "double-click",

    // 弹出error
    "latex-workshop.message.error.show": true,

    // 弹出warning
    "latex-workshop.message.warning.show": true,
}这些关系都不大，可以随意尝试，也可以阅读插件的文档以探索更多可能。我猜测有些设置或许会影响编译速度，所以打算留个心思。另外，这么多注释其实是不必要的，只要悬停鼠标即可看到所有信息。
好了，现在是时候把完整版放出来了。
不过事先申明一下，我参考的是下面这位答主，然后按照自己的喜好进行了微调，比如把编译和清理都交给手动选择。
{
    "latex-workshop.latex.recipe.default": "first",         // use which recipe
    "latex-workshop.latex.autoBuild.run": "never",          // when auto build
    "latex-workshop.latex.autoClean.run": "never",          // when auto clean
    "latex-workshop.intellisense.package.enabled": true,    // whether auto fill
    "latex-workshop.view.pdf.internal.synctex.keybinding": "double-click", // how to reverse synctex
    "latex-workshop.message.error.show": true,              // pop error
    "latex-workshop.message.warning.show": true,            // pop warning
    "latex-workshop.latex.tools": [
        {
            "name": "xelatex",
            "command": "xelatex",
            "args": [
                "-synctex=1",
                "-interaction=nonstopmode",
                "-file-line-error",
                "%DOCFILE%"
            ]
        },
        {
            "name": "pdflatex",
            "command": "pdflatex",
            "args": [
                "-synctex=1",
                "-interaction=nonstopmode",
                "-file-line-error",
                "%DOCFILE%"
            ]
        },
        {
            "name": "bibtex",
            "command": "bibtex",
            "args": [
                "%DOCFILE%"
            ]
        },
        {
            "name": "latexmk",
            "command": "latexmk",
            "args": [
                "-synctex=1",
                "-interaction=nonstopmode",
                "-file-line-error",
                "-pdf",
                "-outdir=%OUTDIR%",
                "%DOCFILE%"
            ]
        },
    ],
    "latex-workshop.latex.recipes": [
        {
            "name": "xelatex",
            "tools": [
                "xelatex"
            ]
        },
        {
            "name": "pdflatex",
            "tools": [
                "pdflatex"
            ]
        },
        {
            "name": "bibtex",
            "tools": [
                "bibtex"
            ]
        },
        {
            "name": "latexmk",
            "tools": [
                "latexmk"
            ]
        },
        {
            "name": "xelatex -> bibtex -> xelatex*2",
            "tools": [
                "xelatex",
                "bibtex",
                "xelatex",
                "xelatex"
            ]
        },
        {
            "name": "pdflatex -> bibtex -> pdflatex*2",
            "tools": [
                "pdflatex",
                "bibtex",
                "pdflatex",
                "pdflatex"
            ]
        },
    ],
    "latex-workshop.latex.clean.fileTypes": [
        "*.aux",
        "*.bbl",
        "*.blg",
        "*.idx",
        "*.ind",
        "*.lof",
        "*.lot",
        "*.out",
        "*.toc",
        "*.acn",
        "*.acr",
        "*.alg",
        "*.glg",
        "*.glo",
        "*.gls",
        "*.ist",
        "*.fls",
        "*.log",
        "*.fdb_latexmk"
    ],
}注意到有的方案里使用了四次工具，看起来很奇怪。这好像是因为（出于某种我尚不理解的原因）LaTeX需要二次编译才能调整好pdf中跟跳转有关的东西，例如目录、交叉引用、文献等，所以在插入文献后还要再用两次latex引擎。原则上你用一百次都可以，只是比较花时间。与此同时latexmk引擎又格外特殊，可以做到一次性完成所有工作，所以没有这种需要。
再补充一句，关于什么时候清理辅助文件、什么时候用什么工具链，这些设置对速度的影响要留个心思，未来需要性能的时候回过头来看看，我有空也会了解一下。总之，如果把vs code当作黑箱来用，复制粘贴不知从哪来的配置，那几乎肯定远远比不上专业人士打包的IDE黑箱。我喜欢的是vs code的自由，遇到特殊需求再回到IDE，那时候IDE就是我的提线木偶，而不是反过来。
好了好了，我不多扯了，现在只要把这些内容复制粘贴到settings文件中，一时半会就再也不用理它了。
如果复制完了，那么恭喜！现在编译实现了自动化，最后再复习一下常用操作

• 编译（cmd+opt+B）
  
• 定位（cmd+opt+J）
  
• 反向定位（cmd+click）
  

就可以用LaTeX写文章了。
第三方包

我前面推荐一次性下载，也是因为这个包管理我还没弄明白。我遇到了找不到包的问题，而且是很正规的包，这个还没有解决。但因为只是下着玩，所以我就先搁置这个问题了，只能祝你好运吧。
基本操作并不复杂，但LaTeX包的分发貌似不如python那样规范。
tlmgr install <package>
tlmgr uninstall <package>
tlmgr list

更多关于自动和手动下载，可以参考wiki电子书（链接）3.1-3.2节。

编写第一个tex文件

基本框架如下，细节语法还请自学（为方便阅读，我一般会限制一下宽度）：
% ----------------------------------------------------------------------
%                              MAX WIDTH                             72|
%            HALF WIDTH          36|

\documentclass[]{article}
% Document Classes:
%   article, proc, minimal, report, book, slides
% Document Class Options:
%   10/11/12pt, a4paper, letterpaper,
%   fleqn, leqno, one/two columns, one/twoside, ...

\usepackage[]{}
% Some of the Packages Distributed with LaTeX:
%   doc, exscale, fontenc, ifthen, latexsym,
%   makeidx, syntonly, inputenc

\pagestyle{plain}
% The Predefined Page Styles of LaTeX:
%   plain, headings, empty

\author{Nemo}
\title{First \LaTeX{} File}
\date{2023}

\begin{document}

    \maketitle

    Say hi to \LaTeXe.

\end{document}编译后的效果：


可以尝试添加点实际内容：
\documentclass[]{article}
\usepackage[]{amsmath, xeCJK} % in distribution

\author{Nemo}
\title{First \LaTeX{} File}
\date{2023}

\begin{document}

    \maketitle
    \tableofcontents

    \section{Schrödinger Equation}
    \begin{equation*}
        i \hbar \frac{\partial}{\partial t} \psi = H \psi
    \end{equation*}

    \section{前赤壁赋}
    \begin{verse}
        客亦知夫水与月乎？\\
        逝者如斯，而未尝往也；\\
        盈虚者如彼，而卒莫消长也。
    \end{verse}

\end{document}编译后的效果：