explainroo 常见问题排查手册：渲染失败、发音错误、文字被裁切等 10 个高频坑及解法

用 explainroo 生成讲解视频（explainer video）时，新手最容易卡在几类问题上：环境没配好导致渲染失败、语音把单词读错、画面里的文字被裁切或压盖。本文整理了 10 个高频坑及对应解法，按"环境与渲染、发音与语音、文字与版面、成片检查"四个环节展开，每个坑都给出可直接执行的排查命令，帮助你在本地免费、无需 API Key 地顺利产出带配音的 MP4。

整个流程由 bin/explainroo.js 统一驱动：Kokoro 本地朗读script.md，Whisper 标记每个单词的说话时间，Chrome 在后台逐帧绘制画面，ffmpeg 合成 MP4。完整操作规范见 AGENTS.md，本文的解法均出自该项目文档。

一、环境与渲染：视频"生不出来"的坑

坑 1：Node、ffmpeg 或 Chrome 缺失，命令直接报错

explainroo 需要 Node.js 20.11 及以上、ffmpeg 和 Chrome/Chromium，三者缺一就会在启动或渲染时报错。首次安装后，先运行体检命令一次性检查所有依赖，并下载约 400 MB 的英语语音模型：

git clone https://gitcode.com/gh_mirrors/ex/explainroo cd explainroo npm install node bin/explainroo.js doctor --fetch

doctor会逐项报告 Node、ffmpeg、Chrome 及各语言额外依赖的状态，是排查环境问题最快的入口。

坑 2：渲染中途报 EPIPE 或浏览器关闭（closed browser）

在负载较高的电脑上，render会默认开出较多并行页面（最多 8 个）同时绘制帧，资源吃紧时后台浏览器可能被系统杀掉，渲染随之中断。官方给出的解法是减少并行页数后重跑：

node bin/explainroo.js render videos/<name> --workers 2

并行数由 src/render.js 中的workers逻辑控制，默认取 CPU 核数的一半且不超过 8。先渲染--draft半尺寸草稿定位问题，再跑正式版，也能显著降低内存压力。

二、发音与语音：声音"不对"的坑

坑 3：语音把缩写、版本号、域名读错

voice命令结束后会打印每个场景的时长和"语音检查确认了多少词"。若某词未被确认，说明声音大概率读错了，此时用{显示文本|发音文本}覆盖写法修正后重跑，只有改动过的场景会重新合成：

{SQL|sequel} {v2.1|version two point one} {example.com|example dot com} # 否则语音会读成 "example comm"

这个覆盖语法同时作用于字幕和语音检查，是处理读错词的第一选择，细节见 src/voice.js。

坑 4：同音词读混、缩写逐字母拼读失败

语音检查会听见 "won" 像 "one"、"plain" 像 "plane"，这类同音混淆{shown|spoken}无法修复，只能改写句子绕开。逐字母的缩写请写成{API|A, P, I}的形式，不要写成A.P.I.——语音模型会把点号当网址读。日语、中文里个别汉字读音选错（如"一日"）时，同样按读音写出期望读法，例如{グレゴリオ暦|グレゴリオれき}。

坑 5：小语种报错，缺 espeak-ng 或 misaki

各语言的语音依赖不同，报错时先对照环境：

• 西班牙语、法语、意大利语、葡萄牙语、印地语需要 espeak-ng：sudo apt install espeak-ng或brew install espeak-ng，路径异常时用EXPLAINROO_ESPEAK指定二进制；
• 日语、中文需要 Python 3 + misaki 发音库：python3 -m pip install "misaki[zh]"（日语为misaki[ja]并需下载 unidic 词典），虚拟环境下用EXPLAINROO_PYTHON指定解释器；
• 英语、ElevenLabs 和自录人声不需要以上任何工具。

首次渲染日文/中文视频时，explainroo 还会自动下载约 33 MB 的 Noto Sans JP/SC 字体到缓存目录，下载完成后设置EXPLAINROO_OFFLINE=1即可离线使用。

三、文字与版面：画面"不好看"的坑

坑 6：文字被裁切、越界或与其他元素重叠

这是新手最高频的视觉问题。check命令会找出跑出版面的文字、离边缘过近（3.5% 以内）、字号过小、文字压文字、以及掉进字幕带的内容，报错信息里直接给出位置：

node bin/explainroo.js check videos/<name>

修复原则：布局从s.safe（安全区）而不是固定像素出发；同一时间屏上元素控制在 5~6 个，旧元素用out及时离场；标题 80~110 px、标签 40~56 px。检查通过后，务必再用静帧和连续帧图肉眼复核，因为check只看文字和公式，形状、箭头、图标需要你自己看：

node bin/explainroo.js still videos/<name> # 每个场景的收尾帧 node bin/explainroo.js sheet videos/<name> # 整片抽帧拼成一张图

坑 7：投到信息流后文字太小

16:9 原片上看着合适的字号，放到 Reddit、B 站信息流等约 854 px 宽的小播放器里就可能缩到 16 px 以下。官方建议对信息流场景加一个查看宽度再跑检查：

node bin/explainroo.js check videos/<name> --view-width 854

它会在可见文字缩小到 16 px 以下时给出警告；静帧也可以按--scale 0.4448（1080p 约等于 480p）复核。修复方式是放大字号、只展示当前查询结果、把细节交给镜头推近。不同平台的画幅选择可参考explainroo formats的输出。

坑 8：文字颜色与背景对比度不足

在paper和clean等浅色风格里，绿、橙、红作为形状颜色是够鲜亮的，但直接拿来当文字颜色往往偏淡、看不清。check会检测文字相对页面背景（或自带bg卡片）的对比度，警告时会给出一个可读的替代色并附上对比度数值，照着换色即可。六种内置风格（paper、clean、chalk、blueprint、midnight、editorial）各有独立的调色，换风格后建议重跑一次检查：

坑 9：镜头推近后，标题或卡片被切一半

explainroo 0.4 起每场画面都有跟随旁白的自动镜头，静帧里完整的文字在动态镜头里可能被切。官方规则是：镜头停留时，卡片和标签要么完整入画、要么完全出画；做产品演示用s.ui.headline画大标题时，标题必须画在s.camera()之后，且镜头缩放要么不超过约 1.1 倍（标题始终完整可见），要么直接缩到约 1.3 倍以上让标题出画，介于两者之间标题就会被拦腰切断。需要镜头保持不动时，在场景开头调用s.camera([])即可。

另外两个版面高频坑也一并提醒：

• 提示词（cue）失效：同一个词说两次时，at: 'word'只对第一次生效，第二次要用s.cue('word', 2)或[#marker]；带撇号的词（如 visitor's）会被当作 visitors，此处也应改用 marker。
• 元素偶尔才调用：不要写if (s.t > 3) s.box(...)，应始终调用并靠at/out控制出现时机，否则音效和检查都会失灵。

四、成片检查：文件"不合格"的坑

坑 10：MP4 里有黑帧、静音，或音乐盖过人声

渲染完成后不要直接上传，先跑verify。它会测量响度、检测黑帧与静音段，并对成片音轨重跑一次语音检查，确认人声在背景音乐之上依然清晰：

node bin/explainroo.js verify videos/<name>

常见问题与对应调整：响度不达标就改 src/project.js 中video.json的loudness（默认 -14 LUFS）；音乐太抢戏可把music设为false或调低音量；屏幕录制出现跳帧、卡帧，多因原始素材是可变帧率，录制时固定帧率即可。检查逻辑位于 src/qa.js，报错信息可直接定位到具体时间点。

收尾：一套固定的排查顺序

把 10 个坑串起来，日常工作流其实是一条流水线：doctor体检环境 →voice看发音确认词数 →check清版面警告 →still+sheet肉眼看帧 →render出片 →verify验收。每个环节的输出都指向下一个环节的入口，遇到任何一步卡住，回到本文对应小节按命令排查即可。想直接对照修改，仓库自带的完整示例在 examples/，其中 examples/how-dns-works/scenes.js 是一个结构清晰、适合新手参考的场景写法。