129 lines
4.7 KiB
Markdown
129 lines
4.7 KiB
Markdown
# 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
|
||
|
||
```bash
|
||
node scripts/check_node_runtime_compat.js --target addon --markdown
|
||
node scripts/check_node_runtime_compat.js --target isolated-vm --markdown
|
||
```
|
||
|
||
也可以手动检测：
|
||
|
||
```bash
|
||
node -v
|
||
node -p "process.versions.modules"
|
||
```
|
||
|
||
Windows：
|
||
|
||
```powershell
|
||
where.exe nvm
|
||
nvm version
|
||
nvm root
|
||
```
|
||
|
||
macOS / Linux：
|
||
|
||
```bash
|
||
bash -lc 'command -v nvm || true; [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh" && nvm --version || true'
|
||
```
|
||
|
||
## 用户确认模板
|
||
|
||
### addon ABI 不兼容
|
||
|
||
```markdown
|
||
当前 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 不兼容
|
||
|
||
```markdown
|
||
当前随包魔改 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：
|
||
|
||
```powershell
|
||
winget install CoreyButler.NVMforWindows
|
||
# 或让用户从 nvm-windows 官方 Release 手动安装
|
||
nvm version
|
||
```
|
||
|
||
macOS / Linux 常用 nvm-sh：
|
||
|
||
```bash
|
||
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
|
||
bash -lc 'source "$HOME/.nvm/nvm.sh" && nvm --version'
|
||
```
|
||
|
||
安装 / 检测 nvm 成功后按目标组件切换：
|
||
|
||
```bash
|
||
# 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 范围、已知差异和用户确认记录。
|