Back to Details

latex-setup

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

LaTeX Environment Setup

LaTeX环境搭建

When to Use This Skill

何时使用该技能

Use this skill when:
  • Installing LaTeX on a new machine
  • Setting up MacTeX distribution
  • Configuring Skim PDF viewer with SyncTeX
  • Verifying LaTeX installation
  • Troubleshooting missing packages
在以下场景使用本技能：
  • 在新设备上安装LaTeX
  • 搭建MacTeX发行版环境
  • 配置支持SyncTeX的Skim PDF阅读器
  • 验证LaTeX安装情况
  • 排查缺失包问题

Quick Reference

快速参考

Recommended Stack

推荐技术栈

ComponentPurposeStatus
MacTeX 2025Full LaTeX distribution (TeX Live 2025)✅ Recommended
Skim 1.7.11PDF viewer with SyncTeX support✅ macOS only
TeXShop 5.57Integrated LaTeX IDE (optional)✅ Native macOS
组件用途状态
MacTeX 2025完整LaTeX发行版（基于TeX Live 2025）✅ 推荐使用
Skim 1.7.11支持SyncTeX的PDF阅读器✅ 仅适用于macOS
TeXShop 5.57集成式LaTeX开发环境（可选）✅ 原生macOS应用

Quick Start

快速开始

Install MacTeX

安装MacTeX

bash
brew install --cask mactex
bash
brew install --cask mactex

Size: ~4.5 GB (includes everything)

大小：约4.5 GB（包含全部组件）

undefined
undefined

Verify Installation

验证安装

bash
tex --version
bash
tex --version

Expected: TeX 3.141592653 (TeX Live 2025)

预期结果：TeX 3.141592653 (TeX Live 2025)

pdflatex --version latexmk --version
undefined
pdflatex --version latexmk --version
undefined

Test Compilation

测试编译

bash
echo '\documentclass{article}\begin{document}Hello World!\end{document}' > test.tex
pdflatex test.tex
ls test.pdf  # Verify PDF created
bash
echo '\documentclass{article}\begin{document}Hello World!\end{document}' > test.tex
pdflatex test.tex
ls test.pdf  # 验证PDF文件已生成

Post-Installation Checklist

安装后检查清单

  • Verify 
    tex --version
    shows TeX Live 2025
  • Verify 
    latexmk --version
    shows 4.86a+
  • Verify 
    pdflatex test.tex
    creates PDF
  • Install Skim if using mactex-no-gui
  • Test SyncTeX: compile with 
    -synctex=1
    flag
  • Configure Skim preferences for editor integration
  • Add 
    /Library/TeX/texbin
    to PATH if needed
  • Test package installation: 
    sudo tlmgr install <package>
  • 验证
    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>

Reference Documentation

参考文档

For detailed information, see:
  • Installation - Full MacTeX vs lightweight options, Skim installation
  • Verification - Check installation, verify PATH, test compilation
  • Package Management - Check, install, search for packages with tlmgr
  • Skim Configuration - Enable SyncTeX, configure preferences for editor integration
  • Troubleshooting - PATH issues, tlmgr problems, permissions
See Also:
  • Build Workflows: Use 
    latex/build
    skill for latexmk automation
  • Table Creation: Use 
    latex/tables
    skill for tabularray usage
如需详细信息，请查看：
  • 安装指南 - MacTeX完整版与轻量版对比、Skim安装方法
  • 验证指南 - 检查安装情况、验证PATH、测试编译
  • 包管理 - 使用tlmgr检查、安装、搜索包
  • Skim配置 - 启用SyncTeX、配置编辑器集成偏好设置
  • 问题排查 - PATH问题、tlmgr故障、权限问题
扩展参考:
  • 构建工作流：使用
    latex/build
    技能实现latexmk自动化
  • 表格创建：使用
    latex/tables
    技能使用tabularray

Troubleshooting

问题排查

IssueCauseSolution
tex command not foundPATH not configuredAdd 
/Library/TeX/texbin
to PATH in shell profile
Permission denied (tlmgr)Need sudo for system packagesUse 
sudo tlmgr install <package>
Package not foundMissing from TeX LiveRun 
tlmgr search <package>
to find correct name
Skim not showing PDFSyncTeX not enabledCompile with 
-synctex=1
flag
Outdated TeX LiveOld MacTeX versionRun 
sudo tlmgr update --self --all
Compilation hangsInfinite loop in documentCheck for circular includes or missing \end{}
Missing font errorFont not in TeX distributionInstall with 
tlmgr install <font-package>
Disk space errorFull TeX Live too largeConsider BasicTeX (smaller) if space limited
问题原因解决方法
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（轻量版）