写在前面

LaTeX 是学术写作和科技文档排版的首选工具，但在 Mac 上配置 LaTeX 编译环境对于新手来说可能有些复杂。本文将从零开始，详细介绍如何在 Mac 上配置完整的 LaTeX 环境，并实现与 VS Code 的完美集成。

本文特色：

• 全局配置方案：一次配置，所有 LaTeX 项目自动应用，无需重复设置
• 完整功能支持：包含 XeLaTeX、PDFLaTeX、LaTeXmk、BibTeX、Biber 等所有常用工具
• 智能编译：自动处理多遍编译、参考文献和依赖关系
• 自动清理：编译后自动清理临时文件，保持项目整洁
• 效率提升：自定义快捷键配置，大幅提升写作速度

通过本文的配置，你将能够在任何 LaTeX 项目中享受一致的、高效的编写体验。

目录

本文包含以下内容：

• MacTeX 安装（三种方案）
• 环境变量配置
• VS Code 集成配置（全局配置推荐）
• 完整编译工具和配方配置
• 自定义快捷键配置（提升写作效率）
• 测试验证
• 常见问题解决

方案选择

在 Mac 上安装 LaTeX，主要有三种方案：

推荐方案：MacTeX（完整版），虽然安装包较大，但包含所有常用包和工具，避免后续频繁安装依赖。

方法一：MacTeX 完整安装（推荐）

1. 安装 MacTeX

方法 A：使用 Homebrew（推荐）

如果你已经安装了 Homebrew，这是最简单的方式：

1

brew install --cask mactex

方法 B：手动下载安装

1. 访问 MacTeX 官网
2. 下载 MacTeX.pkg（约 4GB）
3. 双击安装包，按照提示完成安装

注意：安装过程可能需要 10-30 分钟，请耐心等待。

2. 配置环境变量

安装完成后，需要将 TeX Live 工具添加到系统 PATH 中。

自动配置脚本

创建一个配置脚本 setup_latex.sh：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

#!/bin/bash

echo "正在配置 LaTeX 环境..."

# 检测 TeX Live 安装路径
TEXLIVE_YEAR=$(ls -d /usr/local/texlive/*/bin 2>/dev/null | head -1 | sed 's|/usr/local/texlive/\([0-9]*\)/.*|\1|')
TEXLIVE_PATH="/usr/local/texlive/${TEXLIVE_YEAR}/bin/universal-darwin"

if [ -d "$TEXLIVE_PATH" ]; then
    echo "找到 TeX Live 安装路径: $TEXLIVE_PATH"
    
    # 添加到 .zshrc
    if [ -f ~/.zshrc ]; then
        if ! grep -q "texlive.*bin.*universal-darwin" ~/.zshrc; then
            echo "" >> ~/.zshrc
            echo "# LaTeX (MacTeX) 环境变量" >> ~/.zshrc
            echo "export PATH=\"$TEXLIVE_PATH:\$PATH\"" >> ~/.zshrc
            echo "✓ 已添加到 ~/.zshrc"
        fi
    fi
    
    # 立即生效
    export PATH="$TEXLIVE_PATH:$PATH"
    echo "✓ 配置完成！"
else
    echo "✗ 未找到 TeX Live 安装路径"
    exit 1
fi

运行脚本：

1
2
3

chmod +x setup_latex.sh
./setup_latex.sh
source ~/.zshrc

手动配置

如果不想使用脚本，可以手动编辑 ~/.zshrc 文件：

1
2
3
4
5
6
7
8

# 打开配置文件
nano ~/.zshrc

# 添加以下内容（注意：年份可能不同，请根据实际安装版本修改）
export PATH="/usr/local/texlive/2025/bin/universal-darwin:$PATH"

# 保存后执行
source ~/.zshrc

3. 验证安装

检查 LaTeX 工具是否可用：

1
2
3
4
5
6

# 检查命令路径
which pdflatex xelatex tlmgr

# 查看版本信息
pdflatex --version
xelatex --version

如果看到版本信息，说明安装成功！

方法二：BasicTeX 轻量安装

如果你只需要基本功能，或者想节省磁盘空间，可以使用 BasicTeX：

1. 安装 BasicTeX

1

brew install --cask basictex

2. 配置环境变量

1
2

echo 'export PATH="/usr/local/texlive/2025basic/bin/universal-darwin:$PATH"' >> ~/.zshrc
source ~/.zshrc

3. 安装常用包

BasicTeX 只包含基础包，需要手动安装常用包：

1
2
3

sudo tlmgr update --self
sudo tlmgr install collection-latexextra
sudo tlmgr install collection-fontsrecommended

VS Code 集成配置

VS Code 配合 LaTeX Workshop 扩展，可以提供最佳的 LaTeX 编写体验。

1. 安装 LaTeX Workshop 扩展

1. 打开 VS Code
2. 按 Cmd+Shift+X 打开扩展面板
3. 搜索 “LaTeX Workshop”
4. 安装由 James Yu 开发的扩展

2. 配置 LaTeX Workshop

配置方式选择

LaTeX Workshop 的配置可以在两个位置进行：

推荐使用全局配置，这样所有 LaTeX 项目都可以使用相同的编译配方和设置，无需在每个项目中重复配置。

全局配置方法

1. 按 Cmd+Shift+P 打开命令面板
2. 输入 “Preferences: Open User Settings (JSON)”
3. 在打开的 settings.json 文件中添加以下完整配置：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136

{
  "latex-workshop.latex.tools": [
    {
      "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",
        "%DOCFILE%"
      ]
    },
    {
      "name": "latexmk",
      "command": "latexmk",
      "args": [
        "-synctex=1",
        "-interaction=nonstopmode",
        "-file-line-error",
        "-pdf",
        "-outdir=%OUTDIR%",
        "%DOCFILE%"
      ]
    },
    {
      "name": "biber",
      "command": "biber",
      "args": [
        "%DOCFILE%"
      ]
    },
    {
      "name": "bibtex",
      "command": "bibtex",
      "args": [
        "%DOCFILE%"
      ]
    }
  ],
  "latex-workshop.latex.recipes": [
    {
      "name": "XeLaTeX",
      "tools": [
        "xelatex"
      ]
    },
    {
      "name": "PDFLaTeX",
      "tools": [
        "pdflatex"
      ]
    },
    {
      "name": "BibTeX",
      "tools": [
        "bibtex"
      ]
    },
    {
      "name": "LaTeXmk",
      "tools": [
        "latexmk"
      ]
    },
    {
      "name": "xelatex -> biber -> xelatex*2",
      "tools": [
        "xelatex",
        "biber",
        "xelatex",
        "xelatex"
      ]
    },
    {
      "name": "xelatex -> bibtex -> xelatex*2",
      "tools": [
        "xelatex",
        "bibtex",
        "xelatex",
        "xelatex"
      ]
    },
    {
      "name": "pdflatex -> bibtex -> pdflatex*2",
      "tools": [
        "pdflatex",
        "bibtex",
        "pdflatex",
        "pdflatex"
      ]
    }
  ],
  "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",
    "*.snm",
    "*.nav",
    "*.synctex.gz",
    "*.synctex(busy)",
    "*.vrb",
    "*.bcf",
    "*.run.xml"
  ],
  "latex-workshop.latex.autoClean.run": "onBuilt",
  "latex-workshop.latex.recipe.default": "xelatex -> biber -> xelatex*2",
  "latex-workshop.latex.autoBuild.run": "onSave",
  "latex-workshop.view.pdf.internal.synctex.keybinding": "double-click",
  "latex-workshop.view.pdf.viewer": "tab"
}

配置说明

编译工具（Tools）：

• xelatex：支持中文和现代字体的编译工具（推荐用于中文文档）
• pdflatex：标准 PDF 编译工具
• latexmk：智能编译工具，自动处理多遍编译和依赖
• biber：现代参考文献管理工具（与 biblatex 配合使用）
• bibtex：传统参考文献管理工具

编译配方（Recipes）：

• XeLaTeX：单次编译，适合简单文档
• PDFLaTeX：单次编译，标准工具
• BibTeX：仅处理参考文献
• LaTeXmk：智能编译，自动处理所有依赖
• xelatex -> biber -> xelatex*2：完整编译流程（默认配方），适用于使用 biblatex 的文档
• xelatex -> bibtex -> xelatex*2：完整编译流程，适用于使用传统 BibTeX 的文档
• pdflatex -> bibtex -> pdflatex*2：PDFLaTeX 完整编译流程

其他重要设置：

• autoBuild.run: "onSave"：保存时自动编译
• autoClean.run: "onBuilt"：编译后自动清理临时文件
• recipe.default：默认使用的编译配方
• view.pdf.viewer: "tab"：在 VS Code 标签页中预览 PDF
• synctex.keybinding: "double-click"：双击 PDF 定位到源码

项目级配置（可选）

如果某个项目需要特殊配置，可以在项目根目录创建 .vscode/settings.json：

1
2
3

{
  "latex-workshop.latex.recipe.default": "first"
}

项目配置会覆盖全局配置，但通常只需要全局配置即可。

3. VS Code 使用技巧

编译文档

• 自动编译：保存 .tex 文件时自动编译
• 手动编译：按 Cmd+Option+B
• 选择编译工具：点击状态栏的 “Recipe”

查看 PDF

• 自动预览：编译完成后自动在标签页打开
• 手动查看：按 Cmd+Option+V

同步定位（SyncTeX）

• PDF → 源码：双击 PDF 中的位置（已配置为双击触发）
• 源码 → PDF：按 Cmd+Option+J 或 Cmd+Click 点击源码中的位置

提示：同步定位功能需要在编译时启用 -synctex=1 参数，配置中已包含此参数。

4. 自定义快捷键配置（提升写作效率）

为了提高 Markdown 和 LaTeX 文档的写作效率，我们可以配置一些实用的自定义快捷键。这些快捷键可以帮助你快速插入常用的代码片段。

快捷键快速参考

配置方法

打开 VS Code/Cursor 的快捷键配置文件：

1. 按 Cmd+Shift+P 打开命令面板
2. 输入 “Preferences: Open Keyboard Shortcuts (JSON)”
3. 在打开的 keybindings.json 文件中添加以下配置：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59

[
    // 倾斜字体
    {
        "key": "cmd+shift+i",
        "command": "markdown.extension.editing.toggleItalic",
        "when": "editorTextFocus && !editorReadonly && editorLangId == 'markdown'"
    },
    // 加粗字体
    {
        "key": "cmd+b",
        "command": "markdown.extension.editing.toggleBold",
        "when": "editorTextFocus && !editorReadonly && editorLangId == 'markdown'"
    },
    // 插入下划线的快捷键
    {
        "key": "cmd+u",
        "command": "editor.action.insertSnippet",
        "when": "editorTextFocus",
        "args": {
            "snippet": " <u>$0</u>"
        }
    },
    // 插入链接的快捷键
    {
        "key": "cmd+k",
        "command": "editor.action.insertSnippet",
        "when": "editorTextFocus",
        "args": {
            "snippet": "[${1:link text}](${2:link})$0"
        }
    },
    // 居中插入图片的快捷键
    {
        "key": "cmd+p",
        "command": "editor.action.insertSnippet",
        "when": "editorTextFocus",
        "args": {
            "snippet": "<p align=\"center\">\n  <img src=\"${1:}\" alt=\"${2:}\" width=\"${3:55%}\" height=\"${4:height}\">\n</p>$0"
        }
    },
    // 插入表格的快捷键
    {
        "key": "cmd+t",
        "command": "editor.action.insertSnippet",
        "when": "editorTextFocus",
        "args": {
            "snippet": "| ${1:header 1} | ${2:header 2} |\n| :---: | :---: |\n| ${3:row 1 col 1} | ${4:row 1 col 2} |\n| ${5:row 2 col 1} | ${6:row 2 col 2} |\n$0"
        }
    },
    // 插入代码块的快捷键
    {
        "key": "cmd+d",
        "command": "editor.action.insertSnippet",
        "when": "editorTextFocus",
        "args": {
            "snippet": "```${1:language}\n${2:code}\n```\n$0"
        }
    }
]

快捷键说明

快捷键设计说明：

• 使用简单的 Cmd + 单字母 组合，操作更快捷
• 字母选择遵循常用记忆规则：U(Underline)、K(Link)、P(Picture)、T(Table)、D(Code)
• 这些快捷键会覆盖 VS Code 的默认行为，但提供了更高效的写作体验

使用技巧

1. 占位符导航：插入代码片段后，使用 Tab 键在占位符之间跳转，快速填充内容

2. 自定义修改：可以根据自己的需求修改代码片段内容，比如调整表格列数、图片默认尺寸等

3. 快捷键冲突：这些快捷键会覆盖 VS Code 的默认行为：

   • Cmd+U 原本是"转换为小写"，现在用于插入下划线
   • Cmd+K 原本是"清除终端"，现在用于插入链接
   • Cmd+P 原本是"快速打开文件"，现在用于插入图片
   • Cmd+T 原本是"打开新标签页"，现在用于插入表格
   • Cmd+D 原本是"选择下一个匹配项"，现在用于插入代码块

   如果这些默认功能对你很重要，可以改为其他组合键（如 Cmd+Option+字母 或 Cmd+Shift+字母）

实际应用示例

假设你正在编写一篇博客文章，需要快速插入内容：

1. 插入链接：按 Cmd+K → 自动插入 [link text](link) → 按 Tab 跳转到链接文本 → 输入文本 → 再按 Tab → 输入 URL
2. 插入图片：按 Cmd+P → 自动插入居中图片标签 → 按 Tab 依次填充图片路径、alt 文本、宽度、高度
3. 插入表格：按 Cmd+T → 自动插入 2x2 表格框架 → 使用 Tab 键快速填充表头和内容
4. 插入代码块：按 Cmd+D → 自动插入代码块 → 输入语言类型（如 python、bash）→ 按 Tab → 输入代码
5. 插入下划线：按 Cmd+U → 自动插入 <u></u> 标签 → 直接输入需要下划线的文本

效率对比：

• 传统方式：手动输入所有标签和格式，可能需要 10-20 秒
• 使用快捷键：一键插入模板，只需 2-3 秒填充内容，效率提升 5-10 倍

这些快捷键可以显著提升 Markdown 和 LaTeX 文档的编写效率，特别是在需要频繁插入格式化元素时。

测试验证

创建一个测试文件 test.tex：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

\documentclass{article}
\usepackage[UTF8]{ctex}  % 中文支持
\usepackage{graphicx}    % 插入图片
\usepackage{float}        % 图片位置控制

\title{LaTeX 测试文档}
\author{测试}
\date{\today}

\begin{document}

\maketitle

\section{欢迎}
这是一个 LaTeX 测试文档。如果你能看到这个 PDF 文件，说明 LaTeX 环境配置成功！

\section{数学公式测试}
这是一个行内公式：$E = mc^2$

这是一个块级公式：
\[
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
\]

\end{document}

编译测试：

1

xelatex test.tex

如果成功生成 test.pdf，说明配置完成！

🔧 常见问题解决

问题 1：编译失败，提示找不到命令

原因：环境变量未正确配置或 VS Code 未重启。

解决方案：

1. 运行 ./setup_latex.sh 配置环境变量
2. 重启 VS Code（重要！）
3. 检查终端中 which pdflatex 是否返回路径

问题 2：中文显示乱码

原因：使用了不支持中文的编译工具。

解决方案：

• 使用 xelatex 或 lualatex 而不是 pdflatex
• 确保 .tex 文件使用 UTF-8 编码
• 在文档中使用 \usepackage[UTF8]{ctex}

问题 3：插入图片报错

错误信息：

1
2

LaTeX Error: Unknown float option `H'.
Undefined control sequence. \includegraphics

解决方案：

1
2

\usepackage{graphicx}    % 插入图片
\usepackage{float}        % 图片位置控制（H 选项）

图片路径格式：

• ✅ 正确：{图片.png} 或 {./图片.png}
• ❌ 错误：{.\图片.png}

问题 4：PDF 预览不显示

解决方案：

1. 检查编译是否成功（查看输出面板）
2. 尝试手动编译：Cmd+Option+B
3. 检查 PDF 文件是否生成

问题 5：包缺失错误

解决方案：

1
2
3
4
5
6
7
8

# 更新包管理器
sudo tlmgr update --self

# 安装缺失的包
sudo tlmgr install <package-name>

# 安装常用包集合
sudo tlmgr install collection-latexextra

常用 LaTeX 工具

安装完成后，你将拥有以下工具：

• pdflatex - 标准 PDF 编译工具
• xelatex - 支持中文和现代字体的编译工具（推荐用于中文文档）
• lualatex - 现代 LaTeX 引擎
• latexmk - 智能编译工具，自动处理多遍编译和依赖关系
• bibtex - 传统参考文献管理工具
• biber - 现代参考文献管理工具（与 biblatex 配合使用）
• tlmgr - TeX Live 包管理器

总结

通过本文的配置，你现在应该能够：

1. ✅ 在 Mac 上使用完整的 LaTeX 环境
2. ✅ 在 VS Code 中高效编写 LaTeX 文档
3. ✅ 使用全局配置，所有 LaTeX 项目自动应用相同设置
4. ✅ 自动编译和预览 PDF（保存即编译）
5. ✅ 支持中文文档编写（XeLaTeX）
6. ✅ 支持参考文献管理（BibTeX/Biber）
7. ✅ 自动清理临时文件，保持项目整洁
8. ✅ 配置自定义快捷键提升写作效率
9. ✅ 解决常见配置问题

配置优势

全局配置的优势：

• ✅ 一次配置，处处使用：所有 LaTeX 项目自动使用相同的编译配方
• ✅ 统一体验：在不同项目间切换时，编译行为保持一致
• ✅ 易于维护：只需在一个地方更新配置
• ✅ 无需重复：不需要在每个项目中创建 .vscode/settings.json

完整功能支持：

• ✅ 多种编译工具：XeLaTeX、PDFLaTeX、LaTeXmk
• ✅ 参考文献支持：BibTeX 和 Biber 双支持
• ✅ 智能编译：自动处理多遍编译和依赖关系
• ✅ 自动清理：编译后自动清理 20+ 种临时文件

推荐工作流程

1. 打开项目：在 VS Code 中打开任何 LaTeX 项目（无需额外配置）
2. 编写文档：使用自定义快捷键快速插入常用元素：
   • Cmd+K 插入链接
   • Cmd+P 插入图片
   • Cmd+T 插入表格
   • Cmd+D 插入代码块
   • Cmd+U 插入下划线
3. 自动编译：保存 .tex 文件时自动编译（默认使用 xelatex -> biber -> xelatex*2 配方）
4. 查看预览：编译完成后自动在标签页打开 PDF
5. 同步定位：双击 PDF 中的位置跳转到源码，或使用 Cmd+Option+J 从源码跳转到 PDF

效率提升技巧

• ✅ 全局配置：一次配置，所有项目通用，无需重复设置
• ✅ 自动编译：保存即编译，无需手动操作
• ✅ 智能配方：默认配方自动处理参考文献和多遍编译
• ✅ 自动清理：编译后自动清理临时文件，保持项目整洁
• ✅ 双向同步：PDF 和源码之间快速跳转（双击 PDF 或 Cmd+Option+J）
• ✅ 自定义快捷键：配置常用代码片段快捷键，大幅提升写作速度
• ✅ 智能补全：LaTeX Workshop 提供丰富的代码补全

编译配方选择建议

下一步

• 学习 LaTeX 基础语法
• 探索更多 LaTeX 包和模板
• 学习参考文献管理（BibTeX/Biber）
• 根据项目需求切换编译配方
• 根据个人需求定制更多快捷键

📖 参考资源

• MacTeX 官网
• LaTeX Workshop 扩展文档
• LaTeX 中文文档

祝你 LaTeX 写作愉快！ 🎉