如何让Sphinx latexpdf(xelatex)生成的内容、标题和代码支持emoji

问题根源 #

你遇到的问题是Sphinx默认LaTeX模板中，标题（section）使用FreeSansBold、代码块（sphinxVerbatim）使用FreeMono，这两款字体不包含Emoji字符；而正文能显示是因为你替换了主字体，但直接替换主字体又会和模板默认的FreeSerif冲突，导致重复设置。

解决方案 #

1. 给所有字体添加Emoji fallback（解决标题/代码块Emoji+主字体冲突） #

不用直接覆盖主字体，而是给模板用到的所有字体指定Symbola作为fallback，既保留原字体样式，又能渲染Emoji。

修改conf.py中的latex_elements配置：

latex_elements = {
    'preamble': r'''
\usepackage{fontspec}
% 主字体FreeSerif添加Symbola fallback
\setmainfont{FreeSerif}[
    RawFeature={fallback=Symbola}
]
% 标题字体FreeSans（含粗体）添加fallback
\setsansfont{FreeSans}[
    BoldFont=FreeSansBold,
    RawFeature={fallback=Symbola}
]
% 代码字体FreeMono添加fallback
\setmonofont{FreeMono}[
    RawFeature={fallback=Symbola}
]
''',
}

这样就不会出现\setmainfont重复设置的问题——之前的重复是因为Sphinx默认模板先设FreeSerif，你加的\setmainfont{Symbola}又覆盖了它，用fallback就完美规避了冲突。

注意：确保系统已安装Symbola字体，XeLaTeX才能调用它。

2. 实现彩色Emoji显示 #

用支持彩色的Emoji字体（如Noto Color Emoji，比Symbola彩色效果更完善）替换fallback，再配合XeTeX的字符配置强制彩色渲染：

修改conf.py的preamble：

latex_elements = {
    'preamble': r'''
\usepackage{fontspec}
\usepackage{xcolor}
% 主字体fallback到Noto Color Emoji
\setmainfont{FreeSerif}[
    RawFeature={fallback=NotoColorEmoji}
]
% 标题字体fallback
\setsansfont{FreeSans}[
    BoldFont=FreeSansBold,
    RawFeature={fallback=NotoColorEmoji}
]
% 代码字体fallback
\setmonofont{FreeMono}[
    RawFeature={fallback=NotoColorEmoji}
]
% 强制Emoji彩色渲染
\XeTeXinterchartokenstate=1
\newXeTeXintercharclass\emojiclass
% 覆盖主流Emoji的Unicode区间
\XeTeXcharclass"1F600"1F64F=\emojiclass
\XeTeXcharclass"1F300"1F5FF=\emojiclass
\XeTeXcharclass"1F680"1F6FF=\emojiclass
\XeTeXcharclass"1F1E0"1F1FF=\emojiclass
\XeTeXinterchartoks 0 \emojiclass={\begingroup\color{black!0}}
\XeTeXinterchartoks \emojiclass 0={\endgroup}
\XeTeXinterchartoks \emojiclass \emojiclass={\endgroup\begingroup\color{black!0}}
''',
}

前提：系统已安装Noto Color Emoji字体。

你的疑问解答 #

1. tex文件里为何同时有\setmainfont{FreeSerif}和\setmainfont{Symbola}？能否将Symbola设为FreeSerif的fallback？ #

• 原因：Sphinx默认LaTeX模板会自动设置主字体为FreeSerif，你在preamble中手动添加的\setmainfont{Symbola}会覆盖这个默认配置，所以tex文件中会出现两次主字体设置。
• 完全可以用fallback：就是上面第一部分的方案，给FreeSerif添加Symbola作为fallback，既保留FreeSerif作为正文主字体，遇到Emoji时自动切换到Symbola渲染，不会有重复设置的问题。

2. 能否实现彩色Emoji显示？ #

• 可以，按照上面第二部分的方案，使用支持彩色的Emoji字体（如Noto Color Emoji）作为fallback，再配合XeTeX的字符类配置强制彩色渲染，就能生成带彩色Emoji的PDF。

内容的提问来源于stack exchange，提问作者user3313834