上周帮同事在自己的笔记本上从零装 LaTeX从下载镜像到跑出第一份中文 PDF前后花了两个多小时——其中真正点击下一步的时间不到十分钟剩下的全耗在镜像选择、路径命名和环境变量这些细节上。这篇 Latex 详细安装教程就是想把这些不该花的时间省掉。我说的 LaTeX 不是某个单一软件而是一整套排版工具链一个负责排版的发行版里面装着几千个宏包和编译器、一个负责写代码的编辑器、再加上一层把它们连起来的配置。装好之后你能做什么写论文、排简历、出书籍、做公式密集的技术文档尤其是那种公式多到 Word 会卡死的场景LaTeX 的优势就非常明显。这篇内容适合三类人看完全没碰过命令行、只想赶紧把环境装起来的新手装过一次但被报错劝退、想彻底搞明白原理的中级用户以及需要在多台机器、多个系统上重复部署环境的老手。下面我会按选型—安装—配置—验证—排错的顺序,一步步拆开讲,每个参数为什么这么设,我都会说明理由。1. 本地 LaTeX 值不值得装先算一笔时间账1.1 什么情况下必须装本地环境很多人第一反应是用在线编辑器不就行了。在线方案确实省事打开浏览器就能写但对于几类场景它撑不住一是论文投稿期刊模板动辄要求特定的宏包版本和编译顺序在线编辑器不一定装了你需要的包二是文档体量大几百页带几十张图的毕业论文在线编译排队能等到你没脾气三是断网环境、内网环境学校机房或者公司内网根本连不上外部服务四是需要版本控制你想把源文件丢进 git 做提交历史本地环境天然支持。所以判断标准很简单只要你写的东西超过十页、或者需要长期反复修改、或者涉及机构模板本地环境就是刚需。1.2 三套常见方案的横向对比我把常见的组合列成一张表方便你按自己的情况对号入座。这张表里的上手难度是我按周围非计算机专业同事的平均感受估的仅供参考。方案发行版编辑器上手难度适合人群主要代价省心组合MiKTeXTeXstudio低只想写文档的新手宏包按需下载首次编译慢主流组合TeX LiveVS Code LaTeX Workshop中需要长期维护文档的人初始安装体积大、耗时长极客组合TeX Live终端 latexmk高熟悉命令行、要自动化的人学习曲线陡排错全靠日志选哪套没有绝对对错。我给身边人的默认推荐是主流组合理由是 TeX Live 的宏包完整度最高一次装完基本不会再遇到缺包问题VS Code 又是大多数人的日常编辑器不用再额外学一个软件的界面。如果你连终端都不想打开那省心组合更适合你MiKTeX 检测到缺宏包会自动弹窗询问是否下载这个特性对新手非常友好。2. 工具链三层拆解发行版、编辑器、编译引擎2.1 发行版TeX Live、MiKTeX、MacTeX 到底怎么选发行版是整个体系的地基它决定了你手里有多少宏包、编译器是什么版本。TeX Live 是跨平台的Windows、Linux、macOS 都能装宏包覆盖面最广每年发一个版本前面冠以年份比如 2024 版、2025 版。它的坑在于安装包大完整版接近 8 GB安装过程视网速要半小时到一小时。MiKTeX 主要面向 Windows优点是按需装包你文档里用到哪个宏包它才下载哪个初始安装几百兆就够缺点是首次编译时反复弹窗、依赖网络在网络受限的环境下反而更麻烦。MacTeX 本质是 TeX Live 的 macOS 定制版把配置和字体处理都帮你做好了代价是体积同样很大。注意发行版不要装两个。TeX Live 和 MiKTeX 同时存在时环境变量 PATH 里谁在前面谁生效你会遇到明明装了宏包却提示找不到这种诡异问题。装新的之前把旧的卸干净。2.2 编辑器TeXstudio 与 VS Code 的取舍编辑器只是外壳它本身不负责排版真正干活的是后台的编译器。理解这一点你就不会纠结哪个编辑器的排版效果更好这种伪命题了。TeXstudio 是专门为 LaTeX 做的编辑器开箱即用左侧大纲、右侧 PDF 预览、中间写代码快捷键和补全都是为排版定制的缺点是界面偏老派主题和动画不够现代。VS Code 加 LaTeX Workshop 扩展是我的日常配置好处是写代码、写 Markdown、写 LaTeX 全在一个窗口里git 集成也顺代价是需要手动写一段配置才能把编译链跑通。选哪个如果你只写 LaTeXTeXstudio 更省心如果你本来就在用 VS Code那别折腾了装个扩展就行。2.3 编译引擎xelatex、pdflatex、lualatex 什么时候用哪个这是新手最容易混淆的一层。简单说编译器负责把 .tex 源文件转成 PDF而不同编译器对字符编码和字体的处理方式不一样。pdflatex元老级引擎速度快、兼容性最好但它对 Unicode 支持有限处理中文需要额外的宏包配置一般不推荐新手直接用。xelatex原生支持 Unicode可以直接调用系统字体中文排版首选速度中等。lualatex功能最强支持 Lua 脚本扩展字体处理方式更现代但某些老宏包兼容性不如 xelatex编译速度也偏慢。我的建议很直接只要文档里有中文就用 xelatex。这条规则能帮你避开八成的中文乱码和字体缺失问题。后面第三章里 VS Code 的配置我给的也是以 xelatex 为主的编译配方。3. Windows 平台完整安装流程3.1 下载与镜像选择为什么强烈建议换源TeX Live 官方主站下载国内访问速度往往惨不忍睹安装过程还会因为超时中断。解决办法就是用国内镜像站。下载页面打开后找到国家/地区镜像列表选一个响应快的站点进去之后找install-tl-windows.exe这个在线安装器或者更稳妥的做法是直接下 ISO 镜像文件用虚拟光驱加载后离线安装——ISO 方式的好处是安装过程不依赖网络中途不会因为断线失败。提示ISO 文件几个 GB建议用支持断点续传的下载工具。下完之后核对一下官方给出的校验值避免文件损坏导致安装到一半报错这种问题排查起来非常折磨人。3.2 安装参数逐项拆解双击安装器后界面上的选项别一股脑点下一步有几项值得停下来想想。安装方案Scheme默认是 full全量安装占盘大约 8 GB。如果你的硬盘紧张可以选 basic 或者 small之后再通过tlmgr按需补装宏包。但我个人的经验是省这几 GB 换来的麻烦不划算——写论文时频繁遇到缺包每次都要联网补装时间成本更高。安装路径默认在C:\texlive\年份。我建议就按默认来因为路径里绝对不能出现中文和空格。有人喜欢装到我的文档\软件\LaTeX这类目录结果编译时报一堆莫名其妙的找不到文件错误根源就是路径里的中文字符。环境变量安装界面里有个将 bin 目录添加到 PATH的选项务必勾上。不勾的话你得手动去系统设置里加很多人就是漏了这一步导致命令行里敲tex提示不是内部或外部命令。安装时间full 方案解压几千个文件机械硬盘上跑四十分钟很正常固态盘大概二十到三十分钟。期间不要关闭窗口。3.3 环境变量配置与安装验证装完之后必须验证别等到写文档时才发现环境有问题。打开一个新的命令行窗口注意必须是新开的旧窗口读不到刚更新的 PATH依次敲三条命令tex --version xelatex --version tlmgr --version三条都能正常回显版本号说明安装成功。如果提示找不到命令检查一下 PATH 里有没有C:\texlive\2024\bin\windows这一条年份按你实际装的版本替换。还有一个容易忽略的点确认这个路径下确实存在xelatex.exe和tlmgr.bat有时候杀毒软件会误删尤其是国内某几款安全软件对可执行文件的拦截比较激进。3.4 VS Code LaTeX Workshop 配置实录先装 VS Code然后在扩展市场里搜 LaTeX Workshop装上。接着打开设置切到 JSON 模式快捷键CtrlShiftP输入 Open User Settings (JSON)把下面的配置合并进去{ latex-workshop.latex.tools: [ { name: xelatex, command: xelatex, args: [ -synctex1, -interactionnonstopmode, -file-line-error, %DOC% ] }, { name: bibtex, command: bibtex, args: [%DOCFILE%] } ], latex-workshop.latex.recipes: [ { name: xelatex, tools: [xelatex] }, { name: xelatex - bibtex - xelatex x2, tools: [xelatex, bibtex, xelatex, xelatex] } ], latex-workshop.latex.recipe.default: first, latex-workshop.view.pdf.viewer: tab }配置里每个参数都有用意。-synctex1生成同步文件让你能在源码和 PDF 之间双向跳转写长文档时这个功能能救命-interactionnonstopmode表示遇到错误不要停下来等输入直接往下跑避免编译卡死在终端-file-line-error让报错信息带上文件和行号排查效率翻倍。bibtex 那一步是为了处理参考文献如果你暂时不写引用用第一个单步配方就够。提示latex-workshop.latex.recipe.default设成first之后按CtrlAltB走的是列表里第一个配方也就是单次 xelatex。如果你的文档有参考文献或目录记得手动切成第三个配方否则引用的编号会显示成问号。3.5 跑通第一份中文文档新建一个文件夹路径别带中文里面创建一个test.tex写入\documentclass[UTF8]{ctexart} \begin{document} \title{我的第一份 LaTeX 文档} \author{张三} \maketitle \section{引言} 这是一段中文测试文字用来验证 xelatex 编译链路是否正常。 行内公式示例$E mc^2$。 \end{document}保存后按CtrlAltB编译右侧如果弹出 PDF 预览并且中文正常显示整个环境就算彻底打通了。如果中文显示成方块或者直接空白先别慌多半是编译器选错了——确认你用的是 xelatex 而不是 pdflatex这一点在第四章会详细展开。4. macOS 与 Linux 的安装差异4.1 macOSMacTeX 全量包与 BasicTeX 的取舍macOS 上最省事的是 MacTeX下载一个 pkg 安装包一路下一步大概 5 GB 左右装完自带 TeXShop 编辑器、BibDesk 文献管理工具TeX Live 的宏包也全都在。如果你的固态盘实在紧张可以选 BasicTeX压缩包不到 200 MB但它只带最基础的宏包中文排版、绘图相关的包基本都得用sudo tlmgr install手动补。我的判断是只要是长期用就上 MacTeX 全量包省下来的时间远比硬盘空间值钱。安装时还有一个细节安装器会问你是否把 TeX 的 bin 目录加到 PATH选是不然后面命令行调不动。4.2 Ubuntu 与 Debianapt 源安装的正确姿势Linux 上很多教程直接让你sudo apt install texlive-full这条命令能装但有两个问题一是版本可能比官方 TeX Live 落后一两年某些新宏包用不了二是 apt 的 TeX Live 和官方安装脚本混装会互相打架。我的做法是分情况如果你只是临时写点东西apt 够用装这一组就差不多sudo apt update sudo apt install texlive-latex-base texlive-latex-recommended \ texlive-latex-extra texlive-xetex texlive-lang-chinese \ texlive-fonts-recommended latexmk如果你要长期维护学位论文、跟随期刊模板那就去 TeX Live 官网下install-tl-unx.tar.gz解压后运行安装脚本装完再把/usr/local/texlive/2024/bin/x86_64-linux加进 PATH。注意这条路径里的架构名要按你机器的实际输出替换用uname -m能查。4.3 跨平台字体差异带来的连锁反应同一份 .tex 文件在 Windows 上编译正常拷到 Linux 上就报字体找不到这是最常见的一类环境问题根源在字体。Windows 上 ctex 宏包默认调用系统自带的中易宋体、中易黑体这些字体在 Linux 上根本不存在。解决办法有两个一是显式指定字体集比如在文档类选项里写fontsetfandolFandol 是 TeX Live 自带的开源中文字体跨平台都有二是用 fontspec 宏包手动指定具体字体文件。推荐第一种改动最小。如果你在 Linux 上想让系统里的思源黑体生效就先确认fc-list :langzh能列出来再在文档里用 fontspec 指名字体名名字要和fc-list输出的完全一致多一个空格都会失败。5. 装完立刻要用的中文、换行、符号、图片表格5.1 ctex 文档类与中文支持的三条路线中文支持这块ctex 宏包是目前最省心的方案它提供了ctexart、ctexrep、ctexbook三个文档类分别对应文章、报告、书籍你直接用它们替代标准的article、report、book就行。三条可行路线一是文档类路线\documentclass[UTF8]{ctexart}最简单二是宏包路线在标准文档类里\usepackage{ctex}适合必须用特定期刊模板、不能改文档类的情况三是手动路线用xeCJK宏包自己配置字体灵活但配置量大一般用不上。绝大多数人用第一条就够了。这里再强调一遍ctex 的文档必须用 xelatex 或 lualatex 编译用 pdflatex 会直接报错或中文丢失。5.2 换行、分段、空行换行符到底怎么打这个话题问的人特别多我把它讲透。LaTeX 里源码中的一个换行等于一个空格不是换行。想强制换行用双反斜杠\\想分段就空一行源码里敲两次回车。这两个概念别混\\是这一行到此为止下一行接着写常用于诗歌、地址块、表格单元格里空行是新起一个段落段首会自动缩进。还有一个\newline也能换行但和\\在段落对齐时有细微差别日常用\\就行。数学公式里的换行规则又不一样equation环境里根本不能换行要换行得用align或者split环境用对齐、\\断行。表格里单元格内容要用\\结束一行但这个\\前面不能有多余的不然会报 column 数量不匹配。5.3 数学符号与希腊字母速查符号这块不用背用的时候查就行但有几个高频的必须记住。需求写法说明希腊字母小写\alpha\beta\gamma加\var前缀可换形状希腊字母大写\Gamma\Delta\Omega首字母大写即可分数\frac{a}{b}前是分子后是分母根号\sqrt{x}\sqrt[n]{x}方括号里写次数求和、积分\sum_{i1}^{n}\int_a^b上下标用_和^比较符\leq\geq\neq\approx别直接敲偏导、梯度\partial\nabla常在物理公式里出现无穷、乘号\infty\times\cdot点乘和叉乘别搞混注意符号命令只在数学环境里有效。想在正文里写个希腊字母得用$\alpha$包起来直接写\alpha会报 Undefined control sequence。5.4 插入图片与表格自动换行插入图片要先用\usepackage{graphicx}然后用figure环境包起来\begin{figure}[htbp] \centering \includegraphics[width0.8\textwidth]{figures/result.png} \caption{实验结果对比} \label{fig:result} \end{figure}[htbp]是位置建议分别是 here、top、bottom、pageLaTeX 会挑一个合适的位置放不用强求它一定在你写代码的地方。width0.8\textwidth表示占正文宽度的八成比直接写像素值稳妥换纸张尺寸也不用改。\label和\ref配合用正文里写如图\ref{fig:result}所示编号会自动更新。表格自动换行是另一个高频痛点。标准的tabular环境里单元格内容不会自动折行长文本会直接撑破页面。解法是用tabularx宏包把列类型写成X\usepackage{tabularx} \begin{tabularx}{\textwidth}{|l|X|} \hline 项目 说明 \\ \hline 编译引擎 xelatex 支持 Unicode 和系统字体中文文档首选 \\ \hline \end{tabularx}X列会自动分配剩余宽度并换行。如果只是某个单元格里需要手动断行用makecell宏包的\makecell{第一行\\第二行}也行适合内容不多的情况。6. 报错排查与编译提速实录6.1 高频报错速查表下面这张表是我这些年真正遇到过的报错按出现频率排序建议收藏。报错信息常见原因解决办法File xxx.sty not found宏包没装tlmgr install xxxFont ... not found字体缺失或字体集不匹配加fontsetfandol或装字体Undefined control sequence命令拼错或漏引宏包核对拼写补\usepackageMissing $ inserted数学符号写在了正文里用$...$包起来I cant write on file文件被占用或无写权限关掉 PDF 阅读器换目录Emergency stop严重错误通常前面有真凶往上翻日志找第一条错误Overfull \hbox行超宽不是致命错误检查长公式或长网址排查有个通用心法日志里第一个 Error 才是真凶后面的往往是被连累的。很多人看到满屏红字就慌其实只要找到第一条解决它后面一大片报错会自己消失。6.2 宏包缺失的补装方法TeX Live 用tlmgr补包先更新自身再装目标sudo tlmgr update --self sudo tlmgr install ctex tabularx makecellWindows 上如果有权限问题就以管理员身份打开命令行。注意tlmgr的仓库地址如果访问慢可以换镜像tlmgr option repository 镜像地址。MiKTeX 用户不用手动装编译时它会自己弹窗问你要不要下载点确认即可但前提是网络通畅。6.3 编译提速与临时文件治理编译慢主要慢在重复处理图片和目录。几个实用技巧一是草稿模式在导言区加\usepackage[draft]{graphicx}图片位置只画个框不实际渲染能快一大截定稿时再去掉二是用\includeonly{chapter3}只编译正在改的那一章三是用latexmk -pvc做增量编译它会盯着源文件变化自动重编省去反复敲命令。临时文件方面一次编译会产生.aux、.log、.out、.toc、.synctex.gz一堆东西用latexmk -c可以清理干净但保留 PDFlatexmk -C连 PDF 一起删。VS Code 里配置好的latex-workshop.latex.clean.fileTypes就是干这个的点一下清理按钮就行。提示.aux文件别随手删。目录、交叉引用、参考文献编号都靠它传递删了之后至少要连编两次才能恢复遇到引用变成问号的情况先想想是不是刚删过 aux。7. 我的长期维护习惯与几个压箱底技巧装好只是开始真正决定你用起来顺不顺的是后面这些习惯。我自己的做法是机器上只保留一个 TeX Live 版本每年新版发布后不着急升等目标期刊的模板确认兼容了再升升级前把老版本的texmf-local目录备份出来里面放的是自己改过的宏包和自定义样式重装后直接拷回去就能用。字体这块我统一用 Fandol不管在 Windows 还是 Linux 上都指定fontsetfandol这样同一份文档换机器编译不会出岔子代价是字形没那么好看但对保证可复现性来说值得。再分享一个排错小技巧遇到完全看不懂的报错把文档内容删到只剩最简结构如果还能复现说明问题在导言区如果不能复现就用二分法把段落一段段加回去很快能定位到出问题的那一行。这招听起来笨但比重读几百行日志快得多。另外一个很多人不知道的点是\typeout{检查点}可以在编译日志里打印自定义信息用来确认某个宏包到底有没有被加载、某个分支有没有执行到调试复杂模板时特别好用。最后说个关于编辑器的心得。我用了几年 TeXstudio后来彻底转到 VS Code原因不是 TeXstudio 不好而是我不想在写代码、写文档、管 git 之间来回切窗口。工具链这东西统一比先进更重要。你要是已经习惯了 TeXstudio 的 PDF 预览和正向反向搜索那就继续用别为了追新折腾自己。环境装好之后真正的门槛其实是宏包的用法和排版思维那些内容靠多写多查慢慢积累装的这一步一次搞对就够了。