装好 Manim 之后,中文用户第一时间撞上的往往不是 API,而是一排方框。写了 Text("你好"),成片里变成 □□□;改成 MathTex("当 x 趋近于 0"),直接抛一大串 LaTeX 报错。这两个问题看着像一回事,其实走的是两条完全不同的链路,解法也不一样。

这篇是安装部分的最后一块补遗。结论先放这儿:中文文字用 Text,数学公式用 MathTex,别把中文塞进公式对象里。 守住这条,九成的坑都不会踩到。

前提:已按 第二篇 装好 Manim Community 0.22.1,checkhealth 能通过。本文命令默认在项目根目录执行;uv 路线统一加 uv run 前缀,pip / conda 路线去掉前缀即可。所有版本信息以 2026 年 11 月的官方文档为准。

一、先分清三条链路

对象 底层 要不要 LaTeX 中文怎么办
Text / MarkupText Pango(ManimPango) 不要 指定含中文字形的字体族名
Tex / MathTex LaTeX + dvisvgm 要 默认模板不支持,要么拆开写,要么换 ctex 模板
Typst 内置编译器 不要 另一套语法,本文不展开

最容易混的是前两行:Text 和 Tex 只差一个字母,却是两套东西。官方《Rendering Text and Formulas》里有一句说得很直白 —— 如果只是排文字,大概根本不需要 Tex,应该用 Text 代替。

图 1:中文内容该走哪条渲染链路

二、Text 的中文:先别急着改配置

方框不等于「Manim 不支持中文」。 官方教程明确写了 Text 用 Pango 渲染,能显示「你好」「こんにちは」「안녕하세요」,还给了中文示例:

1
2
3
4
5
6
from manim import *

class MultipleFonts(Scene):
def construct(self):
chinese = Text("臂猿「黛比」帶著孩子", font="sans-serif")
self.add(chinese)

也就是说,在装了中文字体的中文 Windows、macOS 上,Text("你好") 通常是正常的。真正出方框的是这三种情况:

  1. 容器或精简 Linux 里一个中文字体都没有(官方 Docker 镜像就是这种);
  2. 显式指定了不含中文的字体,比如 font="Consolas";
  3. 字体族名写错了,Pango 回退到一个缺字的字体。

所以别一上来就重装 LaTeX、改环境变量 —— 那跟中文方框基本无关。

查一下系统里到底有哪些字体

1
2
import manimpango
print(manimpango.list_fonts())

不想建文件就一行命令:

1
uv run python -c "import manimpango; print(manimpango.list_fonts())"

输出是一长串字体族名,形如 ['Arial', 'DengXian', 'KaiTi', 'Microsoft YaHei', ...]。这是字体族名,区分大小写,既不是文件名,也不是「微软雅黑」这类中文显示名。

Text 在 0.22.1 的官方签名里写得很清楚:font 是 the font family to be used to render the text,取值要么是系统字体,要么是用 register_font() 加载过的字体;另外还有个 warn_missing_font=True,字体名不在 list_fonts() 里时会发警告。看到这类警告别当噪音划过去,它就是在告诉你「这个名字没匹配上」。

一处常见错法:不少中文教程让你写 Text("你好", font="C:/Windows/Fonts/msyh.ttc")。按官方参数定义,font 是字体族名而不是文件路径,这种写法不保证生效,换个平台必然失效。要用没装进系统的字体文件,正确做法见第四节。

各平台常见的中文字体族名:

系统 可用字体族名
Windows Microsoft YaHei、Microsoft YaHei UI、SimHei、SimSun、DengXian、KaiTi
macOS PingFang SC、Heiti SC、Songti SC
Linux Noto Sans CJK SC、Source Han Sans SC、WenQuanYi Micro Hei
通用 sans-serif(交给 Pango 回退,最省事但不可控)

字体名写错时 Manim 不会崩,只会给个警告然后继续用回退字体,所以一定要按 list_fonts() 的输出原样抄,别凭印象填。Microsoft YaHei 写成 microsoft yahei 就匹配不上了。

一次设好,别每个 Text 都写一遍

最稳的是封装一个小函数:

1
2
3
4
5
6
7
from manim import *

CN_FONT = "Microsoft YaHei" # macOS 改 "PingFang SC",Linux 改 "Noto Sans CJK SC"


def cn(text, **kwargs):
return Text(text, font=CN_FONT, **kwargs)

社区里也常用 set_default,一行搞定(个别版本若提示没有这个方法,用上面的 cn() 函数即可):

1
Text.set_default(font="Noto Sans CJK SC")

把字体名做成常量还有个实际好处:脚本拷到另一台机器上,只改一行就能跑,不用满文件找 font=。

三、方框还在:给系统装一套中文字体

按 list_fonts() 的结果判断。Windows 和 macOS 一般自带,直接跳过;Linux 服务器和容器通常要补:

1
2
3
4
5
# Debian / Ubuntu
sudo apt install fonts-noto-cjk

# 查看已安装的中文字体
fc-list :lang=zh family | sort -u

官方 Docker 镜像 manimcommunity/manim 要特别注意两件事:它自带的是精简版 TeX Live,默认没有 ctex 宏包(官方 Docker 文档明确写了,用到 TexTemplateLibrary.ctex 时要在容器里 tlmgr install ctex);同样也别指望里面有中文字体。两者一起补:

1
2
apt-get update && apt-get install -y fonts-noto-cjk
tlmgr install ctex

用 Docker 时把这两行写进 Dockerfile,别只在运行中的容器里敲一次,否则下次 docker run 又回到原样。

图 2:中文方框的四步排查顺序

装完字体要重启渲染进程或容器。Pango 的字体缓存不会在你装字体的那一刻刷新,同一个 Python 进程里继续渲染,看到的还是旧列表。

截图位 A:list_fonts() 的输出里圈出中文字体族名,保存为 uploads/allimg/2026/0198/list-fonts.png 后插入本节。

四、想用某个下载来的字体文件:register_font()

字体没装进系统、只是放在项目里,用官方提供的 register_font():

1
2
3
4
5
from manim import *

with register_font("fonts/SourceHanSansSC-Regular.otf"):
title = Text("用下载来的字体", font="Source Han Sans SC")
# 在 with 块内创建的所有 Text 都能用这个字体

几个容易踩的细节:

  • 它是上下文管理器,退出 with 后字体会被注销,所以 Text 对象要在块内创建;
  • 文件查找顺序是:绝对路径 → assets/fonts/ → font/ → 当前目录,找不到会抛 FileNotFoundError;
  • font= 里仍然要写字体文件内部登记的字体族名,不是文件名;不知道叫什么,先用系统字体查看器打开 ttf/otf 看一眼;
  • macOS 上需要 ManimPango ≥ 0.2.3,更早的版本会抛 AttributeError。

这一步做完,font 参数就和「路径」彻底没关系了:要么填系统里已有的族名,要么先 register_font() 再填该字体的族名。

五、公式里的中文:为什么会炸

MathTex 传进去的一切内容,默认都在 LaTeX 的 align* 数学环境里。中文既不是数学符号,默认模板的 preamble 里也没加载任何 CJK 宏包 —— 所以:

1
2
# 会报错或丢字,别这么写
MathTex(r"当 x \to 0 时,f(x) \to 1")

写成 \text{当 x 趋近于 0} 也救不了,默认编译器是 latex,遇上 UTF-8 中文同样过不去。

推荐解法:拆开排版

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
from manim import *

CN_FONT = "Microsoft YaHei"


class ChineseAndFormula(Scene):
def construct(self):
title = Text("函数的极限", font=CN_FONT, font_size=56)
formula = MathTex(r"\lim_{x \to 0} \frac{\sin x}{x} = 1", font_size=64)
note = Text("当 x 趋近于 0 时", font=CN_FONT, font_size=32)

VGroup(title, formula, note).arrange(DOWN, buff=0.5)

self.play(Write(title))
self.play(Write(formula))
self.play(FadeIn(note, shift=UP * 0.2))
self.wait()

中文走 Pango、公式走 LaTeX,各自用最擅长的那套,最后靠 VGroup.arrange() 在画面上拼起来。观众看不出差别,但公式少一次 CJK 编译,渲染更快,报错也少一大半。

图 3:中文标题、公式、注释分别生成后叠成同一画面

真要混排:ctex 模板

官方 TexTemplateLibrary.ctex 就是为「公式里夹几个汉字」准备的,官方示例原样:

1
2
3
4
5
6
7
8
from manim import *

class LaTeXTemplateLibrary(Scene):
def construct(self):
tex = Tex('Hello 你好 \\LaTeX',
tex_template=TexTemplateLibrary.ctex,
font_size=144)
self.add(tex)

翻一下 0.22.1 里这个模板的定义,三条信息很关键:

1
2
3
tex_compiler  = xelatex
output_format = .xdv
preamble 含 \usepackage[UTF8]{ctex}

也就是说它换用了 XeLaTeX 编译器、产物是 .xdv(仍由 dvisvgm 转成 SVG)、并且必须装 ctex 宏包。对比一下 default 模板用的是 latex + .dvi,就能明白为什么照着默认配置折腾中文永远不通。

官方在给出这个例子的同时就提醒了:只排文字别用 Tex。ctex 是给「同一行里既有公式又有汉字」准备的,不是中文排版的默认方案。

六、把 ctex 环境配齐

Windows(MiKTeX):装完整版 MiKTeX(见第二篇第七节),打开 MiKTeX Console 把「Always install missing packages on-the-fly」打开。第一次跑 ctex 模板会弹窗问要不要装 ctex 及其依赖,允许即可,别手动取消。然后验证:

1
2
xelatex --version
dvisvgm --version

macOS(MacTeX):完整版自带;若用的是精简版 BasicTeX:

1
sudo tlmgr install ctex

Linux(TeX Live):

1
2
3
4
sudo tlmgr install ctex

# Debian / Ubuntu 也可以用发行版包
sudo apt install texlive-lang-chinese texlive-xetex

Docker:tlmgr install ctex,写进 Dockerfile。

配完别急着 -p 慢慢等播放器,用 -s 只出末帧 PNG,几秒就能验完:

1
uv run manim -s -ql ctex_demo.py LaTeXTemplateLibrary

能出 PNG,就说明 xelatex → .xdv → dvisvgm → SVG 这条链路通了。顺手再跑一次 uv run manim checkhealth,确认 LaTeX 相关检查项都通过。

截图位 B:manim -s 输出的末帧,中文与公式同屏。建议保存为 uploads/allimg/2026/0198/ctex-demo.png 后插入本节。

七、验收清单

检查项 命令 / 操作 期望结果
系统有中文字体 manimpango.list_fonts() 输出里有 Microsoft YaHei / PingFang SC / Noto Sans CJK SC
中文 Text 正常 manim -s -ql demo.py ChineseAndFormula 末帧里中文清晰、无方框
没有字体警告 看渲染日志 不出现 warn_missing_font 相关提示
公式正常 同上 极限公式完整显示
LaTeX 工具链 uv run manim checkhealth LaTeX 相关检查项通过
ctex(按需) xelatex --version 返回版本号

前三项过了,日常做中文视频就够了;ctex 只有真要中英文同处一行时才需要验。

八、常见报错对照表

症状 原因 解法
中文全是方框 字体族不含中文字形,或系统压根没装中文字体 list_fonts() 核对;Linux / Docker 装 fonts-noto-cjk;显式 font=CN_FONT
出现字体缺失警告(warn_missing_font) 字体族名拼错、大小写不对 从 list_fonts() 输出原样复制
font="C:/Windows/Fonts/msyh.ttc" 不生效 font 收的是字体族名,不是路径 改用 register_font(),或填系统字体族名
装完字体仍是方框 Pango 字体缓存没刷新 重启渲染进程 / 容器
MathTex 中文报 LaTeX Error 或直接丢字 默认模板在 align* 环境,无 CJK 支持 拆成 Text + MathTex;必要时上 ctex 模板
File 'ctex.sty' not found 没装 ctex 宏包 MiKTeX 允许自动安装,或 tlmgr install ctex
xelatex not found / dvisvgm not found 用了精简 LaTeX 发行版 装完整版或补包,checkhealth 复查
Docker 里中文方框、公式报错 镜像只有精简 TeX Live,且无中文字体 Dockerfile 里补 fonts-noto-cjk 与 tlmgr install ctex
register_font() 抛 FileNotFoundError 字体文件路径不在查找范围内 用绝对路径,或放进 font/ 目录
macOS 上 register_font() 抛 AttributeError ManimPango 版本过旧 升级到 ≥ 0.2.3

九、可以先跳过的:Typst

第二篇提过 uv add "manim[typst]" 能启用 Typst 渲染,它自带编译器、不依赖系统 LaTeX。但中文字体照样得自己指定,语法又是另一套,跟本文这两条链路不通用。等主线内容写完再单独说,现在不用碰。

小结

三句话收尾:

  • 中文文字交给 Text,font 填字体族名,用 manimpango.list_fonts() 查,别填路径;
  • 数学公式交给 MathTex,中文和公式拆成两个对象,再用 VGroup 拼;
  • 只有必须同处一行时才用 TexTemplateLibrary.ctex,并配好 xelatex + ctex 宏包 + dvisvgm。

环境到这里就彻底收口了,下一篇回到正题:用 Scene、Mobject、Animation 做第一个真正属于自己的动画。

返回第二篇:安装 Manim 并渲染第一个动画

参考与配图

本站为非官方个人博客,与 Manim Community 及 3Blue1Brown 无隶属关系。遇到安装问题请以官方文档为准。