xecjk安装时提示“fontspec error: font not found”如何解决？

Question

在使用 `xeCJK` 宏包编译中文 LaTeX 文档时，若 XeLaTeX 报错 `fontspec error: font not found`，根本原因并非 `xeCJK` 未安装，而是**未指定可用的中文字体**或系统中缺失该字体。`xeCJK` 依赖 `fontspec` 加载字体，但默认不绑定任何中文字体。常见解决方式：① 在导言区显式设置主中文字体，如 `\setmainfont{Noto Serif CJK SC}`（需已安装）；② 使用 `\setCJKmainfont{SimSun}`（Windows）或 `\setCJKmainfont{STSong}`（macOS）等系统自带字体；③ 推荐用 `ctex` 宏包替代手动配置，它自动适配本地中文字体并处理编码与字号。验证字体是否可用：终端执行 `fc-list :lang=zh`（Linux/macOS）或检查 Windows 字体目录。切勿仅安装 `xeCJK` 而忽略字体配置——这是90%同类错误的根源。

Answer 1

```html

一、现象层：错误表征与典型报错日志

XeLaTeX 编译中文文档时，控制台高频输出：fontspec error: "font-not-found"，紧随其后是类似 The font "Noto Serif CJK SC" cannot be found. 的定位提示。该错误常被误判为宏包缺失（如误装 xeCJK 却未配置字体），实则 xeCJK 已成功加载——fontspec 在底层调用系统字体渲染引擎（Core Text / FreeType / DirectWrite）失败，本质是「字体资源链路断裂」。

二、机制层：xeCJK 与 fontspec 的协同架构

xeCJK 并非字体容器，而是一套面向 CJK 文字的排版规则调度器：它定义字符类（如汉字、假名、平假名）、自动处理字距、禁则（widow/orphan）、标点挤压等；但所有实际字形渲染均由 fontspec 驱动。关键约束如下：

• xeCJK 默认不预设任何 CJK 字体，\setmainfont{} 仅影响西文，\setCJKmainfont{} 才绑定中文字体主干
• 字体名称必须与系统注册名完全一致（区分空格、大小写、版本后缀），如 macOS 中 "STSong" ≠ "STSong-Light"
• XeLaTeX 不读取 CSS 或 GUI 字体列表，只信任 fontconfig（Linux/macOS）或 GDI+（Windows）注册表

三、诊断层：跨平台字体可用性验证矩阵

平台	验证命令	预期输出特征	常见陷阱
Linux/macOS	fc-list :lang=zh | grep -i "song\|serif\|sans"	含完整路径与 PostScript 名称，如 /usr/share/fonts/truetype/noto/NotoSerifCJKsc-Regular.otf: Noto Serif CJK SC:style=Regular	fc-cache -fv 未刷新缓存导致新安装字体不可见
Windows	PowerShell: [System.Drawing.Text.InstalledFontCollection]::new().Families | Where-Object {$_.Name -match "Sim|Fang|Kai|NSim"}	返回 FontFamily 对象，Name 属性值即为 \setCJKmainfont 参数	从网页下载的 .ttc 文件需右键「安装」而非仅解压到目录

四、解决层：三级字体配置策略（由简至强）

1. 显式绑定系统字体：在导言区添加
   

   \usepackage{xeCJK}
   \setCJKmainfont{SimSun}[BoldFont={SimHei}, ItalicFont={KaiTi}] % Windows

   或
   

   \setCJKmainfont{STSong}[BoldFont={STHeiti}, ItalicFont={STKaiti}] % macOS

2. 引入开源字体生态：通过 texlive-fonts-extra 安装 Noto CJK：
   sudo tlmgr install noto-cjk，再使用
   

   \setCJKmainfont{Noto Serif CJK SC}[
       Extension = .otf,
       UprightFont = *-Regular,
       BoldFont = *-Bold,
       ItalicFont = *-Italic,
       BoldItalicFont = *-BoldItalic
     ]

3. 工程级封装：ctex 宏包自动适配：
   

   \documentclass[UTF8, zihao=5]{ctexbook}
   % ctex 内部执行：
   %   \ctex_font_set_main:nn {simhei} {simkai} （Win）
   %   \ctex_font_set_main:nn {STHeiti} {STKaiti} （macOS）
   %   \ctex_font_set_main:nn {NotoSansCJKsc} {NotoSerifCJKsc} （Linux）

五、进阶层：字体回退链与多语言混合排版

当文档含中/日/韩/越文混合时，需构建层级化字体栈。以下 Mermaid 流程图描述 xeCJK 的字体选择逻辑：

flowchart LR
A[输入 Unicode 字符] --> B{是否在 CJK 范围？}
B -->|是| C[查 xeCJK 字符类映射]
C --> D[匹配 CJKmainfont / CJKsansfont / CJKmonofont]
D --> E{字体是否支持该码位？}
E -->|否| F[尝试 fallbackfont 设置]
E -->|是| G[渲染字形]
B -->|否| H[走 fontspec 原生西文字体链]

六、防错层：CI/CD 环境字体一致性保障

在 GitHub Actions 或 GitLab CI 中，Linux 容器默认无中文字体。须显式注入：

• Debian/Ubuntu：apt-get install fonts-noto-cjk fonts-wqy-zenhei
• Alpine：apk add noto-cjk-fonts wqy-zenhei-fonts
• 自建 Docker 镜像：COPY ./fonts/ /usr/share/fonts/opentype/ && fc-cache -fv

并在 LaTeX 主文件头添加防御性检查：

\ExplSyntaxOn
\sys_if_engine_xetex:T {
  \file_if_exist:nTF {/usr/share/fonts/truetype/noto/NotoSerifCJKsc-Regular.otf}
    {\msg_info:nnn {xeCJK} {font} {Noto~CJK~found}}
    {\msg_error:nnn {xeCJK} {font} {Noto~CJK~missing!}}
}
\ExplSyntaxOff

```