✨ 写在前面

LaTeX 是学术写作和科技文档排版的首选工具，但在 Mac 上配置 LaTeX 编译环境对于新手来说可能有些复杂。本文将从零开始，详细介绍如何在 Mac 上配置完整的 LaTeX 环境，并实现与 VS Code 的完美集成，让你能够高效地编写和编译 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. 创建 VS Code 配置文件

在项目根目录创建 .vscode 文件夹，并添加以下配置文件：

.vscode/extensions.json

1
2
3
4
5

{
  "recommendations": [
    "james-yu.latex-workshop"
  ]
}

.vscode/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

{
  "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",
        "%DOC%"
      ]
    },
    {
      "name": "bibtex",
      "command": "bibtex",
      "args": ["%DOCFILE%"]
    }
  ],
  "latex-workshop.latex.recipes": [
    {
      "name": "XeLaTeX",
      "tools": ["xelatex"]
    },
    {
      "name": "XeLaTeX → XeLaTeX",
      "tools": ["xelatex", "xelatex"]
    },
    {
      "name": "PDFLaTeX",
      "tools": ["pdflatex"]
    },
    {
      "name": "XeLaTeX → BibTeX → XeLaTeX × 2",
      "tools": ["xelatex", "bibtex", "xelatex", "xelatex"]
    }
  ],
  "latex-workshop.latex.autoBuild.run": "onSave",
  "latex-workshop.latex.autoClean.run": "onBuilt",
  "latex-workshop.view.pdf.viewer": "tab",
  "latex-workshop.synctex.afterBuild.enabled": true
}

3. VS Code 使用技巧

编译文档

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

查看 PDF

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

同步定位

• PDF → 源码：双击 PDF 中的位置
• 源码 → PDF：按 Cmd+Option+J

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

[
    // 插入下划线的快捷键
    {
        "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 引擎
• bibtex - 参考文献管理
• tlmgr - TeX Live 包管理器

🎯 总结

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

1. ✅ 在 Mac 上使用完整的 LaTeX 环境
2. ✅ 在 VS Code 中高效编写 LaTeX 文档
3. ✅ 自动编译和预览 PDF
4. ✅ 支持中文文档编写
5. ✅ 配置自定义快捷键提升写作效率
6. ✅ 解决常见配置问题

推荐工作流程

1. 在 VS Code 中打开 .tex 或 .md 文件
2. 使用自定义快捷键快速插入常用元素：
   • Cmd+K 插入链接
   • Cmd+P 插入图片
   • Cmd+T 插入表格
   • Cmd+D 插入代码块
   • Cmd+U 插入下划线
3. 编写内容并保存（LaTeX 文件会自动编译）
4. 在 VS Code 中查看 PDF 预览（LaTeX）或实时预览（Markdown）
5. 使用同步功能快速定位（LaTeX PDF ↔ 源码）

效率提升技巧

• ✅ 自定义快捷键：配置常用代码片段快捷键，大幅提升写作速度
• ✅ 自动编译：保存即编译，无需手动操作
• ✅ 双向同步：PDF 和源码之间快速跳转
• ✅ 智能补全：LaTeX Workshop 提供丰富的代码补全

下一步

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

📖 参考资源

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

祝你 LaTeX 写作愉快！ 🎉