latex-setup

LaTeX 环境设置

自我演进技能：此技能会在使用过程中不断改进。如果说明有误、参数发生变化，或需要采用变通方法，请立即修正此文件，不要拖延。仅针对真实且可复现的问题进行更新。

何时使用此技能

在以下情况下使用此技能：

• 在新机器上安装 LaTeX
• 设置 MacTeX 发行版
• 配置支持 SyncTeX 的 Skim PDF 查看器
• 验证 LaTeX 安装
• 排查缺少宏包的问题

快速参考

推荐技术栈

组件	用途	状态
MacTeX 2025	完整的 LaTeX 发行版（TeX Live 2025）	✅ 推荐
Skim 1.7.11	支持 SyncTeX 的 PDF 查看器	✅ 仅限 macOS
TeXShop 5.57	集成式 LaTeX IDE（可选）	✅ macOS 原生

---

快速开始

安装 MacTeX

brew install --cask mactex
# Size: ~4.5 GB (includes everything)

验证安装

tex --version
# Expected: TeX 3.141592653 (TeX Live 2025)

pdflatex --version
latexmk --version

测试编译

echo '\documentclass{article}\begin{document}Hello World!\end{document}' > test.tex
pdflatex test.tex
ls test.pdf  # Verify PDF created

---

安装后检查清单

• 验证 tex --version 显示 TeX Live 2025
• 验证 latexmk --version 显示 4.86a+
• 验证 pdflatex test.tex 能生成 PDF
• 如果使用 mactex-no-gui，请安装 Skim
• 测试 SyncTeX：使用 -synctex=1 标志进行编译
• 配置 Skim 偏好设置，以便与编辑器集成
• 如有需要，将 /Library/TeX/texbin 添加到 PATH
• 测试宏包安装：sudo tlmgr install <package>

---

参考文档

详细信息请参阅：

• 安装 - 完整版 MacTeX 与轻量级选项、Skim 安装
• 验证 - 检查安装、验证 PATH、测试编译
• 宏包管理 - 使用 tlmgr 检查、安装和搜索宏包
• Skim 配置 - 启用 SyncTeX，配置偏好设置以便与编辑器集成
• 故障排除 - PATH 问题、tlmgr 问题、权限问题

另请参阅：

• 构建工作流：使用 latex/build skill 自动运行 latexmk
• 表格创建：使用 latex/tables skill 使用 tabularray

---

故障排除

问题	原因	解决方案
找不到 tex 命令	未配置 PATH	在 shell 配置文件中将 /Library/TeX/texbin 添加到 PATH
权限被拒绝（tlmgr）	系统宏包需要 sudo	使用 sudo tlmgr install <package>
找不到宏包	TeX Live 中缺少该宏包	运行 tlmgr search <package> 查找正确名称
Skim 未显示 PDF	未启用 SyncTeX	使用 -synctex=1 标志进行编译
TeX Live 版本过旧	MacTeX 版本较旧	运行 sudo tlmgr update --self --all
编译卡住	文档中存在无限循环	检查循环引用或缺失的 \end{}
缺少字体错误	TeX 发行版中没有该字体	使用 tlmgr install <font-package> 安装
磁盘空间错误	完整版 TeX Live 占用空间过大	如果空间有限，可考虑使用较小的 BasicTeX

执行后回顾

此技能执行完毕后，请在结束前检查：

1. 命令是否成功？ — 如果失败，请修正导致问题的说明或错误表格。
2. 参数或输出是否发生变化？ — 如果底层工具的接口发生变化，请更新用法示例和参数表，使其保持一致。
3. 是否需要采用变通方法？ — 如果需要临时调整（更换标志、增加步骤），请更新此 SKILL.md，避免下次调用时再次采用相同的变通方法。

仅在问题真实且可复现时进行更新，不要臆测。