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 为什么新手首选MacTeXMacTeX有两个安装选项完整版MacTeX和精简版BasicTeX。MacTeX安装包大约四五个GBBasicTeX只有一百多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. 编译引擎选型中文为什么必须选XeLaTeX4.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 一组对比和最终结论用表格看三者的差异更直观对比项pdfLaTeXXeLaTeXLuaLaTeX直接调用系统字体不支持支持支持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[width0.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 -synctex1 -interactionnonstopmode -file-line-error %-synctex1开启同步反向搜索就是PDF里按住Command点击文字可以跳回源码对应位置写长文档时找内容非常关键。-interactionnonstopmode让编译出错时不暂停等待输入而是直接把错误全部打印出来避免编译过程卡死。-file-line-error让错误信息带上文件名和行号方便在TeXStudio下方窗口定位。最后的%表示当前编辑的tex文件名。日常编译只需要记两个快捷键F5是构建并查看PDFF6是只编译不查看。熟练之后还能用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 unavailablectex版本过旧无法识别macOS字体升级ctex宏包或指定fontsetmac! 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全程不超过五分钟。这套流程我已经用了很久传给身边几位同专业的朋友没有再听说过中文编译搞不定的情况。希望这篇记录能帮你省下我在终端前死磕的那些时间。