装好 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 代替。

二、Text 的中文:先别急着改配置
方框不等于「Manim 不支持中文」。 官方教程明确写了 Text 用 Pango 渲染,能显示「你好」「こんにちは」「안녕하세요」,还给了中文示例:
1 | from manim import * |
也就是说,在装了中文字体的中文 Windows、macOS 上,Text("你好") 通常是正常的。真正出方框的是这三种情况:
- 容器或精简 Linux 里一个中文字体都没有(官方 Docker 镜像就是这种);
- 显式指定了不含中文的字体,比如
font="Consolas"; - 字体族名写错了,Pango 回退到一个缺字的字体。
所以别一上来就重装 LaTeX、改环境变量 —— 那跟中文方框基本无关。
查一下系统里到底有哪些字体
1 | import manimpango |
不想建文件就一行命令:
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 | from manim import * |
社区里也常用 set_default,一行搞定(个别版本若提示没有这个方法,用上面的 cn() 函数即可):
1 | Text.set_default(font="Noto Sans CJK SC") |
把字体名做成常量还有个实际好处:脚本拷到另一台机器上,只改一行就能跑,不用满文件找 font=。
三、方框还在:给系统装一套中文字体
按 list_fonts() 的结果判断。Windows 和 macOS 一般自带,直接跳过;Linux 服务器和容器通常要补:
1 | # Debian / Ubuntu |
官方 Docker 镜像 manimcommunity/manim 要特别注意两件事:它自带的是精简版 TeX Live,默认没有 ctex 宏包(官方 Docker 文档明确写了,用到 TexTemplateLibrary.ctex 时要在容器里 tlmgr install ctex);同样也别指望里面有中文字体。两者一起补:
1 | apt-get update && apt-get install -y fonts-noto-cjk |
用 Docker 时把这两行写进 Dockerfile,别只在运行中的容器里敲一次,否则下次 docker run 又回到原样。

装完字体要重启渲染进程或容器。Pango 的字体缓存不会在你装字体的那一刻刷新,同一个 Python 进程里继续渲染,看到的还是旧列表。
截图位 A:
list_fonts()的输出里圈出中文字体族名,保存为uploads/allimg/2026/0198/list-fonts.png后插入本节。
四、想用某个下载来的字体文件:register_font()
字体没装进系统、只是放在项目里,用官方提供的 register_font():
1 | from manim import * |
几个容易踩的细节:
- 它是上下文管理器,退出
with后字体会被注销,所以Text对象要在块内创建; - 文件查找顺序是:绝对路径 →
assets/fonts/→font/→ 当前目录,找不到会抛FileNotFoundError; font=里仍然要写字体文件内部登记的字体族名,不是文件名;不知道叫什么,先用系统字体查看器打开 ttf/otf 看一眼;- macOS 上需要 ManimPango ≥ 0.2.3,更早的版本会抛
AttributeError。
这一步做完,font 参数就和「路径」彻底没关系了:要么填系统里已有的族名,要么先 register_font() 再填该字体的族名。
五、公式里的中文:为什么会炸
MathTex 传进去的一切内容,默认都在 LaTeX 的 align* 数学环境里。中文既不是数学符号,默认模板的 preamble 里也没加载任何 CJK 宏包 —— 所以:
1 | # 会报错或丢字,别这么写 |
写成 \text{当 x 趋近于 0} 也救不了,默认编译器是 latex,遇上 UTF-8 中文同样过不去。
推荐解法:拆开排版
1 | from manim import * |
中文走 Pango、公式走 LaTeX,各自用最擅长的那套,最后靠 VGroup.arrange() 在画面上拼起来。观众看不出差别,但公式少一次 CJK 编译,渲染更快,报错也少一大半。

真要混排:ctex 模板
官方 TexTemplateLibrary.ctex 就是为「公式里夹几个汉字」准备的,官方示例原样:
1 | from manim import * |
翻一下 0.22.1 里这个模板的定义,三条信息很关键:
1 | tex_compiler = xelatex |
也就是说它换用了 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 | xelatex --version |
macOS(MacTeX):完整版自带;若用的是精简版 BasicTeX:
1 | sudo tlmgr install ctex |
Linux(TeX Live):
1 | sudo tlmgr install ctex |
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 做第一个真正属于自己的动画。
参考与配图
- 官方文字与公式教程(含 ctex 示例):https://docs.manim.community/en/stable/guides/using_text.html
Text类参考(font、warn_missing_font):https://docs.manim.community/en/stable/reference/manim.mobject.text.text_mobject.Text.htmltext_mobject模块(register_font):https://docs.manim.community/en/stable/reference/manim.mobject.text.text_mobject.htmlTexTemplateLibrary定义(ctex 的编译器与 preamble):https://docs.manim.community/en/stable/reference/manim.utils.tex_templates.TexTemplateLibrary.html- 官方 Docker 安装页(精简 TeX Live 与 ctex 说明):https://docs.manim.community/en/stable/installation/docker.html
本站为非官方个人博客,与 Manim Community 及 3Blue1Brown 无隶属关系。遇到安装问题请以官方文档为准。


















