Mac 上高效编写 LaTeX：VSCode + LaTeX Workshop 完全配置指南
1. 为什么要在 Mac 上用 VSCode 写 LaTeX？
如果你和我一样，曾经是 Overleaf 的忠实用户，那你肯定也经历过在论文截止日期前夜，网站突然卡顿或者加载缓慢的焦虑。在线编辑器虽然方便，但把写作的命脉交给网络和服务器，总感觉心里不踏实。尤其是在处理几十上百页、包含大量图表和参考文献的学位论文时，那种等待编译的焦灼，以及担心网络中断的忐忑，实在影响创作心流。
于是，我决定把 LaTeX 写作环境搬回本地。在 Mac 上，选择其实不少：有老牌的 TeXShop，也有功能强大的 Texpad。但最终，我选择了Visual Studio Code (VSCode) + LaTeX Workshop 插件这个组合。原因很简单：VSCode 是我日常开发的主力编辑器，它的轻量、快速和强大的扩展生态让我爱不释手。如果能在一个我早已熟悉的编辑器里无缝编写 LaTeX，那岂不是事半功倍？
这个组合带来的体验提升是巨大的。首先，编译速度飞快，所有运算都在本地完成，再也不用排队等待云端服务器的资源。其次，写作体验高度可定制，VSCode 的快捷键、主题、代码片段功能可以完全按照你的习惯来配置，效率直接拉满。最后，离线工作毫无压力，无论身处何地，只要带着你的 MacBook，就能安心写作。接下来，我就手把手带你完成从零到一的完整配置，打造一个专属于你的、高效顺滑的 Mac 本地 LaTeX 写作环境。
2. 基础环境搭建：安装 LaTeX 发行版
工欲善其事，必先利其器。在 Mac 上运行 LaTeX，我们需要先安装一个 LaTeX 发行版，它包含了编译引擎、宏包、字体等所有必需组件。对于 Mac 用户，最省心的选择就是MacTeX。
2.1 下载与安装 MacTeX
MacTeX 是 TeX Live 发行版针对 macOS 的定制版本，打包了所有常用工具和一个图形化编辑器 TeXShop。不过我们主要用它的命令行工具。
第一步：获取安装包最直接的方法是访问 MacTeX 官网。但官网服务器在国外，国内下载速度可能很慢。这里我强烈推荐使用国内高校的镜像站，速度会快很多。以下是我亲测可用的镜像（请根据网络情况选择）：
- 清华大学镜像站
- 中国科学技术大学镜像站
- 上海交通大学镜像站
在这些镜像站的/systems/mac/mactex/目录下，可以找到最新版本的MacTeX.pkg文件进行下载。文件大约 4-5 GB，建议在稳定的网络环境下进行。
第二步：执行安装下载完成后，你会得到一个.pkg文件。双击打开，就像安装其他 macOS 应用一样，一路点击“继续”、“同意”、“安装”即可。安装过程需要输入你的电脑密码，并且会占用大约 5 GB 的磁盘空间。安装完成后，建议重启一次电脑，以确保所有路径和环境变量生效。
2.2 验证安装与环境变量配置
安装完成后，我们需要打开终端（Terminal）验证一下。打开“终端”应用，输入以下命令：
latex --version如果安装成功，你会看到类似pdfTeX 3.14159265...这样的版本信息输出。
接下来，检查 LaTeX 的可执行文件路径是否已经添加到系统的PATH环境变量中。在终端输入：
echo $PATH查看输出的路径列表中是否包含/Library/TeX/texbin。如果能看到这个路径，说明配置正确。
如果没看到这个路径怎么办？别担心，这是新手常遇到的问题。手动添加一下即可。用你喜欢的文本编辑器（比如nano或vim）打开用户目录下的.zshrc文件（如果你使用的是 macOS Catalina 及以后版本，默认 shell 是 zsh）：
nano ~/.zshrc在文件的末尾，添加下面这行：
export PATH=$PATH:/Library/TeX/texbin然后按下Ctrl + X，再按Y确认保存，最后按回车退出。为了让配置立即生效，在终端执行：
source ~/.zshrc再次执行echo $PATH，现在应该就能看到/Library/TeX/texbin路径了。这个步骤至关重要，它保证了 VSCode 在后台调用xelatex、pdflatex等命令时，系统能够正确找到它们。
3. 核心编辑器配置：VSCode 与 LaTeX Workshop
基础环境搞定后，接下来就是打造我们的“主战场”——VSCode。
3.1 安装 Visual Studio Code
如果你还没安装 VSCode，可以去其官网下载。选择 Apple Silicon 或 Intel 芯片版本，下载后拖入“应用程序”文件夹即可。安装过程非常简单。
3.2 安装并初步认识 LaTeX Workshop 插件
打开 VSCode，点击侧边栏的“扩展”图标（或使用快捷键Cmd + Shift + X），在搜索框中输入LaTeX Workshop。你会看到由James-Yu维护的插件，认准这个名字，它有超过一千万的下载量，是事实上的标准。点击“安装”按钮。
安装完成后，你的 VSCode 左侧活动栏会多出一个 TeX 图标（一个蓝色的“TΣ”符号），这就是 LaTeX Workshop 的入口。同时，当你打开一个.tex文件时，编辑器会自动进行语法高亮，右上角会出现编译和预览的按钮。这个插件的强大之处在于，它把编写、编译、预览、调试 LaTeX 文档的所有功能都集成在了 VSCode 内部，让你无需离开编辑器。
3.3 深度配置 LaTeX Workshop（JSON 设置）
默认设置可能无法满足我们所有的需求，尤其是涉及到中文编译、参考文献处理等复杂场景时。我们需要对插件进行深度配置。VSCode 的设置有两种方式：图形界面（UI）和 JSON 文件。为了更精准地控制，我推荐直接修改 JSON 配置文件。
使用快捷键Cmd + Shift + P打开命令面板，输入Preferences: Open User Settings (JSON)并选择。这会在编辑器打开你的用户设置文件settings.json。我们将把 LaTeX Workshop 的配置粘贴到这个文件的大括号{}内。
下面是我经过多年使用，优化后的一份配置，你可以直接复制使用。我会逐段解释关键部分的作用：
// LaTeX Workshop 核心配置 "latex-workshop.latex.autoBuild.run": "onSave", // 保存时自动编译，提升效率 "latex-workshop.latex.autoClean.run": "onBuilt", // 编译后自动清理中间文件 "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", "*.nav", "*.snm", "*.synctex.gz" ], "latex-workshop.latex.tools": [ // 定义可用的编译工具 { "name": "xelatex", "command": "xelatex", "args": [ "-synctex=1", "-interaction=nonstopmode", "-file-line-error", "-pdf", "%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%", "-xelatex", // 使用 xelatex 引擎 "%DOC%" ] } ], "latex-workshop.latex.recipes": [ // 定义编译配方（工作流） { "name": "xelatex (一次编译)", "tools": ["xelatex"] }, { "name": "xelatex -> bibtex -> xelatex*2 (含参考文献)", "tools": ["xelatex", "bibtex", "xelatex", "xelatex"] }, { "name": "latexmk (自动处理交叉引用和参考文献)", "tools": ["latexmk"] } ], "latex-workshop.latex.recipe.default": "lastUsed", // 默认使用上次的配方 "latex-workshop.view.pdf.viewer": "tab", // 在 VSCode 内部标签页预览 PDF "latex-workshop.synctex.afterBuild.enabled": true, // 编译后启用正向同步 "latex-workshop.synctex.keybinding": "double-click", // 双击 PDF 反向同步 "latex-workshop.message.error.show": false, // 不弹出错误框，在问题面板查看 "latex-workshop.message.warning.show": false配置详解与个性化建议：
- 编译引擎选择：我主要配置了
xelatex和pdflatex。对于绝大多数中文用户，xelatex是更好的选择，因为它原生支持 Unicode 和系统字体，处理中文非常简单，无需额外配置CJK宏包。pdflatex则对某些特殊宏包兼容性更好。 - 编译配方（Recipes）：这是核心。
xelatex (一次编译)适合快速查看简单修改；xelatex -> bibtex -> xelatex*2是处理参考文献的标准流程，需要运行多次编译器来生成正确的引用编号；latexmk是一个自动化工具，它能自动判断需要运行多少次编译，对于复杂的文档非常省心，我通常将其作为默认。 - 同步（SyncTeX）：这是提升效率的神器！配置中的
synctex相关选项，实现了源代码和 PDF 的双向定位。在.tex文件里按Cmd + Option + J，光标会跳转到 PDF 的对应位置；在 PDF 预览里双击某个位置，编辑器会自动打开并定位到对应的源代码行。查错、调整排版时无比方便。 - PDF 预览位置：我设置为
"tab"，让 PDF 在编辑器内以标签页形式打开，切换起来更快捷。你也可以设置为"external"用系统默认阅读器（如预览.app 或 Skim）打开。
保存这个settings.json文件，配置就生效了。你可以根据自己后续的使用体验微调这些参数。
4. 效率提升：必备辅助工具与插件
基础环境搭建好了，但要想真正写得“爽”，还得靠一些辅助工具和插件来武装我们的 VSCode。
4.1 PDF 阅读器的选择：内置预览 vs 外部工具
LaTeX Workshop 内置的 PDF 预览器已经非常强大，支持同步、缩放、搜索。对于大多数场景，完全够用。但如果你需要更专业的 PDF 阅读功能，比如连续滚动模式、更好的注释工具，可以考虑外部阅读器。
在 Mac 上，除了系统自带的“预览”，学术界很多人推荐Skim。它轻量、免费，并且对 SyncTeX 支持得非常好。安装 Skim 后，需要在 VSCode 设置中指定外部阅读器路径，并启用外部同步。不过，根据我个人的经验，VSCode 内置预览的同步响应速度更快，与编辑器集成度更高，所以我更倾向于使用内置预览。除非你有大量 PDF 批注需求，否则建议先体验内置预览。
4.2 强烈推荐的 VSCode 辅助插件
VSCode 的插件市场里有很多能极大提升 LaTeX 写作体验的插件，这里推荐几个我离不开的：
- LaTeX Utilities：这个插件补充了 LaTeX Workshop 的一些实用功能。比如，它可以为
\ref{},\cite{}等命令提供悬浮预览，直接显示被引用的标签内容或文献条目，无需跳转。它还提供了快速插入数学环境、图片环境的命令，非常方便。 - Code Spell Checker：英语拼写检查器。写论文时拼写错误很影响观感，这个插件能实时在
.tex文件中检查英文单词拼写，并给出纠正建议。你可以为它添加科学词汇词典，避免专业术语被误报。 - GitLens：如果你的论文是用 Git 进行版本管理（强烈推荐！），那么 GitLens 必不可少。它能让你在行内看到每一行的最近修改者和时间，方便回溯和协作。
- Todo Tree：写长文档时，我们经常在代码中留下
% TODO: ...这样的注释。Todo Tree 插件能扫描整个项目，把所有 TODO 项收集到一个侧边栏树状图中，方便跟踪和管理写作进度。
4.3 高效写作技巧与快捷键
配置好工具，再来点“软技能”，让你的写作行云流水。
首先，善用代码片段（Snippets）。VSCode 支持自定义代码片段。你可以为常用的 LaTeX 结构创建片段。例如，创建一个输入beg后按 Tab 键就能展开为\begin{}和\end{}环境的片段。LaTeX Workshop 和 LaTeX Utilities 插件已经自带了很多片段，比如输入/可以快速插入各种数学符号。
其次，掌握核心快捷键：
Cmd + Option + B：使用默认配方编译当前文档。Cmd + Option + V：在侧边栏预览 PDF。Cmd + Option + J：从源代码同步到 PDF（正向搜索）。- 在 PDF 预览中
Cmd + 单击：从 PDF 同步到源代码（反向搜索）。 Cmd + S：保存并触发自动编译（如果你设置了"autoBuild.run": "onSave"）。
最后，组织好项目结构。对于一个大型论文项目，不要把所有内容都堆在一个.tex文件里。合理的做法是：一个主文件（如main.tex）负责文档类型、宏包引入和章节组织，各个章节（chapter1.tex,chapter2.tex）则用\input{}或\include{}命令引入。图片统一放在figures/文件夹，参考文献数据库放在refs.bib。这样结构清晰，也便于管理。
5. 进阶配置与疑难排错
当你开始用这个环境处理真正的项目，尤其是复杂的学术论文时，可能会遇到一些挑战。这里分享几个进阶配置和常见问题的解决方法。
5.1 处理复杂项目：多文件、参考文献与索引
对于包含多个子文件的项目，确保你的编译配方（比如latexmk）是针对主文件（main.tex）运行的。LaTeX Workshop 通常能自动检测到主文件。如果检测失败，你可以在.tex文件的开头添加魔法注释来指定：% !TEX root = ../main.tex。
参考文献（BibTeX/Biber）：我的配置里已经包含了处理 BibTeX 的配方。你需要确保：
- 在文档中正确使用
\bibliographystyle{}和\bibliography{}命令（或biblatex宏包）。 - 编译时选择正确的配方，例如
xelatex -> bibtex -> xelatex*2。latexmk配方会自动处理这个过程。 - 如果使用更现代的
biblatex+biber后端，你需要在tools和recipes中添加对应的biber工具和配方。
生成索引和术语表：这需要额外运行makeindex或xindy命令。你可以在tools中定义新的工具，并在recipes中创建包含这些步骤的更长的工作流。例如：xelatex -> makeindex -> xelatex。
5.2 常见编译错误与解决方案
即使配置正确，编写过程中也难免遇到编译错误。LaTeX Workshop 会将错误和警告信息实时显示在“问题”面板（Problems Panel）中。
- “File
xxx.clsorxxx.stynot found”：这是缺少宏包。首先，尝试用 TeX Live 自带的包管理器tlmgr在线安装。在终端运行sudo tlmgr install <package-name>。如果网络不行，可以去 CTAN 手动下载.sty或.cls文件，放到你的项目目录或本地 TeX 目录树中。 - 字体找不到：使用
xelatex时，如果提示字体缺失，确保字体名拼写正确，并且该字体已安装在你的 macOS 字体册中。你可以使用fc-list命令在终端查看系统已识别的字体列表。 - 编译卡住或无响应：有时复杂的文档或某些宏包会导致编译进程卡死。首先检查“输出”面板，看是否有错误日志。可以尝试：
- 清理所有辅助文件（LaTeX Workshop 有清理按钮）。
- 暂时注释掉疑似有问题的章节或宏包，逐步排查。
- 在
tools的args中加入"-halt-on-error"参数，让编译器在第一个错误处停止，方便定位。
5.3 与 Overleaf 的协同：Git 版本控制
完全脱离 Overleaf 可能不现实，特别是需要与导师或合作者协同编辑时。一个完美的方案是：本地用 VSCode 写作，用 Git 同步到 Overleaf 进行审阅和最终提交。
具体操作是：在 Overleaf 项目中，点击菜单中的“Git”选项，将其与一个 GitHub（或 GitLab）仓库关联。然后，在本地使用git clone将这个仓库克隆下来。之后，你就在本地 VSCode 中工作，使用git commit和git push将更改推送到远程仓库。合作者可以在 Overleaf 上通过“从 Git 拉取”来获取你的最新版本，并在 Overleaf 上做批注；你也可以将 Overleaf 上的修改拉取到本地。这样既享受了本地编辑器的强大和速度，又保留了 Overleaf 的协作便利性。记得在项目根目录添加一个.gitignore文件，忽略所有 LaTeX 生成的中间文件（*.aux,*.log,*.pdf等），只跟踪源代码。
6. 从测试到实战：你的第一个 LaTeX 项目
理论说了这么多，是时候动手实践了。让我们创建一个简单的测试项目，验证整个环境是否工作正常。
在你的文档文件夹（比如~/Documents/LaTeX）中，新建一个文件夹叫MyFirstPaper。用 VSCode 打开这个文件夹（File -> Open Folder...）。在资源管理器中，新建一个文件，命名为main.tex。
将以下内容复制进去，这是一个支持中文的简单文档：
% !TEX program = xelatex % !TEX root = main.tex \documentclass[12pt, a4paper]{article} \usepackage{fontspec} % 用于设置字体 \usepackage{xeCJK} % 用于中文字体支持 \setCJKmainfont{PingFang SC} % 设置中文字体为苹方，请确保你的系统有此字体 \setmainfont{Times New Roman} % 设置英文字体 \title{我的第一个 VSCode LaTeX 文档} \author{你的名字} \date{\today} \begin{document} \maketitle \section{引言} 你好，世界！这是一个在 Mac 上使用 VSCode 和 LaTeX Workshop 编写的文档。它支持中文，并且编译速度非常快。 \section{数学公式} 行内公式：爱因斯坦的质能方程是 $E = mc^2$。 独立公式： \begin{equation} \int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi} \end{equation} \section{列表} \begin{itemize} \item 这是一个无序列表项。 \item 另一个列表项。 \end{itemize} \begin{enumerate} \item 这是一个有序列表项。 \item 第二个有序项。 \end{enumerate} \section{结论} 环境配置成功！现在你可以开始用这个高效、离线、可定制的环境来撰写你的论文、报告或书籍了。 \end{document}保存文件后，你有几种方式编译它：
- 点击编辑器右上角的“小绿三角”编译按钮。
- 使用快捷键
Cmd + Option + B。 - 点击左侧 TeX 图标，在“命令”视图里选择“使用配方编译”，然后选择
xelatex (一次编译)或latexmk。
编译成功后，点击右上角的“预览 PDF”按钮（或按Cmd + Option + V），你的 PDF 就会在 VSCode 内部打开。尝试修改一下文本，然后保存，你会发现 PDF 会自动更新（如果设置了onSave自动编译）。再试试在.tex文件里按Cmd + Option + J，或者在 PDF 里双击文字，体验一下 SyncTeX 同步定位的魔力。
走到这一步，恭喜你！你已经成功在 Mac 上搭建了一个功能全面、高度定制化的 LaTeX 写作环境。这个环境不仅解决了对在线编辑器的依赖，更在速度、稳定性和个性化上带来了质的飞跃。剩下的，就是尽情享受专注于内容创作的乐趣了。如果在使用过程中遇到任何独特的问题，记住善用搜索引擎和 LaTeX Workshop 插件的官方文档，大部分问题都能找到答案。