LaTeX本地部署全攻略：从安装到公式、参考文献与图片排版

写给自己Blog的时候，我一向不太愿意把“本地部署”说得太玄。LaTeX本身不复杂，复杂的是第一次装环境时那些碎到不能再碎的坑。这篇我把从安装、配置、写公式、插图片到排参考文献的完整路径整理出来，尽量按我实际操作过的顺序写，你照着走一遍，应该就能把自己的本地LaTeX环境稳稳跑起来。

1. LaTeX本地部署先想清楚：哪些场景真的需要本机环境

1.1 在线编译越来越卡，真正卡在什么地方

先说一个很现实的问题：在线LaTeX编辑器用了两三年，文档页面刚过三十页，每次编译要等十几秒，git版本管理还老和自动保存打架，那你就到了该考虑本地部署的节点了。LaTeX本地部署，本质上是把编辑器、LaTeX发行版、PDF预览器和参考文献工具链全部装到自己的操作系统里，所有编译动作在本地CPU上完成，不依赖任何网页服务。

为什么本地环境对长文档更有优势，核心原因有三点：

• 编译速度稳定。在线服务高峰时段经常排队，本地编译基本是秒开，尤其是增量编译的时候，改一个小错误只重编受影响的部分。
• 断网可用。我赶过好几次高铁上改论文的稿子，离线环境下在线编辑器直接罢工，本地TeX Live没有任何影响。
• 包管理和模板自由。在线平台能装的宏包有限，遇到期刊模板要求特定版本宏包，本地环境可以手动装任意版本，自由度完全不一样。

适合参考这篇内容的人，我大致分三类：正在写本科或研究生学位论文的同学、需要频繁改投期刊模板的研究人员、以及所有工作中要处理公式和报告模板的工程师。如果你只是偶尔写两页带公式的作业，其实在线编辑器足够了，没必要折腾本地部署。

1.2 TeX Live和MiKTeX怎么选：一张表说清

本地部署LaTeX的第一步是选发行版。主流的就两个：TeX Live和MiKTeX。这两个不是LaTeX本身，而是把LaTeX引擎、数百个宏包、字体和工具打包到一起的“发行版”，理解成“LaTeX生态的一键安装包”就行。

我自己在Windows上主力用TeX Live，在Linux服务器上也装过TeX Live，MiKTeX只在一台老笔记本上试过。两者的差异我用一个表格直接说清：

我的建议很直接：如果你不知道自己选什么，直接装TeX Live完整版。7GB对现在的主流固态硬盘不算大，换来的是“编译到任何一个宏包都不会提示missing”的安心感。MiKTeX适合那种纯粹想写个几十行公式、连宏包概念都不想了解的人，但一旦论文开始引用大量包，按需下载装包的过程反而让人烦躁。

2. 从零开始装环境：TeX Live安装、VS Code配置与首次编译

2.1 安装TeX Live时我踩过的三个选择

TeX Live安装看起来是“下一步下一步”，但有几个选项第一次装很容易忽略。我以Windows环境为例，在macOS和Linux上思路完全相同，只是安装包形态不一样。

第一件事，去TeX Live官网找到install-tl的下载页面。Windows下下载zip包，解压后进目录运行install-tl-windows.bat，会弹出字符界面的安装菜单。这个界面不是图形化，很多人第一次看到以为出错了，其实这是正常界面，用键盘上下键和回车操作。

安装菜单里我最关注三个配置项：

• 安装方案（scheme）。默认是full scheme，这就是完整版。千万不要为了省空间选basic或small，后面每缺一个包都要手动装，成本远超省下的那点磁盘空间。
• 安装目录。Windows默认是C:\texlive\2024，建议保持默认，后面配环境变量时路径好记。
• 字体和符号包。完整版会自动带上所有font和latex packages，不需要单独勾选。

安装时长取决于网络速度。我第一次装大概花了四十分钟，主要是下载几百个package的归档。安装完成后，把C:\texlive\2024\bin\windows加入系统的Path环境变量，这个步骤非常关键。具体操作是：右键“此电脑” → 属性 → 高级系统设置 → 环境变量 → 在“系统变量”里找到Path，把上面的bin路径追加进去。

提示：用macOS的话，安装MacTeX后通常系统路径会自动配好，不用手动改。Linux用户如果用apt装texlive-full，路径一般也已经在/usr/bin下，不需要额外配置。

装完验证环境是否成功，打开命令行输入：

bash复制tex --version
latex --version
xelatex --version

只要三条命令都有版本号输出，说明核心引擎已经就位。如果提示“不是内部或外部命令”，八成是Path没配置对或者终端没重启，关掉命令行窗口重新开一个就行。

2.2 VS Code + LaTeX Workshop配置出稳定编译链

引擎装好之后，接下来要选一个顺手的编辑器。Windows下我推荐的组合是VS Code加LaTeX Workshop插件，理由有三：免费、跨平台、语法高亮与编译工具链集成度足够高。

在VS Code扩展市场搜“LaTeX Workshop”安装，插件自带PDF预览功能，还支持正向同步（从源文件跳转到PDF对应位置）和反向同步（从PDF点回去找源码位置）。装完后需要在settings.json里做一些微调，我直接把常用的配置贴出来：

json复制{
    "latex-workshop.latex.recipes": [
        {
            "name": "xelatex",
            "tools": ["xelatex"]
        },
        {
            "name": "xelatex -> bibtex -> xelatex * 2",
            "tools": ["xelatex", "bibtex", "xelatex", "xelatex"]
        }
    ],
    "latex-workshop.latex.tools": [
        {
            "name": "xelatex",
            "command": "xelatex",
            "args": [
                "-synctex=1",
                "-interaction=nonstopmode",
                "-file-line-error",
                "%DOC%"
            ]
        },
        {
            "name": "bibtex",
            "command": "bibtex",
            "args": ["%DOCFILE%"]
        }
    ],
    "latex-workshop.view.pdf.viewer": "tab"
}

这里要额外强调一个点：很多新手在本地部署LaTeX后，编译中文文档编不出来，核心原因是默认走了pdflatex引擎，而这个传统引擎对中文字体支持非常有限。我上面的配置把默认编译方式设为xelatex，配合ctex宏包，处理中文排版最省心。如果你的项目里没有中文需求，用pdflatex或latexmk也可以，但我建议所有新项目直接统一走xelatex，省得以后切来切去。

还有一个细节：LaTeX Workshop会默认生成很多辅助文件，.aux、.log、.synctex.gz、.out、.toc，它们不影响最终PDF，但会占目录空间。在settings.json里加一段清理规则，每次编译后自动清除：

json复制"latex-workshop.latex.clean.fileTypes": [
    "*.aux", "*.log", "*.bbl", "*.blg", "*.out", "*.toc",
    "*.synctex.gz", "*.fls", "*.fdb_latexmk"
]

2.3 第一次拉通编译：用最小文档验证环境

环境配置完，别急着拷入大论文模板，先新建一个最小测试文件，确认整条编译链路是通的。我在任意目录新建test.tex，写入：

latex复制\documentclass{article}
\usepackage[UTF8]{ctex}
\begin{document}
你好，LaTeX 本地部署测试。
\end{document}

然后按VS Code里的编译按钮（也可以用快捷键Ctrl+Alt+B），等几秒后右侧应该弹出PDF预览。看到“你好，LaTeX 本地部署测试。”这句话出现在PDF里，说明Tex Live、环境变量、VS Code插件、xelatex引擎、ctex宏包、PDF预览器这一整条链路全部正常。

第一次编译通常会慢一些，因为xelatex要加载字库和宏包，后面再做增量编译就快多了。如果这一步出了问题，多半是之前Path没配好或者ctex宏包缺失。值得提一句的是，测试文件里不要用test命名，某些Windows环境下test保留词可能引发奇怪的问题，我习惯命名为mwe.tex（Minimal Working Example）。

3. 高频遇到的操作与排版细节：斜杠、公式、参考文献、图片布局

3.1 反斜线命令是怎么工作的：从按键到效果

热搜词里“latex右斜线怎么打”其实是个高频困惑，严格来说，LaTeX所有命令的开头都是反斜线\，不是右斜线/。在键盘上，反斜线的位置通常在退格键左边、回车键上方，一个键两个符号，上面是|，下面是\。很多人在中文输入法状态下按这个键，打出的是顿号、，因为输入法把按键接管了。解决办法很简单，切到英文输入模式再按，或者临时按Shift键切换中英文状态。

\在LaTeX里的作用是引入命令，比如\section{标题}表示一级章节标题，\textbf{加粗}表示粗体，\begin{document}表示文档环境开始。理解了这个机制，你就明白为什么LaTeX源码里会有一堆“斜杠加英文单词”，它们不是装饰，而是控制文档结构的语法。

需要补充的是，命令分两类：有参数的命令和无参数的命令。有参数的命令用花括号包裹参数，例如\section{引言}；无参数的命令直接使用，例如\newpage表示另起一页。还有一类带星号变体的命令，比如\section*{标题}表示不编号的章节标题。这些都是非常高频的语法点。

3.2 数学公式与连等排版：高频率用法整理

LaTeX最大的优势是数学公式排版。公式分为行内公式和行间公式。行内公式用一对美元符号包裹，比如$E=mc^2$，效果是公式嵌在文字行里；行间公式用\[和\]包裹，或者直接用equation环境：

latex复制\begin{equation}
E = mc^2
\label{eq:energy}
\end{equation}

带编号的行间公式是论文里的主力。\label和\ref配合可以实现公式交叉引用，正文里写“见公式(\ref{eq:energy})”，编译后会自动填充公式编号。

“latex连等”的热搜词我猜测说的是多行公式等号对齐。多行连等最标准的写法是用align环境：

latex复制\begin{align}
(a + b)^2
&= a^2 + 2ab + b^2 \\
&= a^2 + b^2 + 2ab.
\end{align}

这里的关键是&=，它的作用是让每一行的等号在同一个垂直位置对齐。\\表示换行。如果不需要编号，用align*环境。初次用alignment时最常犯的错误是忘记在等号前加&，结果各行左对齐而不是等号对齐，输出效果很乱。

上标下标是另一个高频操作，上标用^，下标用_，例如x^2、a_i。如果上标下标有多个字符，必须用花括号括起来，写成x^{2n}、a_{i,j}，否则只对紧邻的第一个字符生效。这是新手最容易混淆的规则。

3.3 参考文献引用的两种方法：手动列表与BibTeX

“latex如何加入参考文献”和“latex引用两篇参考文献格式”这两个热搜词几乎是同一问题的两面。参考文献有两种主流做法，我先说最直白的手动列表法，再介绍更专业的BibTeX。

手动列表法是在文档末尾直接用thebibliography环境：

latex复制\begin{thebibliography}{99}
\bibitem{ref1} 作者. 文章标题[J]. 期刊名, 2024, 12(3): 45-50.
\bibitem{ref2} 作者. 书名[M]. 出版社, 2023.
\end{thebibliography}

正文中引用用\cite{ref1}。如果要同时引用两篇，可以写\cite{ref1, ref2}，效果是方括号里包含两个编号，例如[1,2]。这个写法在期刊投稿里非常常见，就是“引用两篇参考文献格式”的实际答案。

BibTeX是更规范的做法，适合参考文献数量多、需要统一管理条目的场景。首先建一个.bib文件，比如叫refs.bib，里面写条目：

bibtex复制@article{ref1,
  author  = {张三 and 李四},
  title   = {关于LaTeX本地部署的研究},
  journal = {计算机应用},
  year    = {2024},
  volume  = {44},
  number  = {3},
  pages   = {45-50}
}

然后在LaTeX源码的\begin{document}之后，或者末尾处，按顺序写：

latex复制\bibliographystyle{unsrt}
\bibliography{refs}

\bibliographystyle{unsrt}表示参考文献按正文引用顺序编号，plain则表示按作者字母排序。编译流程比纯xelatex多了一步：先xelatex编译一次，再运行bibtex，最后再跑两遍xelatex让交叉引用稳定。这正好对应我前面VS Code配置里的xelatex -> bibtex -> xelatex * 2方案。

注意：使用BibTeX时，.bib文件名和LaTeX主文件名不要包含中文和空格，否则bibtex工具解析时容易出错。这算是本地部署环境里一个非常隐蔽的坑。

3.4 双栏页面的图片排版技巧（含作者照片并排）

期刊模板多数是双栏排版。单栏width环境下，普通figure环境插入的图片只能在当前栏内浮动，图片宽度超过栏宽时会强行溢出或变形。双栏页面跨栏插图需要用带星号的figure*环境：

latex复制\begin{figure*}
    \centering
    \includegraphics[width=0.8\textwidth]{figure.png}
    \caption{跨双栏的宽幅图片}
\end{figure*}

figure*只能放在页面顶部或独占一页（LaTeX默认不允许它出现在页面中部），这是双栏排版机制决定的。如果不需要跨栏，只希望图片在栏内不“飞”得太远，可以用浮动参数控制位置：\begin{figure}[htbp]，四个字母分别表示当前位置、页顶、页底、独立浮动页，LaTeX会按字母顺序尝试放置。

热搜词里还有个问题，“如何 在作者介绍文字 左侧 加照片”，这个在双栏模板里也有标准解法，用两个minipage并排，左边放图片，右边放文字：

latex复制\begin{minipage}{0.25\textwidth}
    \includegraphics[width=\linewidth]{author.jpg}
\end{minipage}
\hfill
\begin{minipage}{0.7\textwidth}
    作者简介：某某某，研究方向为自然语言处理。
\end{minipage}

两个minipage的总宽度不要超过\textwidth，我通常左边留0.25、右边留0.7，中间用\hfill撑开间距。\includegraphics[width=\linewidth]让图片自动适配左侧容器的宽度，防止图片溢出。

图片和表格的浮动位置，是本地排版里最让人头疼的环节之一。我的经验是：只要不影响阅读顺序，[htbp]参数就已经够用；如果插图必须出现在某段之后，可以考虑用\FloatBarrier强制提前输出浮动体。后者需要引入placeins宏包，写论文时很实用。

4. 本地编译最常见的报错与排查实录

4.1 装了找不到命令？多半是环境变量没刷

我刚装完TeX Live时遇到的第一类报错是“pdflatex不是内部或外部命令”。这不代表LaTeX没装好，八成是Path环境变量没有生效。安装目录的bin路径加进Path后，必须开一个新的命令行窗口，旧窗口不会自动刷新环境变量。

另一个容易忽略的问题是安装路径有中文或空格，比如D:\软件\texlive\2024。xelatex在Windows下对中文路径的处理并不稳定，建议安装目录保持全英文。同理，LaTeX项目文件夹也最好用英文命名，有些宏包对中文目录名支持很差，编译时会抛出一堆看不懂的路径错误。

如果确认Path没问题但命令还是找不到，可以用完整路径验证，例如直接执行C:\texlive\2024\bin\windows\xelatex --version。能输出版本号说明文件确实装了，问题只出在环境变量上，再回头检查Path是否加入系统变量而非用户变量。

4.2 宏包缺失、字体报错和中文乱码

完整版TeX Live装好后，宏包缺失的概率很低，但如果用的是精简版或后期更新版本，仍然会遇到File 'xxx.sty' not found。这个错误的意思是缺少对应的宏包。在TeX Live下用tlmgr install 包名手动安装：

bash复制tlmgr install ctex
tlmgr install enumitem
tlmgr install subcaption

如果提示没有权限，要在命令前加sudo（macOS/Linux下），或者以管理员身份打开终端（Windows下）。MiKTeX则一般会在编译时弹出自动安装宏包的提示，这一点确实省事。

中文字体问题是中文LaTeX编译的另一大坑。用ctex宏包配合xelatex，通常能自动处理系统里常见的中文字体。如果在Linux服务器上部署，系统里可能没有任何中文字体，编译时ctex会报Cannot find font。解决办法是安装中文字体包，Ubuntu下可以用apt install fonts-noto-cjk fontconfig，装完刷新字体缓存：

bash复制fc-cache -f

Windows下一般不存在这个问题，因为系统自带SimSun等字体，ctex能直接调用。如果遇到乱码，先检查源文件编码格式是不是UTF-8，VS Code右下角可以切换，LaTeX对GBK编码的支持比较差。这里我建议所有项目统一UTF-8，省掉所有编码相关的麻烦。

4.3 BibTeX 与 Biber：参考文献总编不出来的真相

参考文献编译不出来，常发生在从在线编辑器迁移到本地的场景。在线平台通常自动帮你跑完整个编译链，本地环境则需要自己配置recipe。如果使用BibTeX，主文件里要写\bibliography{refs}，然后按xelatex→bibtex→xelatex→xelatex的顺序编译。如果漏了bibtex这一步，正文中的\cite只会显示问号“?”。

如果你用的是biblatex宏包加biber后端，情况又不一样。biblatex是比BibTeX更现代的参考文献方案，子集格式更丰富，但编译顺序最后一步是biber而不是bibtex。VS Code的LaTeX Workshop里，需要额外添加一个Biber工具配置。

我在实际项目中更倾向于biblatex + biber，因为它在处理非英语文献、URL前缀和字体控制上更灵活。但期刊模板如果明确要求用BibTeX，我会按模板来，毕竟投稿以期刊要求为准，不建议为了用biblatex强行改动模板。

4.4 编译清理与增量编译：让重跑速度回到秒级

本地编译还有一个实用话题：增量编译。xelatex默认每次全量编译，文档页数多了以后，一次编译可能要十几秒甚至几十秒。Latexmk工具可以监控文件变化，只重编发生改动的部分。LaTeX Workshop里配置latexmk的recipe：

json复制{
    "name": "latexmk",
    "command": "latexmk",
    "args": ["-xelatex", "-synctex=1", "-interaction=nonstopmode", "-file-line-error", "%DOC%"]
}

这样每次保存时按编译快捷键，自动跳过没有变化的中间文件，速度提升非常明显。配合Synctex，在PDF里按住Ctrl点击某段文字，可以精确跳转到源码对应行，反向同步是长文档修订的利器。

日志文件aux和log的清理也要养成习惯。每次编译后残留的辅助文件越来越多，有时会影响下一次编译的交叉引用结果，尤其是改过章节编号后，旧的.aux缓存会让目录显示错误页码。用LaTeX Workshop自带的清理命令（默认为Clean up auxiliary files）就能处理。

我个人在实际项目里的习惯是：新建一个build子目录，把所有中间文件输出到那里，主目录只保留.tex源码、.bib文献库和最终的PDF。这样既方便备份，也避免辅助文件污染版本管理。配置方式是在LaTeX Workshop的tools参数里加-output-directory=build，前提是先把build目录建好。

最后再分享一个建议：本地部署LaTeX不是一锤子买卖，别装完环境、编出一份PDF就觉得完事了，要把常用模板、常用宏包和参考文献库沉淀成自己的“个人LaTeX工具箱”。我用了两年本地环境之后，最大的体会是，在线编辑器只是一个入口，真正能让你专注写作的是稳定的工具链和本地目录习惯。遇到问题不要急着重装，先去日志文件里找关键错误行，绝大多数坑都能在output.log里找到直接线索。