M1 Mac上配置VSCode与LaTeX：从零搭建高效学术写作环境

1. 项目概述：为什么要在M1 Mac上折腾VSCode与LaTeX？

如果你是一名理工科学生、科研工作者，或者需要经常撰写包含复杂数学公式、图表和参考文献的学术文档，那么LaTeX几乎是一个绕不开的工具。它排版精美、引用规范，是Word等所见即所得编辑器难以比拟的。然而，LaTeX本身只是一个排版引擎和宏包集合，你需要一个编辑器来编写.tex源文件，并调用引擎进行编译。

在Mac平台上，传统的选择是功能强大但略显笨重的TeXShop或跨平台的TeXworks。但对于习惯了现代集成开发环境（IDE）的开发者来说，Visual Studio Code以其轻量、插件生态丰富和高度可定制性，成为了一个极具吸引力的选择。特别是对于搭载Apple Silicon（M1/M2/M3）芯片的Mac用户，由于架构从Intel x86转向了ARM，一些传统的安装和配置方法可能会遇到兼容性问题，导致环境配置成为新手的第一道门槛。

这个教程的核心，就是解决在Apple Silicon Mac上，从零开始搭建一个流畅、高效、且能充分发挥VSCode编辑器优势的LaTeX写作环境。我们将避开那些过时或针对Intel Mac的教程，直接聚焦于ARM原生架构下的最佳实践。整个过程不仅涉及LaTeX发行版的安装，更包括VSCode的深度配置、插件的选择与调优，以及如何解决M1芯片可能带来的特有兼容性问题。最终，你将获得一个支持实时预览、语法高亮、代码补全、一键编译和错误跳转的现代化LaTeX编辑工作站。

2. 环境准备：选择与安装LaTeX发行版

在配置编辑器之前，必须先安装LaTeX的核心——发行版。它包含了编译引擎（如pdfLaTeX, XeLaTeX, LuaLaTeX）、宏包、字体以及各类工具。

2.1 LaTeX发行版选型：MacTeX还是BasicTeX？

对于Mac用户，主要有两个选择：MacTeX和BasicTeX（后者现已更名为TeX Live的精简安装选项）。

• MacTeX：这是为macOS量身定做的完整发行版，基于TeX Live。它包含了TeX Live的全部内容，外加一些macOS特有的图形前端工具（如TeXShop, BibDesk, LaTeXiT）。对于大多数用户，尤其是新手和需要完整功能的用户，MacTeX是首选。它的安装包虽然较大（约4.5GB），但“全家桶”式的安装能避免后续因缺少宏包而频繁手动安装的麻烦。
• BasicTeX / TeX Live (small)：这是一个极简版本，只包含最核心的引擎和少量宏包。适合磁盘空间极其紧张的用户。但你需要什么宏包，就得通过tlmgr（TeX Live管理器）手动安装，对于不熟悉命令行的用户来说，这可能会带来额外的学习成本。

结论与建议：在如今硬盘空间不再那么稀缺的背景下，为了获得最无缝的体验，我强烈推荐M1 Mac用户直接安装MacTeX。它能确保你拥有一个开箱即用、功能完备的环境，避免在写作时被“缺少xxx.sty文件”这类错误打断思路。

2.2 安装MacTeX

1. 下载：访问 MacTeX官网 下载最新的安装包（.pkg格式）。请确保下载的是适用于macOS通用（Universal）或Apple Silicon的版本。
2. 安装：双击下载的.pkg文件，按照图形化安装向导的提示一步步进行即可。安装过程需要输入管理员密码，安装路径通常是/usr/local/texlive/2024（年份会变），这个不需要改动。
3. 验证安装：安装完成后，打开终端（Terminal），输入以下命令：

   which pdflatex

   如果安装成功，通常会返回类似/Library/TeX/texbin/pdflatex的路径。你也可以输入pdflatex --version查看版本信息。

注意：MacTeX的安装器会自动将TeX程序的路径（/Library/TeX/texbin）添加到系统的PATH环境变量中。这是VSCode后续能找到编译命令的关键。如果你使用zsh（macOS Catalina及以后版本的默认shell），这个路径通常会被添加到/etc/paths.d/TeX文件中，系统会自动加载。

2.3 安装Visual Studio Code

1. 下载：前往 VSCode官网 ，点击下载Apple Silicon版本（通常会显示“Mac ARM64”）。
2. 安装：将下载的VSCode-darwin-arm64.zip解压，将Visual Studio Code.app拖拽到“应用程序”文件夹即可。
3. 命令行集成（可选但推荐）：为了让后续在终端中能用code .命令快速打开项目，需要在VSCode中安装命令行工具。打开VSCode，按下Cmd+Shift+P打开命令面板，输入shell command，选择“Install ‘code’ command in PATH”。

至此，我们的两大核心基础组件已就位。接下来进入核心的配置环节。

3. VSCode核心配置：插件、设置与编译工作流

VSCode本身并不认识LaTeX，它的强大功能依赖于插件。我们将通过几个核心插件，将VSCode打造成一个专业的LaTeX IDE。

3.1 必装插件：LaTeX Workshop

这是VSCode中LaTeX支持的基石，由一位日本开发者维护，功能极其全面。

1. 安装：在VSCode左侧活动栏点击“扩展”图标（或按Cmd+Shift+X），搜索“LaTeX Workshop”，由James Yu发布，点击安装。
2. 插件功能预览：安装后，你将会获得：
   • 语法高亮：对.tex文件中的命令、环境、注释等进行彩色标注。
   • 代码片段：输入\be然后按Tab，会自动补全\begin{}...\end{}环境。
   • 结构大纲：在文件大纲视图中显示章节、标签等结构。
   • 实时预览：在编辑区右侧同步预览PDF输出。
   • 一键编译：提供丰富的编译食谱（Recipe），一键运行复杂的编译链。
   • 错误与警告：编译错误和警告会直接显示在“问题”面板，点击可跳转到源码对应行。
   • 正向/反向搜索：在PDF预览中点击内容，可跳转到源码对应行；在源码中点击，可高亮PDF对应区域。

3.2 关键配置：定制LaTeX Workshop设置

插件默认配置已经可以工作，但根据个人习惯进行微调，能极大提升效率。我们需要修改VSCode的设置（settings.json）。

1. 打开设置JSON文件：在VSCode中，按Cmd+Shift+P，输入“settings json”，选择“Preferences: Open Settings (JSON)”。
2. 添加LaTeX专用配置：在打开的文件中（大括号{}内），添加以下配置块。我逐段解释其作用：

{ // ... 你原有的其他配置 ... // ========== LaTeX Workshop 配置 ========== "latex-workshop.latex.autoBuild.run": "onSave", // 保存文件时自动编译（可选，根据习惯） "latex-workshop.latex.autoClean.run": "onBuilt", // 编译完成后自动清理辅助文件（如.aux, .log） "latex-workshop.latex.clean.fileTypes": [ // 指定要清理的文件类型 "*.aux", "*.bbl", "*.blg", "*.idx", "*.ind", "*.lof", "*.lot", "*.out", "*.toc", "*.acn", "*.acr", "*.alg", "*.glg", "*.glo", "*.gls", "*.ist", "*.fls", "*.fdb_latexmk" ], // 配置编译工具链（Recipes） "latex-workshop.latex.tools": [ { "name": "latexmk", // 工具名称，可自定义 "command": "latexmk", // 命令，系统PATH中需能找到 "args": [ "-synctex=1", "-interaction=nonstopmode", "-file-line-error", "-pdf", "-outdir=%OUTDIR%", "%DOC%" // 这些是传递给latexmk的参数 ] }, { "name": "xelatex", "command": "xelatex", "args": [ "-synctex=1", "-interaction=nonstopmode", "-file-line-error", "%DOC%" ] }, { "name": "pdflatex", "command": "pdflatex", "args": [ "-synctex=1", "-interaction=nonstopmode", "-file-line-error", "%DOC%" ] }, { "name": "bibtex", "command": "bibtex", "args": [ "%DOCFILE%" ] } ], // 定义编译食谱（Recipe），即工具的执行顺序 "latex-workshop.latex.recipes": [ { "name": "latexmk (pdf)", // 食谱名称，会在VSCode编译按钮下拉菜单中显示 "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.recipe.default": "lastUsed", // 默认使用上次使用的食谱 // PDF查看器设置 "latex-workshop.view.pdf.viewer": "tab", // 在VSCode内置标签页中预览PDF "latex-workshop.view.pdf.zoom": "page-width", // 默认缩放为页面宽度 "latex-workshop.synctex.afterBuild.enabled": true, // 编译后启用正向/反向搜索 // 其他实用设置 "latex-workshop.message.error.show": true, "latex-workshop.message.warning.show": true, "files.eol": "\n", // 统一换行符为LF，避免在跨平台协作时出现问题 "[latex]": { // 针对.tex文件的特定设置 "editor.wordWrap": "on", "editor.formatOnSave": true // 保存时自动格式化（需要LaTeX Workshop插件支持） } }

配置解析与建议：

• latexmk工具：这是一个Perl脚本，能自动处理多轮编译（解决交叉引用、参考文献等需要多次编译的问题）。-outdir=%OUTDIR%参数会将输出文件（如PDF）生成到单独的目录（默认是./.latex.out），保持项目根目录的整洁。这是我最推荐日常使用的工具。
• 食谱选择：latexmk (pdf)食谱最简单智能。如果你的文档需要处理中文（使用xeCJK或ctex宏包），则应选择包含xelatex的食谱。对于纯英文文档，pdflatex食谱可能编译更快。
• PDF查看器：“tab”模式将PDF内嵌在VSCode中，体验最集成。你也可以设置为“external”使用系统默认PDF阅读器（如预览），但会失去一些集成功能。

3.3 辅助插件推荐

除了LaTeX Workshop，以下几个插件能进一步提升体验：

1. Code Spell Checker：代码拼写检查器。虽然LaTeX Workshop有基础拼写检查，但这个插件更强大，支持自定义词典，对撰写英文论文非常有用。
2. GitLens：如果你用Git管理论文版本，这个插件不可或缺。它能直观显示每行的最近提交信息。
3. Word Count：一个简单的字数统计插件，对于有字数要求的文档很方便。
4. Rewrap：快速重排段落宽度，让代码更美观。

4. 从零开始你的第一个LaTeX文档

环境配置好了，让我们通过一个完整的例子来验证并熟悉整个工作流。

4.1 创建项目与文件

1. 在桌面或你喜欢的目录，新建一个文件夹，命名为my-latex-demo。
2. 用VSCode打开这个文件夹（可以直接将文件夹拖入VSCode窗口，或在终端中进入该目录后输入code .）。
3. 在VSCode的资源管理器中，右键点击文件夹，选择“新建文件”，命名为main.tex。

4.2 编写示例文档内容

将以下内容复制到main.tex文件中。这是一个包含中文、数学公式、图片引用和参考文献的简单示例。

% !TEX program = xelatex % 指定编译器，可选，LaTeX Workshop会识别 \documentclass[12pt, a4paper]{article} % 文档类：文章，12磅字，A4纸 % ===== 预加载的宏包 ===== \usepackage{amsmath, amssymb} % 数学公式支持 \usepackage{graphicx} % 插入图片 \usepackage{hyperref} % 创建超链接（目录、引用等） \usepackage{xeCJK} % 中文字体支持 \setCJKmainfont{STSong} % 设置中文字体为华文宋体（macOS自带） % ===== 文档信息 ===== \title{在M1 Mac上配置VSCode与LaTeX的实践报告} \author{你的名字} \date{\today} % ===== 文档主体 ===== \begin{document} \maketitle % 生成标题 \tableofcontents % 生成目录 \newpage \section{引言} 这是一份在搭载Apple Silicon（M1芯片）的Mac电脑上，配置Visual Studio Code作为LaTeX编辑环境的详细记录。得益于\href{https://code.visualstudio.com/}{VSCode}的强大和\href{https://tug.org/mactex/}{MacTeX}的完整性，我们可以建立一个高效、现代的学术写作工作流。 \section{数学公式示例} LaTeX在排版数学公式方面具有无可比拟的优势。以下是一个行内公式示例：爱因斯坦的质能方程 $E = mc^2$。 以及一个行间公式（带编号）示例： \begin{equation} \int_{-\infty}^{\infty} e^{-x^2} \,dx = \sqrt{\pi} \label{eq:gauss} \end{equation} 公式(\ref{eq:gauss})是著名的高斯积分。 \section{图片插入示例} \begin{figure}[htbp] \centering % 需要提前在项目目录下放置一个名为 ‘demo-image.png’ 的图片 \includegraphics[width=0.5\textwidth]{demo-image.png} \caption{这是一个示例图片的标题} \label{fig:sample} \end{figure} 如图\ref{fig:sample}所示，插入图片非常简单。 \section{参考文献引用示例} 这里引用一篇关于深度学习的经典论文\cite{lecun2015deep}。参考文献列表会在文档末尾自动生成。 % ===== 参考文献 ===== \newpage \bibliographystyle{plain} % 参考文献样式 \bibliography{refs} % 从 refs.bib 文件读取参考文献数据 \end{document}

4.3 创建参考文献数据库文件

1. 在同一个项目文件夹下，新建一个文件，命名为refs.bib。
2. 打开refs.bib，添加以下BibTeX条目：

@article{lecun2015deep, title={Deep learning}, author={LeCun, Yann and Bengio, Yoshua and Hinton, Geoffrey}, journal={nature}, volume={521}, number={7553}, pages={436--444}, year={2015}, publisher={Nature Publishing Group} }

4.4 编译与预览

1. 保存所有文件：按Cmd+S保存main.tex和refs.bib。
2. 触发编译：
   • 方式一（手动）：在main.tex文件的编辑区域内，按下Cmd+Option+B。这是LaTeX Workshop的默认编译快捷键。
   • 方式二（点击）：在编辑器右上角会出现一个小的“TeX”图标，点击它旁边的下拉箭头，选择我们之前配置的食谱，例如“xelatex -> bibtex -> xelatex*2”，然后点击播放按钮。
   • 方式三（自动）：如果你之前设置了"latex-workshop.latex.autoBuild.run": "onSave"，那么直接保存main.tex文件就会自动编译。
3. 查看结果：编译过程会在VSCode底部的“终端”面板显示。如果没有错误，编译成功后，右侧会自动打开PDF预览面板，显示排版好的文档。你会看到带有标题、目录、公式、图片占位符（因为demo-image.png不存在，会显示一个框）和参考文献的完整PDF。
4. 正向/反向搜索：
   • 正向搜索（源码 -> PDF）：在main.tex中，将光标放在某一行（比如公式\label{eq:gauss}那一行），按下Cmd+Option+J，PDF预览会自动滚动并高亮对应的公式区域。
   • 反向搜索（PDF -> 源码）：在PDF预览中，按住Cmd键并点击文档中的任何位置（比如标题或公式），VSCode会自动跳转并聚焦到生成该内容的源码行。

至此，一个完整的、可工作的LaTeX环境已经搭建并验证成功。你已经拥有了从编写、编译、预览到调试的完整闭环能力。

5. 高级技巧与疑难问题排查

即使按照上述步骤操作，在实际使用中仍可能遇到一些问题。以下是我在M1 Mac上长期使用总结出的经验与解决方案。

5.1 字体配置：让中文排版更得心应手

使用xeCJK或ctex宏包时，字体的选择至关重要。macOS自带了许多高质量中文字体。

• 查看系统字体：在终端输入fc-list :lang=zh可以列出系统中所有中文字体。
• 常用字体设置：

  \setCJKmainfont{STSong} % 华文宋体，衬线体，适合正文 \setCJKsansfont{STHeiti} % 华文黑体，无衬线体，适合标题 \setCJKmonofont{STFangsong} % 华文仿宋，等宽字体，适合代码

• 使用外部字体：如果你想使用从网络下载的字体（如思源系列），需要将字体文件（.ttf或.otf）复制到项目目录下的一个子文件夹（如./fonts/），然后在导言区使用路径指定：

  \setCJKmainfont{SourceHanSerifSC}[ Path = ./fonts/, Extension = .otf, BoldFont = *-Bold, ItalicFont = *-Italic, BoldItalicFont = *-BoldItalic ]

  注意：路径是相对于.tex源文件的相对路径。这种方式便于项目字体管理，但需要确保协作方也有相同字体文件。

5.2 编译速度优化

LaTeX文档，尤其是包含大量图片和复杂参考文献的文档，编译可能较慢。

• 使用-output-directory或-outdir：如前所述，将输出文件（.aux,.pdf,.log等）输出到独立目录（如./build或./.latex.out）。这有两个好处：1) 保持源码目录整洁；2) 避免文件系统监控工具（如VSCode的搜索索引、Dropbox同步）反复扫描大量临时文件，提升整体响应速度。LaTeX Workshop的%OUTDIR%变量就是为此设计的。
• 增量编译与latexmk：latexmk工具能智能判断哪些文件需要重新编译。在修改了正文但未修改参考文献或交叉引用时，它可能只运行一次pdflatex，而不是完整的四步链，从而加快编译速度。
• 避免实时保存自动编译：对于大型文档，将"latex-workshop.latex.autoBuild.run"设置为“never”，改为手动编译（Cmd+Option+B），可以避免在打字时频繁触发编译导致的卡顿。

5.3 常见错误与解决方案

以下是一个快速排查表，列出了新手最常遇到的几个问题：

5.4 项目结构与组织

对于学位论文、书籍等大型文档，良好的项目结构至关重要。

• 主文档与子文件：使用\input{}或\include{}命令将文档分割成多个.tex文件（如chapters/intro.tex,chapters/method.tex）。

  % main.tex \documentclass{book} \begin{document} \include{chapters/intro} \include{chapters/method} % ... \end{document}

• 资源分类存放：在项目根目录下创建子文件夹，如：
  • ./figures/存放所有图片
  • ./chapters/存放各章节tex文件
  • ./data/存放数据文件
  • ./styles/存放自定义的.sty格式文件
• 使用\graphicspath：在导言区设置图片搜索路径，这样插入图片时就不用写冗长的相对路径了。

  \graphicspath{{figures/}{../shared-figures/}} % 可以设置多个路径 % 使用时直接写 \includegraphics{my-plot.png}

6. 维护与更新

环境搭建好后，还需要简单的维护以确保其长期稳定。

• 更新MacTeX：每年Tex Live都会发布新版本。你可以通过MacTeX自带的“TeX Live Utility”应用程序来更新宏包和引擎。它是一个图形化工具，比命令行tlmgr更友好。
• 更新VSCode及插件：VSCode和LaTeX Workshop插件都会定期更新，带来新功能和Bug修复。保持更新是获得最佳体验的保证。VSCode通常会自动更新插件，你也可以在扩展面板手动检查更新。
• 备份配置：你的核心配置都保存在VSCode的settings.json中。建议将此文件备份到云端（如iCloud, GitHub Gist），以便在更换电脑或重装系统后快速恢复。

整个配置过程的核心，其实是在理解LaTeX编译工作流的基础上，利用VSCode强大的插件系统和配置能力，将其自动化、可视化。一旦这套流程跑通，你会发现用LaTeX写作不再是一件需要与命令行反复搏斗的苦差事，而是一种专注于内容本身的高效创作体验。尤其是在处理数十页、包含数十张图表和上百篇参考文献的学术论文时，这套环境的优势会更加明显。