Node 版本兼容恢复、nvm 检测与用户确认流程

当 addon.node、随包魔改 xbs isolated-vm 或其他 native 产物因为 Node ABI 不兼容无法加载时读取本文件。原则是先让用户确认是否安装 / 切换兼容 Node，再决定是否降级；不得在用户未同意前直接改全局 Node 环境。

兼容版本表

native 组件	兼容 Node.js 版本	失败后的默认处理
`assets/native-addon/<platform>-<arch>/addon.node`	`v25.8.2`	先询问是否通过 nvm 安装 / 切换到 `v25.8.2`，用户拒绝后才允许 NativeProtect / JS fallback
`assets/runtime-frameworks/xbs-isolated-vm/<platform>-<arch>/isolated_vm.node`	`v26.3.1`	先询问是否通过 nvm 安装 / 切换到 `v26.3.1`，用户拒绝后才允许改选框架或提供匹配构建产物；不得退回 npm 原版 isolated-vm

触发条件

遇到以下任一情况时启动本流程：

Node 报错包含 NODE_MODULE_VERSION、was compiled against a different Node.js version、Module did not self-register、The module was compiled against。
scripts/load_native_addon.js --json 输出 abiMismatch: true。
scripts/check_xbs_isolated_vm.js --json 输出 status: "abi-mismatch" 或 abiMismatch: true。
当前 Node 版本不是对应兼容版本，且 native 组件加载失败。

先检测当前 Node 与 nvm

node scripts/check_node_runtime_compat.js --target addon --markdown
node scripts/check_node_runtime_compat.js --target isolated-vm --markdown

也可以手动检测：

node -v
node -p "process.versions.modules"

Windows：

where.exe nvm
nvm version
nvm root

macOS / Linux：

bash -lc 'command -v nvm || true; [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh" && nvm --version || true'

用户确认模板

addon ABI 不兼容

当前 addon.node 与当前 Node ABI 不兼容。addon-first 是补环境硬性基线，因此不应直接降级到 NativeProtect。

兼容 Node.js 版本：v25.8.2。

请选择：
1. 自动检测 / 安装 nvm，并安装切换 Node.js v25.8.2 后重新加载 addon。
2. 我手动安装 nvm；安装完成后回复“nvm 已安装成功”。
3. 我已经安装 nvm，但当前未检测到；我提供 nvm 路径或可用 shell。
4. 不安装兼容 Node，允许本 case 降级到 NativeProtect / JS fallback，并记录差异。

在你确认前，我不会直接降级，也不会修改全局 Node 版本。

isolated-vm ABI 不兼容

当前随包魔改 xbs isolated-vm 与当前 Node ABI 不兼容。你已选择 isolated-vm 补环境框架，因此应先尝试兼容 Node，而不是退回 npm 原版 isolated-vm。

兼容 Node.js 版本：v26.3.1。

请选择：
1. 自动检测 / 安装 nvm，并安装切换 Node.js v26.3.1 后重新运行 xbs isolated-vm 自检。
2. 我手动安装 nvm；安装完成后回复“nvm 已安装成功”。
3. 我已经安装 nvm，但当前未检测到；我提供 nvm 路径或可用 shell。
4. 不安装兼容 Node，改为提供当前 Node ABI 匹配的魔改 isolated_vm.node 构建产物，或改选不使用框架 / vm / jsEnv。

在你确认前，我不会改用 npm 原版 isolated-vm，也不会桥接旧 addon.node。

nvm 安装与切换

只有用户明确选择自动安装时，才输出安装计划并执行。用户选择手动安装时，只给教程并等待用户确认成功。

Windows 推荐 nvm-windows：

winget install CoreyButler.NVMforWindows
# 或让用户从 nvm-windows 官方 Release 手动安装
nvm version

macOS / Linux 常用 nvm-sh：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
bash -lc 'source "$HOME/.nvm/nvm.sh" && nvm --version'

安装 / 检测 nvm 成功后按目标组件切换：

# addon.node
nvm install 25.8.2
nvm use 25.8.2
node -v
node -p "process.versions.modules"
node scripts/load_native_addon.js --json

# xbs isolated-vm
nvm install 26.3.1
nvm use 26.3.1
node -v
node -p "process.versions.modules"
node --no-node-snapshot scripts/check_xbs_isolated_vm.js --strict --json

记录要求

无论最终是否切换成功，都写入阶段报告、case/notes/代码变更记忆.md 和最终总结：

触发组件：addon.node / xbs isolated-vm。
原 Node 版本、原 ABI、平台、架构。
用户选择：自动安装、手动安装、提供 nvm 路径、拒绝安装、提供匹配二进制或改选框架。
新 Node 版本、新 ABI 和重新检测结果。
如果降级，写明 fallback 范围、已知差异和用户确认记录。

4.7 KiB Raw Permalink Blame History Unescape Escape