OpenMontage 的 Node 版本口径：前置要求写 18+，HyperFrames 那行标的是 ≥ 22

2026-08-09

装环境这件事，最怕的不是文档没写，而是文档写了两遍、两遍写的不一样。OpenMontage 的 README 里就有这么一处：前置条件那节要你准备 Node.js 18+，往下翻到合成运行时那张表，HyperFrames 那一行标的是 Local (Node.js ≥ 22)。

这篇就只干一件事：把这两处原文摆到一起，说清差异落在哪、什么时候会真的碰到它、动手前怎么确认自己处在哪一档。以及同样重要的——哪些话不能从这处差异里推出来。

两处原文分别在哪

第一处，Quick Start 的 Prerequisites。 README 列了四项前置条件：Python 3.10+、FFmpeg（给了 brew install ffmpeg / sudo apt install ffmpeg / ffmpeg.org 三条路）、Node.js 18+，以及第四项「一个 AI 编码助手」（Claude Code、Cursor、Copilot、Windsurf 或 Codex 之一）。这是你 clone 完仓库、准备跑 make setup 之前会看的那一节，也是很多人只会看这一眼的那一节。

第二处，Composition & Rendering 那张表。 这张表一共三行，讲的是这个项目用什么把素材变成成片。只引与本篇直接相关的两行——因为差异恰好就藏在这两行的 Type 一列里：

Engine	Type
Remotion	Local (Node.js)
HyperFrames	Local (Node.js ≥ 22)

三行里只有 HyperFrames 这一行写了具体的版本下限。Remotion 那行只写 “Local (Node.js)“，没给数字；第三行是 FFmpeg，Type 一列标的是 “Local”，整行没有出现 Node 字样。

所以差异是这样的形状：按最低前置条件（Node 18）准备好的环境，可能达不到 HyperFrames 那一行标注的 Node ≥ 22。 这是两处 README 文本之间可以逐字核对的不一致，我把它如实指出来，到此为止——我不推断哪一处是准的、不推断作者是不是漏了同步，也不打算拿它去评价这个项目。同样地，我也不会说「所以 HyperFrames 在 Node 18 上一定跑不起来」，我们没有安装或运行过这套系统，那句话我没有依据说。

为什么这不是「翻到再说」的小事

如果 HyperFrames 是个可选的高级玩法，这处差异确实可以放着。问题是它不在可选那一侧。

第一，零密钥路径也会走到它。 README 有一节 “What You Get With Zero API Keys”，开篇原话是你不需要付费 API 密钥就能做出真视频。那张表里 Composition 是两行：Composition (React) 对应 Remotion，Composition (HTML/GSAP) 对应 HyperFrames。也就是说，哪怕你一个 .env 密钥都不填，HyperFrames 也在 make setup 之后被列为开箱可用的合成能力之一。Node 版本这件事，不是「等你开始花钱调 API 才需要操心」的东西。

第二，走不走它不完全由你临时决定。 README 写的规则是，运行时在提案阶段被选定，并锁定为 render_runtime。默认分工原文是：Remotion 是数据驱动讲解片、以及任何使用既有 React 场景栈的默认；HyperFrames 是动态图形密集、天然适合用 HTML + GSAP 表达的需求的默认，包括 character-animation 流水线的 SVG/GSAP 骨架输出。换句话说，你要是开口就说想要一段卡通角色表演，按这条默认分工，落到 HyperFrames 这一侧是相当自然的事。至于两个运行时具体怎么选、锁定之后意味着什么，本批另有两篇专门讲，这里不展开。完整的决策矩阵，README 指向 skills/core/hyperframes.md——这个文件我们没有读过，只能提它的名字。

第三，它不在安装步骤里露面。 README 给的手动安装串里（下一节照抄），只有 cd remotion-composer && npm install 这一步动了 Node 那侧，装的是 Remotion 的合成引擎。HyperFrames 没有对应目录，README 明说它是通过 npx hyperframes 消费的、无需 checkout 整个 monorepo。仓库里与它相关的 Python 文件是 lib/hyperframes_style_bridge.py，这个文件确实存在，内部我们没有读过，不做描述。

这三条合起来意味着：装环境的时候你不会被 HyperFrames 绊一下，因为安装步骤压根不碰它；真要碰上，是在提案阶段选定运行时、往下走到合成那一步的时候。这个时间差是这处版本口径差异最值得记一笔的地方。

动手前怎么确认自己处在哪一档

判定动作其实只有一个：先看你本机 Node 的主版本号是几。用 Node 自带的版本查询命令即可（这是 Node 的命令，不是 OpenMontage 的命令，本文不代写它的输出）。拿到主版本号之后，对照上面两处原文自己判断：

主版本号 ≥ 22：README 的两处标注你都覆盖了，这件事对你不成立。
主版本号在 18 到 21 之间：你满足 Prerequisites 那一项，但没达到 HyperFrames 那一行标注的下限。这时候要做什么，是你自己的取舍——README 在这两处给的口径不一样，我们没有实测过 Node 18 到 21 上 HyperFrames 的行为，不替你下结论。
主版本号 < 18：连 Prerequisites 都没满足，先解决这一条。

还有一个反过来的问题值得一并说清：只走 Remotion 那一侧的人，该按几准备？ README 给不出更细的答案——Composition & Rendering 表里 Remotion 那行只写了 “Local (Node.js)“，没有任何版本数字，所以整篇 README 里与 Remotion 相关的 Node 数字，就只剩 Prerequisites 那句 18+。这不是我在替它补充，而是如实说明：这个问题在 README 文本范围内没有第二个出处可查。

判断自己会不会落到 HyperFrames 那一侧，还可以看需求形态。README 在零密钥能力表里给 HyperFrames 的描述是 HTML/CSS/GSAP 渲染——动态排版、产品宣传片、发布视频、registry blocks、website-to-video 工作流，以及绑定骨架的 SVG 角色动画。你要做的东西如果长得像这几样，就别把 Node 版本这件事拖到合成那一步再想。

顺带把安装步骤本身抄清楚，两个系统分开写。README 给的标准路径是：

git clone https://github.com/calesthio/OpenMontage.git
cd OpenMontage
make setup

没有 make 的话，README 另给了手动串。macOS/Linux：

python3 -m venv .venv && source .venv/bin/activate && python -m pip install -r requirements.txt && cd remotion-composer && npm install && cd .. && python -m pip install piper-tts && cp .env.example .env

Windows PowerShell：

py -3 -m venv .venv; .\.venv\Scripts\Activate.ps1; python -m pip install -r requirements.txt; cd remotion-composer; npm install; cd ..; python -m pip install piper-tts; Copy-Item .env.example .env

以上两串照抄自 README，我们没有执行过。

一条必须单独拎出来的 Windows 已知问题

README 在这里单记了一条：Windows 上如果 npm install 报 ERR_INVALID_ARG_TYPE，改用 npx --yes npm install。

这条要照原样理解，不要顺手把它接到上一节的版本话题上。README 记的是「出现这个报错就换那条命令」，它没有说这个报错的成因是什么，更没有说它和 Node 版本有关。我在这里也不推断——两件事都发生在 Node 那一侧、都跟 remotion-composer/ 那一步有关，但「相邻」不等于「相关」。你真遇上了，就按 README 给的替代命令走；它没解决，那就说明不是这条已知问题覆盖的情况，得另找原因，而不是回头去改 Node 大版本碰运气。

这处差异能推出什么、不能推出什么

能推出的：README 里关于 Node 的两处标注数字不同，一处是 18+，一处是 ≥ 22；两处都是 README 自己的文本；三个合成运行时里只有 HyperFrames 标了版本下限。这些都是逐字可核对的。

不能推出的：不能推出哪一处「是对的」，不能推出为什么会不一致，不能拿它去评价这个项目的质量或可信度，也不能推出 Node 18 上 HyperFrames 的实际行为——我们既没装过也没渲染过任何一条视频。顺便说一句，仓库里这种可核对的口径差异不止这一处（比如 TTS 的 provider 数量在两个位置写的不一样），本批另有篇目逐个陈列，处理方式都一样：把两处原文摆出来，说完就停。

如果一定要给一句实操上的话，那就是：**你在读一个项目的前置条件时，别只读 Prerequisites 那一节。**真正会咬人的版本下限，经常藏在后面某张能力表的括号里——这次是 (Node.js ≥ 22)，下次可能是别的。文档的目录结构不保证约束都写在同一个地方。

本文依据 OpenMontage 官方仓库（github.com/calesthio/OpenMontage）的 README、 AGENT_GUIDE.md、config.yaml、pipeline_defs/ 与 lib/ 下的治理模块整理，核对日 2026-08-09。本文内容为仓库源码与文档口径，我们没有安装或运行过该系统，也没有调用过其中任何一个 provider API，文中出现的成本数字均为项目方在 README 中自行标注的金额，非我们的实测结果。该项目以 AGPL-3.0 发布，部分流水线在 manifest 中自标 stability: beta，请以仓库最新内容为准。