Mac上装好TeXStudio之后，第一次写中文文档，点下编译按钮，输出面板跳出来一屏英文报错，这事儿我太熟了。后来把整个链条理顺才发现，问题根本不在TeXStudio本身，而是三件事没做好：发行版没装对、编译引擎选错了、文档里少了中文字体支持。这篇文章就按照我的实际踩坑顺序来写，从装MacTeX开始，到配置XeLaTeX，再到一个能直接跑通的中文模板，每一步都讲清楚“为什么这么做”。刚入门LaTeX、想在Mac上排版中文文档的朋友，照着走一遍，十分钟内能拿到第一个中文PDF。
1. 先理清一件事：TeXStudio只是个壳子
1.1 编辑器、发行版、编译引擎三者各管什么
很多Mac新手容易把TeXStudio当成一个“大而全”的软件，觉得下载它之后就什么都有了。这是个误会。TeXStudio本质上是文本编辑器+PDF查看器+构建脚本图形封装，它本身不包含任何排版引擎，也不带宏包和字体。真正干活的是TeX发行版，比如MacTeX或BasicTeX。你点“编译”按钮，TeXStudio做的事情其实是：拿着当前.tex文件路径，调用发行版里的编译命令（比如xelatex），再把输出日志拿回界面给你看。
所以这个链条的准确顺序是：你写好.tex源码 → TeXStudio调用发行版里的编译引擎 → 引擎读取源码里指定的宏包和字体 → 生成PDF。任何一个环节断了，中文文档都会出问题。以前我在Windows上用的CTeX套装，是把发行版、编辑器、常用宏包全部打成一个安装包，用户不需要关心这些底层结构。Mac上没有这种全自动全家桶，需要自己把组件拼起来，但只要明白分工，这个组合一点不复杂。
1.2 Mac上跑通中文的最终方案是什么
先给结论：目前macOS上最稳的中文LaTeX组合是MacTeX + TeXStudio + XeLaTeX + ctex宏包。这四个词就是整套方案的关键。
为什么这么组合？MacTeX是macOS上最完整的TeX发行版，安装后自带xelatex、lualatex、tlmgr等工具，以及一整套常用宏包。ctex宏包负责中文排版，它可以自动检测Mac系统里的中文字体并设置好默认的版式，包括首行缩进、字体选择、中文标点处理等等。而编译引擎必须选XeLaTeX，是因为只有XeLaTeX和LuaLaTeX这类现代引擎才可以直接调用系统OpenType字体；传统的pdfLaTeX对中文支持非常绕，需要用CJK宏包配合字体文件，折腾程度高得多。
这个方案确定下来之后，后面每一步都围绕它展开。下一节先解决发行版的安装问题，这是新人最容易卡住的第一关。
2. 装MacTeX还是BasicTeX，别选错了
2.1 为什么新手首选MacTeX
MacTeX有两个安装选项：完整版MacTeX和精简版BasicTeX。MacTeX安装包大约四五个GB，BasicTeX只有一百多MB，很多人一看体积就选了BasicTeX，然后就开始无休止地折腾宏包。我的建议很直接：新手不要在这件事上省空间，直接上MacTeX。
原因很简单。BasicTeX只保留最核心的引擎和少量宏包，ctex、amsmath、graphicx这些中文排版的必需宏包通通没有。你写个最简单的中文文档，编译时就会报“ctex.sty not found”。接下来你得用tlmgr手动装一堆依赖包，装完这个缺那个，每装一个包还会牵出几个依赖项。我见过太多人卡在这一步：终端里连安装命令都还不太熟悉，就要面对一套复杂的包管理系统。
MacTeX则把这些常见宏包和工具都打包好了，安装之后基本开箱即用。虽然下载时间长，但一次搞定，省下的时间和精力远超那几GB磁盘空间。磁盘上多占一点空间，换来的是后面写中文文档时几乎不用跟宏包装缺失较劲，这笔账很划算。
2.2 安装过程与安装后验证
MacTeX的安装方式很“Mac”：去官网下载pkg安装包，双击运行，一路确认授权就行。安装过程中会要求输入管理员密码，之后它会把全部文件装到/usr/local/texlive/2025/目录下，并且自动配置PATH环境变量。整个安装可能需要一两首歌的时间，别急，等它跑完。
装完必须做一件事：打开终端，执行which xelatex，如果输出一个以/usr/local/texlive/开头的路径，说明安装成功且PATH生效。也可以执行xelatex --version看版本信息。如果提示“xelatex: command not found”，大概率是PATH还没刷新，重启终端再试一次。
这里有个macOS特有的小坑：首次运行xelatex时，系统可能会弹出权限确认框，要求允许它访问某个目录，直接点允许。如果编译时报“Operation not permitted”这类错误，去“系统设置 → 隐私与安全性 → 完全磁盘访问权限”里，把终端（或TeXStudio）加进列表，问题就能解决。这个坑在正式安装文档里很少被提到，但实际发生率不低。
补充一句，如果你平时用Homebrew管理软件，也可以执行brew install --cask mactex-no-gui来安装不带GUI的MacTeX版本，效果基本一致。但不要同时用pkg和brew各装一套，两个发行版共存容易让PATH混乱。
3. TeXStudio安装后的三个必要设置
3.1 下载安装与中文界面
TeXStudio的安装相对简单，去官网下载dmg文件，解压后把应用拖入“应用程序”文件夹。macOS的Gatekeeper可能会拦截首次打开，右键点击图标选择“打开”，或者在系统设置的“隐私与安全性”里选择“仍要打开”即可。
装好之后，第一件事不是急着建文档，而是设置中文界面。打开TeXStudio，进入Options → Configure TeXStudio，在左侧的General分类里找到Language，改成“简体中文”，点OK，重启应用。这一步对英文界面还不太熟悉的人尤其重要，菜单变中文后，后面的配置找起来会方便很多。
3.2 编码和编辑器字体必须提前设好
中文乱码问题有一大半是编码没设对。TeXStudio默认编码是UTF-8，理论上不用动，但为了稳妥还是要检查一下：进入“首选项 → 编辑器”，在最上方找到“编码”，确认选择的是“UTF-8”。这里要提醒的是，如果你从Windows电脑上拷贝了别人的.tex文件，那些文件很可能保存成GBK编码。直接打开会显示乱码，编译也会出错。正确的做法是在TeXStudio里用“文件 → 重新载入”时选择正确的编码，或者用iconv把文件转成UTF-8，而不是让编辑器强行去猜。
还有一个容易忽略的点：编辑器字体。如果界面里的中文字符显示成方框或乱码，多半是当前字体不支持中文。在“首选项 → 编辑器”里把字体族改成“PingFang SC”或者“Songti SC”，字号选12左右即可。这一步不影响编译结果，但直接影响你写文档的心情。
4. 编译引擎选型：中文为什么必须选XeLaTeX
4.1 三种常见引擎到底有什么区别
TeX世界里常见的编译引擎有三个：pdfLaTeX、XeLaTeX、LuaLaTeX。对中文用户来说，这个选择基本决定了你会不会踩坑。
pdfLaTeX是历史最悠久的引擎，快且稳定，但它默认只能识别TeX自己的字体体系，无法直接调用系统中的OpenType/TrueType字体。想在pdfLaTeX下用中文，必须借助CJK宏包甚至安装中文字体到TeX目录，这个过程既繁琐又容易出兼容问题。旧文档常用这套方案，但我不推荐新文档再用它。
XeLaTeX基于pdfTeX发展而来，最大的改进是内置了fontspec宏包支持，可以像Word一样直接调用系统字体。配合ctex宏包，它会自动检测macOS里的中文字体家族并设置好排版规则，用户几乎不用操心字体配置。
LuaLaTeX是把Lua脚本引擎嵌进去的现代引擎，功能更强大，也支持系统字体。但对新手来说，LuaLaTeX在ctex宏包下的兼容性问题比XeLaTeX多一些，遇到奇怪报错的概率更高。当工具能解决问题时，不求最复杂，但求最稳，所以我主推XeLaTeX。
4.2 一组对比和最终结论
用表格看三者的差异更直观：
| 对比项 | pdfLaTeX | XeLaTeX | LuaLaTeX |
|---|---|---|---|
| 直接调用系统字体 | 不支持 | 支持 | 支持 |
| ctex宏包支持 | 需额外配置CJK | 开箱即用 | 可用但有兼容风险 |
| 中文文档推荐度 | 不推荐 | 强烈推荐 | 备选 |
| 编译速度 | 快 | 中等 | 中等偏慢 |
对macOS用户来说，XeLaTeX的另一个优势是macOS自带的中文字体质量很好，宋体、黑体、楷体、苹方都足够正式。XeLaTeX + ctex会默认选一套合适的组合，比如“宋体-简”作为正文，“黑体-简”作为标题，排版出来观感相当舒适，不需要你手动指定字体名称。
5. 一个能直接跑通的中文模板
5.1 最小可编译模板
下面的模板是我实际在用的基础版，保存成以.tex结尾的文件，然后直接用F5构建，XeLaTeX编译就能出结果：
\documentclass[UTF8]{ctexart} \usepackage{amsmath} \usepackage{graphicx} \title{我的第一篇中文文档} \author{A 同学} \date{\today} \begin{document} \maketitle \section{为什么用 XeLaTeX} 这里可以写中文正文了。这一页就是我们最终编译成功的成果。 \section{插入数学公式} 勾股定理如公式~\eqref{eq:gougu} 所示： \begin{equation} a^2 + b^2 = c^2 \label{eq:gougu} \end{equation} \section{插入图片} \begin{figure}[htbp] \centering \includegraphics[width=0.6\textwidth]{example.png} \caption{示例图片} \end{figure} \end{document}文件命名建议用英文，比如main.tex，不要用“我的文档.tex”，尽量避免中文路径带来的各类兼容问题。保存路径也建议放在一个全英文目录下，比如~/Documents/texproject/，因为某些辅助工具对中文路径的处理并不稳妥。
5.2 模板逐行拆解
\documentclass[UTF8]{ctexart}是文档类声明，用的是ctex宏包提供的“ctexart”类，等价于article加上完善的中文支持。UTF8选项在XeLaTeX下实际是默认生效的，写上它是为了兼容老文件或防止某些宏包报编码警告。
\usepackage{amsmath}和\usepackage{graphicx}分别提供数学公式和插图能力。ctexart本身不自动加载这两个宏包，写文档时如果要用公式和图，必须手动引入，否则编译会直接报环境未定义错误。
\title、\author、\date是文章元信息，\maketitle则把这些信息渲染成正式标题区。注意date里用\today会自动写入编译日期的中文形式，比如“2025年1月1日”，这是ctex帮你处理的。
\eqref{eq:gougu}是amsmath提供的引用命令，引用公式时会自动带括号。图片环境figure里，htbp的意思是“here, top, bottom, page”，Hint到LaTeX的浮动位置策略，表示尽量放在当前位置、页顶、页底或单独一页。新手如果想固定图片位置，可以用[H]（需要floating宏包），但绝大多数文档用htbp就够了。
5.3 模板跑通后的第一件事
如果你按照上面的模板成功编译出了PDF，恭喜，最难的坎已经过了。接下来可以试着在\section{为什么用 XeLaTeX}下面写一段中文正文，编译看看效果。你会注意到ctex已经自动做了两件事：一是中文段落首行缩进两个字符，二是中英文混排时自动在字符间插入合适的间距，这两点即使不写任何代码也能实现，这就是我推荐ctex而非手动配置xeCJK的理由。
如果想更换默认字体，可以在导言区加一句\setCJKmainfont{Songti SC}、\setCJKsansfont{Heiti SC}、\setCJKmonofont{PingFang SC}，这样正文用宋体、标题用黑体、等宽字体用苹方。这几个字体名称在macOS上是系统内置的英文名，XeLaTeX能直接识别。
6. 把TeXStudio的构建流程固定下来
6.1 默认编译器改成XeLaTeX
模板没问题，但如果你直接新建一个文档，什么都不配置就点编译，TeXStudio默认可能仍走pdfLaTeX路线，编译时还会报错。所以要在TeXStudio里做一处关键设置，把默认编译器改为XeLaTeX。
进入“首选项 → 构建”，找到“默认编译器”，下拉选成“XeLaTeX”。这里改好后，以后每次新建文档，按F5（构建并查看）就会自动调用xelatex编译并打开内置PDF查看器。这一步做完，基本就不用每次都手动指定引擎了。
6.2 命令行参数和快捷键
TeXStudio的构建命令实际上是一条带参数的命令行。默认的xelatex命令是：
xelatex -synctex=1 -interaction=nonstopmode -file-line-error %-synctex=1开启同步反向搜索，就是PDF里按住Command点击文字可以跳回源码对应位置，写长文档时找内容非常关键。-interaction=nonstopmode让编译出错时不暂停等待输入，而是直接把错误全部打印出来，避免编译过程卡死。-file-line-error让错误信息带上文件名和行号，方便在TeXStudio下方窗口定位。最后的%表示当前编辑的tex文件名。
日常编译只需要记两个快捷键：F5是构建并查看PDF，F6是只编译不查看。熟练之后还能用latexmk自动判断是否需要重新编译，它是另一套更智能的构建流程，可以简化到每次只用F5就行，但在新手阶段先用F5/F6熟悉流程更实在。
6.3 内置PDF查看器的一点经验
TeXStudio内置的PDF查看器最大的优势是集成度高：源码修改后F5直接编译并刷新预览，不用切窗口。但macOS上偶尔会出现内置查看器不刷新的情况，尤其是文件路径带空格或特殊字符时。如果遇到这种问题，可以在“首选项 → 构建 → PDF查看器”里切到“外部查看器”，并且指定为系统自带的“预览”应用，这样编译完自动用预览打开PDF。需要双击跳转反向搜索时，再用外部编辑器配合SyncTeX，效果也不差。
7. 高频问题速查
7.1 编译报错对照表
下面这些错误是中文LaTeX环境里最容易遇到的，我按实际出现频率整理成了表格，供你直接对照。
| 报错信息 | 原因 | 解决办法 |
|---|---|---|
xelatex: command not found | 发行版未安装或PATH未生效 | 安装MacTeX，重启终端 |
File \ctex.sty' not found` | 宏包缺失 | 用TeX Live Utility或tlmgr安装ctex |
! Package ctex Error: CTeX fontset \mac' is unavailable` | ctex版本过旧，无法识别macOS字体 | 升级ctex宏包，或指定fontset=mac |
! Fatal fontspec error: cannot find Font: Songti SC | 字体名不对或字体未安装 | 用字体册确认名称后手动指定 |
Missing character: There is no ... in font ... | 字体缺字形或字符编码问题 | 检查源码是否含特殊字符，换字体方案 |
7.2 中文乱码和字体显示问题
乱码分两种。一种是源码层面乱码，多半是文件编码不是UTF-8。解决办法是把TeXStudio编辑器编码设为UTF-8后，重新保存文件；另一种是编译出来的PDF里某些中文字符显示成空白或方框，这通常是字体缺字形导致的，需要检查源码里是否混入了全角空格、生僻字，或者当前字体家族不支持这些字形。
控制台里中文显示成问号，这个问题可以放心忽略。终端字体和TeXStudio输出面板的默认字体可能不包含中文字形，但这只是显示问题，不影响PDF内容。如果你实在看着难受，在“首选项 → 编辑器 → 默认字体”里改成“PingFang SC”即可。
7.3 宏包管理和日常维护经验
MacTeX自带一个图形化的包管理器，叫TeX Live Utility，第一次打开时点右上角更新数据库，之后在“Packages”页面搜索你需要的包，勾选后点击“Install”按钮就能安装。为什么推荐图形界面？因为命令行tlmgr对新手来说比较劝退，尤其是权限问题：普通用户执行tlmgr时经常提示“permission denied”，加上sudo又担心操作失误。图形工具把权限处理和依赖关系都管理好了，适合日常维护。
另一个经验是：不要频繁同时更新所有宏包。某次某公司同学写长文档时，手滑把全部宏包更新到最新版，结果之前写的文档突然编不过去，后来发现是某个宏包新版本与旧版接口不兼容。写作中途的最佳做法是只更新当前文档用到的包，或者等到文档全部完成后再统一更新。
8. 最后再说一点个人体会
从我自己的使用经验看，Mac上跑通中文LaTeX的难度并不在命令行，而在理解“哪个组件负责什么事”。一旦把TeXXStudio当壳、MacTeX当发动机、XeLaTeX当燃料、ctex当翻译官这套逻辑理顺，后面遇到任何中文环境问题，基本都能按部件拆开排查。我也是踩过几轮坑之后才稳定下来：新机器到手，装MacTeX，装TeXStudio，把默认编译器改成XeLaTeX，一份模板存档随时用，从开设新文档到出PDF全程不超过五分钟。这套流程我已经用了很久，传给身边几位同专业的朋友，没有再听说过中文编译搞不定的情况。希望这篇记录能帮你省下我在终端前死磕的那些时间。
