Node.js 兼容性
本参考文档涵盖受支持的 Node.js 主线、最低版本存在的原因,以及它们随 OpenClaw 各版本的变化。安装步骤请参阅 Node.js;macOS 配套应用要求请参阅 macOS。
受支持的版本¶
| 主线 | 状态 | 最低版本 | 说明 |
|---|---|---|---|
| Node 26 | 推荐 | >=26.1.0 |
与 Node 24 相比,Gateway 启动更快、内存占用更低。 |
| Node 24 | 受支持 | >=24.16.0 <25 |
CI 和 Linux 安装器使用的 LTS 主线。 |
| Node 25 | 不受支持 | — | 被当前 TEXT 解码器最低版本要求排除。 |
| Node 23 | 不受支持 | — | 此前因不兼容的 node:sqlite 行为被排除。 |
| Node 22 | 不受支持 | — | 自 24.16.0/26.1.0 最低版本要求起不受支持。 |
精确的 engines 表达式为 >=24.16.0 <25 || >=26.1.0。它既是文档化的支持策略,也是包管理器所使用的 package.json 引擎范围。
门槛如何判定¶
启动、doctor、Gateway 运行时选择、更新预检和安装器运行时验证都会检查实际的 node:sqlite 绑定:绑定必须存在、加载 WAL-safe SQLite 库,并在 TEXT、BLOB 和 JSON 往返转换过程中保留内嵌及末尾的 NUL 字符。该检查使用内存数据库并缓存当前进程的结果;对其他可执行文件的检查会在该可执行文件中运行同样的检查,并设有受限超时。若检查失败,则拒绝使用受支持版本表格内的构建。
运行中包的启动防护和 Gateway 运行时选择在检查通过时,会接受版本表格之外的 Node 24 或更新版本,并附注说明该版本不受支持但其能力通过了验证。其能力满足本包的正确性门槛,但仍处于经过测试的支持策略之外。这允许使用供应商移植版而不宣称对其版本提供支持。Node 22 和 23 仍被排除,且包管理器的引擎检查仍然生效。
安装器保留数字形式的 Node 要求,并将该检查作为第二道门槛。包和 Git 更新预检也以数字形式要求所选目标的 engines.node 范围,包括任何备用运行时。检查通过并不能放宽其他包的要求:较旧的版本在启动时仍可能强制实施其版本表格。
更新恢复流程会推荐同时满足候选版本引擎范围和上述本更新器支持范围的最低标准版本。例如,要求 >=22.19.0 的较旧候选版本仍会推荐 24.16.0,以便更新器能够运行。如果两个范围没有共同支持的版本,消息会指出这两个范围,并请你选择兼容的目标。选择运行时后,继续使用保留的绝对启动器,以便更新器在安装前重新检查前缀和服务所有权;请遵循完整的恢复流程。
最低版本存在的原因¶
SQLite WAL-reset 损坏漏洞要求加载安全的库:SQLite 3.51.3+、3.50.x 中的 3.50.7+ 或 3.44.x 中的 3.44.6+。OpenClaw 会验证实际加载的库,因为链接到系统共享 SQLite 的 Node 构建可能使用与 Node 自身元数据不同的版本。
另外,Node 22.23.x、24.15.0、25.9.0 和 26.0.0 中的 node:sqlite TEXT 解码器会在内嵌 NUL 字符处静默截断值。首个修复版本是 Node 24.16.0 和 26.1.0;WAL-safe SQLite 库并不能修复该解码器。Node 23 此前因不兼容的 node:sqlite 行为被排除。
V8 编译器设置¶
在 Node 24 和 26 上,process.exit() 可能在命令输出打印后永远挂起:Node 会等待 V8 的后台线程,而 Maglev 或并发 Sparkplug 编译任务又在等待一个永远不会由退出主线程执行的垃圾回收(nodejs/node#64274)。因此,OpenClaw 的 CLI、Gateway、hook 中继和 macOS node worker 启动时会关闭 Maglev 和并发 Sparkplug(Node 22 所使用的分层策略);TurboFan 仍会优化热点代码。向 node 传入 --maglev 或 --concurrent-sparkplug 可保持相应编译器启用。
平台影响¶
官方 Node 24+ macOS 二进制文件针对 macOS 13.5+ 构建,这是 Node 支持的最旧版本。macOS 并不会在更旧版本上阻止它们运行,且 CLI 和 Gateway 已被观察到可在使用官方 Node 24 的 macOS 12 上运行。OpenClaw 不测试也不支持 macOS 11 至 13.4,因此自带原生二进制文件的功能在这些系统上仍可能失败。配套应用有单独的 macOS 要求。
受支持的 Node 主线没有官方 Linux ARMv7 构建。请在兼容的 ARM 硬件上使用 64 位操作系统,或使用其他受支持的主机。
在基于 RPM 的发行版上,安装器会保留一个受支持但由发行版持有的 Node 包(该包链接了不安全的系统 SQLite),并为 OpenClaw 单独提供用户空间的运行时。
安装器提供的内容¶
推荐、受支持和实际提供是三种不同的概念。
| 平台 | 安装器路径 | 提供的 Node |
|---|---|---|
| Linux | install.sh:通过 NodeSource 使用 apt/dnf/yum |
Node 24.x LTS。 |
| Linux 和 macOS | 无 root 权限的 install-cli.sh |
默认 Node 24.21.0;复用现有运行时时或显式选择版本时可能不同。 |
| macOS | install.sh:Homebrew node |
Node 26;未固定具体补丁版本,可保留现有的受支持 Node。 |
| 平台 | 安装程序路径 | 配置的 Node |
|---|---|---|
| Windows | install.ps1:Chocolatey、Scoop 或 winget |
LTS 包;未固定精确补丁版本,安装后进行验证。 |
| Windows | install.ps1:便携回退 |
最新的 26.x Windows zip。 |
有关配置详细信息,请参阅安装程序内部机制。
检查你的运行时¶
对于推荐的安装路径,请使用受支持的 Node 版本。损坏的 TEXT 解码器会因以下诊断信息而被拒绝:
Node <v>: node:sqlite truncates TEXT at embedded NUL (nodejs/node#61954); use 24.16+/26.1+ or a build with the fix
跨版本历史¶
各行标识首个生效版本,包括适用时的 beta。即使数值要求保持不变,也会列出推荐和安装程序变更。
| 版本 | Node 要求 | 变更内容及原因 |
|---|---|---|
| 未发布(main) | 支持策略不变 | 用内存 NUL 往返检查取代仅基于解码器版本的准入;在 Node 24+ 上具备能力的供应商构建可能带不支持版本提示运行。Node 22/23 仍被排除。 |
| v2026.9.3 | >=24.16.0 <25 \|\| >=26.1.0 |
提高 Node 24 下限,并移除 Node 22 和 25,以防止嵌入式 NUL 导致的 TEXT 截断;Node 23 仍被排除。官方基于 Node 的 macOS 11–13.4 和 Linux ARMv7 配置支持结束。#140672 |
| v2026.8.2 | >=22.22.3 <23 \|\| >=24.15.0 <25 \|\| >=25.9.0 |
保留受支持的 RPM 拥有的 Node 包,这些包使用不安全的系统 SQLite,并配置一个独立的用户空间运行时。数值范围和已加载库的安全要求保持不变。#134166 |
| v2026.8.1 | >=22.22.3 <23 \|\| >=24.15.0 <25 \|\| >=25.9.0 |
无根默认值提升到 24.19.0,或在 ARMv7 上为 22.23.2。Linux 包配置返回 Node 24 LTS,以避免预发布仓库构建。#130369 |
| v2026.8.1-beta.3;稳定版 v2026.8.1 | >=22.22.3 <23 \|\| >=24.15.0 <25 \|\| >=25.9.0 |
在 node-version.mjs 中集中管理版本分类,拒绝预发布、nightly 和格式错误的版本标签。#124812 |
| v2026.7.2-beta.5;稳定版 v2026.8.1 | >=22.22.3 <23 \|\| >=24.15.0 <25 \|\| >=25.9.0 |
推荐 Node 26,相比 Node 24 具有更快的 Gateway 启动速度和更低的内存使用。CI 和发布工作流保留 Node 24。#114399 |
| v2026.7.1;main v2026.7.2-beta.1 | >=22.22.3 <23 \|\| >=24.15.0 <25 \|\| >=25.9.0 |
要求构建包含 SQLite WAL 重置修复,验证实际加载的 SQLite 库,并排除所有 Node 23。通过发布 cherry-pick 交付。#106065 |
| v2026.7.1-beta.2 | >=22.19.0 <23 \|\| >=23.11.0 |
由于方言的 StatementSync.columns() 路径中存在不兼容的 SQLite 行为,排除 Node 23.0–23.10。在稳定版 v2026.7.1 之前被取代。#99832 |
| v2026.5.16-beta.7;稳定版 v2026.5.18 | >=22.19.0 |
随着 Pi 依赖项更新到 0.75.1,提高下限。Node 24 仍为推荐版本。 |
| v2026.5.9-beta.1;稳定版 v2026.5.12 | >=22.16.0 |
为原生 SQLite Kysely 方言使用 StatementSync.columns() 识别产生结果的语句而提高下限。#78921 |
| v2026.3.24-beta.2;稳定版 v2026.3.24 | >=22.14.0 |
将下限从 22.16 降低,以便 npm 安装和自更新不会使现有 Node 22.14 用户陷入困境。 |
| v2026.3.12 | >=22.16.0 |
将下限从 22.12 提高,并使 Node 24 成为安装、CI 和发布的默认/推荐版本线。记录的变更未指明具体缺失的 API。 |
| v2026.2.6 | >=22.12.0 |
使启动守卫与包要求保持一致,因为 Matrix 的 SDK 要求 22.12,而旧运行时会产生误导性的模块未找到错误。#5370 |
| v2026.1.5(早期 v2.0.0-beta3) | 包 >=22.12.0;启动 >=22.0.0 |
将包下限从 22.0 提高到 22.12,未记录特定 API 原因。启动验证暂时保留旧的最小值。 |
| 2026 年之前 | >=22.0.0 |
最早的包 engine 声明要求 Node 22;未记录更具体的运行时功能依据。 |
| 版本 | Node 要求 | 更改内容及原因 |
|---|---|---|
相关¶
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw