前阵子帮朋友的毕业论文把关对方在 Ubuntu 23.10 上装了 TeXlive结果编译带中文的文档时直接翻车满屏报错。本来以为装完 TeXlive 就万事大吉实际一跑才发现Ubuntu 上要正常编排中文文档还差着一整套中文支持链路——CTEX 宏包、中文字体、正确的编译引擎一个都不能少。折腾了一下午把整条链路捋顺后我决定把这套完整流程记下来。这篇不只是命令罗列会把每一步“为什么这么做”“踩过的坑在哪”都讲清楚给准备在 Ubuntu 下写中文 LaTeX 的同学做个参考哪怕你之前没怎么碰过终端也能照着走通。1. 安装前先理清思路TeXlive、CTEX 与中文排版的关系1.1 Ubuntu 下写中文 LaTeX为什么绕不开 CTEX很多人以为 LaTeX 装完就能直接写中文这是个误解。LaTeX 这套系统本身是围绕英文排版设计的默认字体、默认编码、默认断行规则都建立在西文基础上。你新建一个article.tex里面直接放中文再用pdflatex去编编译器大概率会报出“Unicode character 你 not set up for use with LaTeX”之类的错误。即便你运气好用 XeLaTeX 能编过出来的 PDF 也不会符合中文排版习惯——没有首行缩进、标点挤压不对、中英文混排间距奇怪。CTEX 宏包解决的问题就是这一层。它把中文排版所需的中文字体配置、标点压缩、段落缩进、章节标题的中文化格式全部封装好你不需要自己去折腾底层。新版 CTEX 在 XeLaTeX 或 LuaLaTeX 引擎下工作良好直接用ctexart这类文档类就能获得比较标准的中文排版效果。所以这套组合的完整逻辑是TeXlive 负责提供 LaTeX 系统和宏包管理工具CTEX 负责中文排版的顶层封装XeLaTeX 负责真正驱动编译字体则负责让系统里存在可用的中文字形。缺了任何一环中文文档都会出问题。1.2 不同 TeX 发行版的差异Ubuntu 仓库版与官方版的区别在 Ubuntu 上装 TeXlive其实有两条主路一条是sudo apt install texlive-full另一条是从官方下载install-tl脚本安装。两者的区别不只是安装方式而是整个“生命周期管理”方式完全不同。apt 安装的 TeXlive 是 Ubuntu 发行版维护者打包的版本它跟着 Ubuntu 的版本走。好处是安装简单、依赖自动解决坏处是版本冻结在打包那一刻宏包更新滞后而且更关键的是apt 版本基本没法用tlmgr方便地更新和安装新宏包。CTEX 这类更新频繁的宏包在 apt 老版本上跑新文档时容易出现兼容问题。官方install-tl安装的则是“滚动发布”的 TeXlive安装后可以用tlmgr随时更新所有宏包到最新版也能按需安装任何缺失的宏包。CTEX 新版功能往往依赖新版本 TeXlive所以想要长期稳定地写中文文档我更推荐官方版。两者还能共存吗能但不建议。PATH 里两个版本同时存在会导致which tex指向不明确编译时宏包版本混乱。1.3 安装前的系统检查与磁盘空间评估动手之前先在终端里确认三件事系统版本、CPU 架构、磁盘剩余空间。lsb_release -a uname -m df -h /Ubuntu 23.10 的 apt 源和官方安装脚本都支持 amd64 架构。磁盘方面TeXlive full 方案占空间比较大包含大量宏包、文档和源码总计通常需要 7GB 左右。如果你的根分区比较紧张建议先清理一下再装或者安装时用 medium 方案后面按需用tlmgr补包。另外强烈建议先把系统软件包更新到最新避免安装过程中出现依赖库版本过旧的问题sudo apt update sudo apt upgrade -y这一步别跳过。我就遇到过在旧依赖环境下编译字体工具报错的案例虽然不常见但更新一次能省掉很多不必要的排查时间。2. 安装 TeXliveapt 快速装与官方脚本装选哪种2.1 apt 方案适合快速体验但不适合长期写中文文档如果你只想先体验一下 LaTeX或者磁盘空间确实有限可以用 apt 直接装sudo apt install texlive-fullapt 版 TeXlive-full 会把几乎所有常用宏包装进去一式到位。装完之后tex --version和xelatex --version都能正常运行不需要配置 PATH。这个方案的痛点在于宏包版本Ubuntu 23.10 仓库里的 TeXlive 版本虽然是 2023 系列但宏包更新停留在打包时点很多新版 ctex 宏包的 bug 修复和功能增强是拿不到的。更麻烦的是 tlmgr 受限。apt 安装的 TeXlive 虽然也带 tlmgr但使用的时候往往会出现“Cannot setup TLPDB”之类的提示因为 Debian/Ubuntu 打包时调整了目录结构。也就是说以后你要补装宏包、更新字体包靠 tlmgr 基本走不通只能等系统仓库更新。对只是临时编译一份英文简历的人来说无所谓但如果你要长期写论文、写书这套限制会很难受。2.2 官方 install-tl 脚本长期使用更推荐的方式官方安装脚本可以从 CTAN 镜像下载也可以直接用国内镜像加速。我给出的命令里下载和解压是第一步cd ~/Downloads wget https://mirror.ctan.org/systems/texlive/tlnet/install-tl-unx.tar.gz tar -xzf install-tl-unx.tar.gz cd install-tl-*解压后不用急着执行交互式安装直接一行命令装 full 方案sudo ./install-tl --no-interaction --scheme full如果你在国内网络环境可以把仓库地址换成清华镜像速度会快很多sudo ./install-tl --repository https://mirrors.tuna.tsinghua.edu.cn/CTAN/systems/texlive/tlnet --no-interaction --scheme full这里说明几个关键参数的含义--no-interaction表示非交互模式安装过程不需要你手动敲回车选择。--scheme full表示安装全部宏包、字体、文档。体积最大但最省心。--repository指定下载源。默认安装目录是/usr/local/texlive/2023可执行文件在/usr/local/texlive/2023/bin/x86_64-linux。安装时间取决于网络快的话 20 分钟慢的话一个小时也正常。如果中途断网重复执行同一命令可以续传继续。我个人的建议是直接 full 方案。缺什么宏包再临时去装虽然可行但每次卡在“缺 xxx.sty”上面很影响心情论文写到一半停下来补包实在不值得。2.3 配置 PATH 并验证安装结果官方安装完成之后命令还不在 PATH 里直接在终端输入xelatex会提示找不到。需要手动加进 shell 配置文件echo export PATH/usr/local/texlive/2023/bin/x86_64-linux:$PATH ~/.bashrc source ~/.bashrc如果你用的是 zsh把~/.bashrc换成~/.zshrc即可。配置完先去验证一下which tex which xelatex xelatex --version只要which xelatex输出了/usr/local/texlive/2023/bin/x86_64-linux/xelatex就说明 PATH 生效了。如果输出还是/usr/bin/xelatex说明系统里已经装了 apt 版本两个版本存在冲突需要清理掉 apt 版或者调换 PATH 顺序。注意PATH 配置完成后当前终端已经 source 过了但新打开的终端窗口会自动读取配置不需要重复 source。很多教程只写追加命令不提 source新手会以为没生效。3. 安装 CTEX 中文支持字体、宏包和第一个中文 PDF3.1 CTEX 到底是什么新版和老版有什么区别CTEX 在中文 LaTeX 用户群体里是个经典名词。老一代的 CTEX 方案基于 CJK 宏包需要手动指定中文字体、设置编码用起来很繁琐。现在大家说的 CTEX更多指的是 ctex 宏包它在 XeLaTeX/LuaLaTeX 引擎下自动处理字体选择和编码问题提供一个开箱即用的中文排版层。ctex 宏包的使用方式很直接。你在文档类里写\documentclass[UTF8]{ctexart}就能获得一个符合中文排版习惯的 article 文档类。ctexart、ctexrep、ctexbook、ctexbeamer 分别对应文章、报告、书籍、幻灯片。如果需要在英文文档里局部插入中文也可以不改变文档类而是用\usepackage{ctex}的方式加载。关于 xeCJK、CJKutf8 和 ctex 三者的关系xeCJK 是 XeLaTeX 下层的中文支持宏包负责字符和字体映射CJKutf8 是 pdflatex 时代的旧解决方案ctex 宏包内部会自动调用 xeCJK再叠加版式优化。日常写文档直接用 ctex 就行不用自己再去配置 xeCJK。方案编译引擎字体处理推荐度CJKutf8pdflatex需手动指定老文档维护xeCJKxelatex系统字体中英混排定制ctex 宏包xelatex/lualatex自动配置日常首选3.2 第一步安装中文字体让系统认识中文CTEX 宏包编译时要调用具体的中文字体文件如果系统里一个中文字体都没有即使宏包装好了也会报错。错误信息通常长这样! Package ctex Error: Chinese font FandolSong-Regular not found.所以安装中文支持的第二步是先把系统级中文字体装好。Ubuntu 上最省事的做法是装开源的 Noto CJK 字体和文泉驿字体sudo apt install fonts-noto-cjk fonts-arphic-uming fonts-arphic-ukai装完用这个命令验证系统认识哪些中文字体fc-list :langzh只要输出了字体文件路径就说明中文字体已经可以被系统字体服务识别。另外ctex 宏包自带一组开源 Fandol 字体日常测试时用fontsetfandol最省心因为不依赖系统装了什么字体。如果 full 方案安装时没把 fandol 字体包带进来可以通过 tlmgr 手动装sudo tlmgr install fandol这里多说一句字体版权。网上有人建议把 Windows 的 SimSun 等字体文件拷到 Linux 下使用技术上可行但版权上不推荐尤其不要放到公开分享的项目里。开源场景下用 Fandol 或 Noto CJK 已经很体面了没必要冒这个风险。3.3 第二步用 tlmgr 安装并更新 ctex 宏包如果你用的是官方版 TeXlive full 方案ctex 宏包大概率已经安装好了。可以用下面的命令确认kpsewhich ctex.sty有输出路径就说明宏包在。如果没有用 tlmgr 安装sudo tlmgr update --self sudo tlmgr install ctex xeCJK fandol latexmk执行tlmgr update --self是为了把 tlmgr 工具本身升到最新避免后面装包时因为版本过低报错。安装完成后再检查一次kpsewhich ctex.sty这步其实很关键。很多同学在网上照着教程装了 CTEX结果编译时仍然提示找不到ctex.sty原因就是宏包检查这步没做以为装完就行。注意官方版 TeXlive 安装目录属于 root直接运行 tlmgr 会报权限错误。解决方法是所有 tlmgr 命令前加sudo。如果你嫌每次 sudo 麻烦可以把整个 TeXlive 目录的属主改成当前用户sudo chown -R $USER /usr/local/texlive/2023之后就无需 sudo 了。这是我的个人习惯方便但代价是系统升级时偶尔会提示属主问题自己权衡。3.4 第三步写一个完整的中文文档并用 xelatex 编译前面的宏包和字体都就位后终于可以进入实战环节。先建一个目录和测试文件mkdir -p ~/latex-test cd ~/latex-test然后创建一个test.tex内容用最精简的方式验证中文支持\documentclass[UTF8,fontsetfandol]{ctexart} \title{中文排版测试文档} \author{你的名字} \begin{document} \maketitle \section{引言} 你好世界。这是一份在 Ubuntu 23.10 上使用 TeXlive 和 CTEX 宏包编译的中文文档。 \end{document}关键点在\documentclass[UTF8,fontsetfandol]{ctexart}UTF8告诉编译器源文件编码fontsetfandol指定字体方案ctexart是 CTEX 提供的中文文章类。随后编译xelatex test.tex正常的话终端会一路输出编译日志最后生成test.pdf。用evince test.pdf或任意 PDF 阅读器打开中文应当正常显示。需要说明的是xelatex是这里唯一的推荐引擎。如果你配置的编辑器默认用pdflatex同样的test.tex会直接报错因为 pdflatex 的编码体系根本不认识中文字符。很多人的中文文档编译失败问题往往不是 CTEX 没装好而是编辑器没有切换到 XeLaTeX。4. 编辑器与日常编译配置把自己顺手的环境搭起来4.1 TeXstudio开箱即用但需要改一处关键配置写中文 LaTeX 不一定非得用复杂的编辑器TeXstudio 是个很不错的图形化选择Ubuntu 上一条命令装好sudo apt install texstudio安装后先做一件事否则中文文档还是编不过把默认编译器从 pdflatex 改成 XeLaTeX。打开 TeXstudio菜单栏进入“选项 → 设置 TeXstudio → 构建”把“默认编译器”改成“XeLaTeX”。在“命令”标签页里XeLaTeX 的默认命令我建议改成xelatex -synctex1 -interactionnonstopmode -file-line-error %.tex解释一下这三个参数-synctex1是生成同步信息编辑器和 PDF 之间能互相定位-interactionnonstopmode是遇到错误不挂起等待用户输入直接把错误写进日志这样批量编译时不会卡死-file-line-error让报错信息带上文件名和行号定位错误一目了然。这三个参数我在任何编辑器里都会设置属于写 LaTeX 的标配。4.2 VS Code LaTeX Workshop适合写大工程的组合VS Code 配合 LaTeX Workshop 扩展是另一套高性价比方案特别适合写论文这种调用多文件的工程。扩展安装好之后需要手动配置编译工具链。在 VS Code 的设置 JSON 里加入{ latex-workshop.latex.recipes: [ { name: xelatex, tools: [xelatex] } ], latex-workshop.latex.tools: [ { name: xelatex, command: xelatex, args: [-synctex1, -interactionnonstopmode, -file-line-error, %DOC%] } ] }%DOC%是扩展内置的宏代表当前打开的.tex文件主名。配置完成后保存文件就可以触发编译预览、反向搜索也都有。我个人在长时间写书稿和论文时更偏向 VS Code因为跨文件搜索、Git 集成都方便TeXstudio 更多用来快速编译单个文件。4.3 latexmk / xelatex / lualatex编译引擎怎么选写中文 LaTeX 的引擎选择有一个清晰的优先级直接选择 XeLaTeX 最省事。pdflatex 是老引擎中文基本不用lualatex 也支持中文且能调用 Lua 脚本但字体配置更繁琐日常文档没必要。对于有目录、交叉引用、参考文献的复杂文档我推荐用 latexmk 来托管编译它会自动判断需要编译几遍避免你手动一遍一遍敲 xelatex。latexmk -xelatex test.tex工具推荐场景中文支持pdflatex纯英文文档差需要 CJK 方案xelatex中文日常排版好直接调用系统字体lualatex需要 Lua 脚本的复杂排版好配置略复杂latexmk长文档自动多轮编译依赖底层引擎这里有个小技巧如果你经常在文档里引用外部图片、参考文献建议写一个.latexmkrc配置文件放在项目根目录$pdf_mode 5; $pdflatex xelatex -synctex1 -interactionnonstopmode -file-line-error %O %S;这样在项目目录直接执行latexmk就能自动用 XeLaTeX 编译目录、引用都会自动处理干净换机器也不怕忘配置。5. 踩坑实录CTEX 中文支持常见的 5 个问题与排查思路5.1 问题速查表写完了完整流程再整理一份速查表。这些是我在安装和使用过程中遇到过的典型问题按“现象 → 原因 → 解决”三列列出方便你直接对照排查。现象原因解决xelatex: command not foundPATH 没配置好检查~/.bashrcsource 后重开终端File ctex.sty not foundctex 宏包未安装sudo tlmgr install ctexChinese font FandolSong-Regular not foundfandol 字体缺失sudo tlmgr install fandol或切换 fontset中文显示为方框/空白系统缺少中文字体sudo apt install fonts-noto-cjk fonts-arphic-umingtlmgr: Cannot setup TLPDB使用了 apt 版 TeXlive 的 tlmgr安装官方版 TeXlivePATH 指向官方 tlmgr编译时宏包版本报错apt 版与官方版混用清理 apt 版只保留官方版5.2 逐条排查几条核心问题的解决思路第一条xelatex: command not found。这个最常见。安装官方版后很多人忘了把/usr/local/texlive/2023/bin/x86_64-linux加进 PATH。解决方法是重新执行source ~/.bashrc which xelatex如果which还是找不到检查~/.bashrc里是否真的写入成功。另外两种 shell 的坑要区分bash 用户改~/.bashrczsh 用户改~/.zshrc别改错文件。第二条File ctex.sty not found。这通常是 medium 方案安装或者手动清理过宏包导致的。安装 ctex 全家桶sudo tlmgr install ctex安装后一定要用kpsewhich ctex.sty验证看到路径输出才算真正成功。如果这条命令没有输出说明 TeXlive 的目录结构有问题需要检查环境变量。第三条Chinese font FandolSong-Regular not found.。汉字字形缺失多数是因为 fandol 字体包没装。运行sudo tlmgr install fandol fc-cache -f之后再编译。如果你不想依赖 fandol也可以把文档类改成[UTF8,fontsetubuntu]让它调用 Ubuntu 系统里已安装的 Noto CJK 字体。改 fontset 是解决字体问题最快的方法之一。第四条编译成功了但 PDF 里中文全是方框。这个和宏包没关系是系统级字体渲染问题。确认安装 fonts-noto-cjk然后清理字体缓存sudo apt install fonts-noto-cjk fonts-arphic-uming fc-cache -f如果已经安装仍无效可以检查一下 PDF 阅读器本身是否支持中文显示。有些极简阅读器依赖系统字体库字体缓存没更新就会出现方框。第五条tlmgr 报错。这里多说两句。如果你是从 apt 渠道装的 TeXlivetlmgr 基本处于不可用状态。想要宏包管理功能唯一稳妥的方案是安装官方版 TeXlive并且确保 PATH 里把/usr/local/texlive/2023/bin/x86_64-linux放在/usr/bin前面。确认方法which tlmgr输出应该指向/usr/local/texlive/2023/bin/x86_64-linux/tlmgr而不是/usr/bin/tlmgr。指向后者基本就是 apt 版本在捣乱。提示如果系统里本来有 apt 版 TeXlive 且你不想清理至少别在同一终端同时用两套宏包管理器。我的建议是直接sudo apt remove --purge texlive-*卸干净一了百了。5.3 其他容易忽略的小坑路径含有中文或空格也可能引发问题。TeXlive 在 Linux 下对包含中文的路径处理虽然比以前好但个别宏包在读取外部文件时仍会出问题。如果你的用户名或主目录路径包含中文建议把项目放到/home/用户名/texwork之外更“干净”的路径或者干脆创建一个英文名用户专门写 LaTeX。另一个容易忽略的是更新频率。CTEX 宏包迭代很快如果你编译一个从朋友那儿拿来的新文档报错可以先试试把宏包更新到最新sudo tlmgr update --all更新完再编译很多“莫名奇妙”的错误就消失了。这个操作在写大型项目前做一次比较明智。最后再说一点我习惯做的事把 TeXlive 的安装流程和编辑器配置一起记到自己的配置仓库里。换新机器时不需要重新去搜索教程照着仓库里的步骤十分钟就能把环境恢复出来。写 LaTeX 最重要的是稳定的编译环境把这些基础配置一次做对、长期复用比临时遇坑再查资料省心得多。