1. 项目概述为什么要在M1 Mac上折腾VSCode与LaTeX如果你是一名理工科学生、科研工作者或者需要经常撰写包含复杂数学公式、图表和参考文献的学术文档那么LaTeX几乎是一个绕不开的工具。它排版精美、引用规范是Word等所见即所得编辑器难以比拟的。然而LaTeX本身只是一个排版引擎和宏包集合你需要一个编辑器来编写.tex源文件并调用引擎进行编译。在Mac平台上传统的选择是功能强大但略显笨重的TeXShop或跨平台的TeXworks。但对于习惯了现代集成开发环境IDE的开发者来说Visual Studio Code以其轻量、插件生态丰富和高度可定制性成为了一个极具吸引力的选择。特别是对于搭载Apple SiliconM1/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)这是一个极简版本只包含最核心的引擎和少量宏包。适合磁盘空间极其紧张的用户。但你需要什么宏包就得通过tlmgrTeX Live管理器手动安装对于不熟悉命令行的用户来说这可能会带来额外的学习成本。结论与建议在如今硬盘空间不再那么稀缺的背景下为了获得最无缝的体验我强烈推荐M1 Mac用户直接安装MacTeX。它能确保你拥有一个开箱即用、功能完备的环境避免在写作时被“缺少xxx.sty文件”这类错误打断思路。2.2 安装MacTeX下载访问 MacTeX官网 下载最新的安装包.pkg格式。请确保下载的是适用于macOS通用Universal或Apple Silicon的版本。安装双击下载的.pkg文件按照图形化安装向导的提示一步步进行即可。安装过程需要输入管理员密码安装路径通常是/usr/local/texlive/2024年份会变这个不需要改动。验证安装安装完成后打开终端Terminal输入以下命令which pdflatex如果安装成功通常会返回类似/Library/TeX/texbin/pdflatex的路径。你也可以输入pdflatex --version查看版本信息。注意MacTeX的安装器会自动将TeX程序的路径/Library/TeX/texbin添加到系统的PATH环境变量中。这是VSCode后续能找到编译命令的关键。如果你使用zshmacOS Catalina及以后版本的默认shell这个路径通常会被添加到/etc/paths.d/TeX文件中系统会自动加载。2.3 安装Visual Studio Code下载前往 VSCode官网 点击下载Apple Silicon版本通常会显示“Mac ARM64”。安装将下载的VSCode-darwin-arm64.zip解压将Visual Studio Code.app拖拽到“应用程序”文件夹即可。命令行集成可选但推荐为了让后续在终端中能用code .命令快速打开项目需要在VSCode中安装命令行工具。打开VSCode按下CmdShiftP打开命令面板输入shell command选择“Install ‘code’ command in PATH”。至此我们的两大核心基础组件已就位。接下来进入核心的配置环节。3. VSCode核心配置插件、设置与编译工作流VSCode本身并不认识LaTeX它的强大功能依赖于插件。我们将通过几个核心插件将VSCode打造成一个专业的LaTeX IDE。3.1 必装插件LaTeX Workshop这是VSCode中LaTeX支持的基石由一位日本开发者维护功能极其全面。安装在VSCode左侧活动栏点击“扩展”图标或按CmdShiftX搜索“LaTeX Workshop”由James Yu发布点击安装。插件功能预览安装后你将会获得语法高亮对.tex文件中的命令、环境、注释等进行彩色标注。代码片段输入\be然后按Tab会自动补全\begin{}...\end{}环境。结构大纲在文件大纲视图中显示章节、标签等结构。实时预览在编辑区右侧同步预览PDF输出。一键编译提供丰富的编译食谱Recipe一键运行复杂的编译链。错误与警告编译错误和警告会直接显示在“问题”面板点击可跳转到源码对应行。正向/反向搜索在PDF预览中点击内容可跳转到源码对应行在源码中点击可高亮PDF对应区域。3.2 关键配置定制LaTeX Workshop设置插件默认配置已经可以工作但根据个人习惯进行微调能极大提升效率。我们需要修改VSCode的设置settings.json。打开设置JSON文件在VSCode中按CmdShiftP输入“settings json”选择“Preferences: Open Settings (JSON)”。添加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: [ -synctex1, -interactionnonstopmode, -file-line-error, -pdf, -outdir%OUTDIR%, %DOC% // 这些是传递给latexmk的参数 ] }, { name: xelatex, command: xelatex, args: [ -synctex1, -interactionnonstopmode, -file-line-error, %DOC% ] }, { name: pdflatex, command: pdflatex, args: [ -synctex1, -interactionnonstopmode, -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以下几个插件能进一步提升体验Code Spell Checker代码拼写检查器。虽然LaTeX Workshop有基础拼写检查但这个插件更强大支持自定义词典对撰写英文论文非常有用。GitLens如果你用Git管理论文版本这个插件不可或缺。它能直观显示每行的最近提交信息。Word Count一个简单的字数统计插件对于有字数要求的文档很方便。Rewrap快速重排段落宽度让代码更美观。4. 从零开始你的第一个LaTeX文档环境配置好了让我们通过一个完整的例子来验证并熟悉整个工作流。4.1 创建项目与文件在桌面或你喜欢的目录新建一个文件夹命名为my-latex-demo。用VSCode打开这个文件夹可以直接将文件夹拖入VSCode窗口或在终端中进入该目录后输入code .。在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 SiliconM1芯片的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[width0.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 创建参考文献数据库文件在同一个项目文件夹下新建一个文件命名为refs.bib。打开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 编译与预览保存所有文件按CmdS保存main.tex和refs.bib。触发编译方式一手动在main.tex文件的编辑区域内按下CmdOptionB。这是LaTeX Workshop的默认编译快捷键。方式二点击在编辑器右上角会出现一个小的“TeX”图标点击它旁边的下拉箭头选择我们之前配置的食谱例如“xelatex - bibtex - xelatex*2”然后点击播放按钮。方式三自动如果你之前设置了latex-workshop.latex.autoBuild.run: onSave那么直接保存main.tex文件就会自动编译。查看结果编译过程会在VSCode底部的“终端”面板显示。如果没有错误编译成功后右侧会自动打开PDF预览面板显示排版好的文档。你会看到带有标题、目录、公式、图片占位符因为demo-image.png不存在会显示一个框和参考文献的完整PDF。正向/反向搜索正向搜索源码 - PDF在main.tex中将光标放在某一行比如公式\label{eq:gauss}那一行按下CmdOptionJPDF预览会自动滚动并高亮对应的公式区域。反向搜索PDF - 源码在PDF预览中按住Cmd键并点击文档中的任何位置比如标题或公式VSCode会自动跳转并聚焦到生成该内容的源码行。至此一个完整的、可工作的LaTeX环境已经搭建并验证成功。你已经拥有了从编写、编译、预览到调试的完整闭环能力。5. 高级技巧与疑难问题排查即使按照上述步骤操作在实际使用中仍可能遇到一些问题。以下是我在M1 Mac上长期使用总结出的经验与解决方案。5.1 字体配置让中文排版更得心应手使用xeCJK或ctex宏包时字体的选择至关重要。macOS自带了许多高质量中文字体。查看系统字体在终端输入fc-list :langzh可以列出系统中所有中文字体。常用字体设置\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%变量就是为此设计的。增量编译与latexmklatexmk工具能智能判断哪些文件需要重新编译。在修改了正文但未修改参考文献或交叉引用时它可能只运行一次pdflatex而不是完整的四步链从而加快编译速度。避免实时保存自动编译对于大型文档将latex-workshop.latex.autoBuild.run设置为“never”改为手动编译CmdOptionB可以避免在打字时频繁触发编译导致的卡顿。5.3 常见错误与解决方案以下是一个快速排查表列出了新手最常遇到的几个问题错误现象或提示可能原因解决方案! LaTeX Error: File ‘xxx.sty’ not found.缺少必要的LaTeX宏包。1. 检查宏包名是否拼写错误。2. 使用TeX Live管理器安装在终端运行sudo tlmgr install xxx。编译中文文档时乱码或报错未使用支持Unicode的编译器如XeLaTeX/LuaLaTeX或未正确配置中文字体。1. 确保在文档开头使用了% !TEX program xelatex指令或在VSCode编译食谱中选择了包含xelatex的食谱。2. 确保已加载xeCJK或ctex宏包并正确设置了中文字体见5.1节。参考文献引用显示为[?]文献数据库.bib文件未被正确处理或需要运行BibTeX。1. 确保编译食谱中包含了bibtex步骤如我们配置的xelatex - bibtex - xelatex*2。2. 运行完整的编译链而不仅仅是pdflatex一次。PDF预览无法打开或空白PDF阅读器路径问题或编译实际未成功生成PDF。1. 检查VSCode的“终端”面板看编译是否有错误。2. 尝试将latex-workshop.view.pdf.viewer临时改为“external”用系统预览打开生成的PDF文件通常在./.latex.out目录下以判断是编译问题还是预览器问题。正向/反向搜索SyncTeX失效编译时未生成.synctex.gz文件或PDF查看器不支持。1. 确保编译工具的参数中包含-synctex1我们的配置已包含。2. 确保使用的是内置的“tab”查看器或配置正确的外部查看器。Command ‘latexmk’ not found系统PATH环境变量未包含TeX Live的二进制目录。1. 检查终端中which latexmk是否有输出。2. 确保MacTeX已正确安装。可以尝试重启终端或VSCode。3. 在VSCode的settings.json中可以显式指定工具路径不推荐优先修复系统PATH“latex-workshop.latex.tools[0].command”: “/Library/TeX/texbin/latexmk”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写作不再是一件需要与命令行反复搏斗的苦差事而是一种专注于内容本身的高效创作体验。尤其是在处理数十页、包含数十张图表和上百篇参考文献的学术论文时这套环境的优势会更加明显。