必须用arm64原生node，x86_64版本会触发rosetta转译，导致npm install失败、native模块编译报错、调试器连接超时；需实测node -p process.arch输出"arm64"且file $(which node)含arm64字样，vscode终端也须一致，并确保python、clang等全链路工具均为arm64架构。
必须用 ARM64 原生 Node，x86_64 版本在 M 系列芯片上会触发 Rosetta 转译，导致 npm install 失败、native 模块（如 sqlite3、sharp）编译报错、调试器连接超时。
确认当前 Node 是否为 arm64 架构
别信安装包名称或官网下载记录，得实测：
- 终端执行
node -p process.arch，输出必须是"arm64" - 执行
file $(which node)，输出里必须含arm64字样（不是x86_64） - 在 VSCode 集成终端里运行同一命令——如果结果是
"x64"，说明终端没加载正确 Shell 环境
安装 ARM64 原生 Node（推荐 nvm + arm64 二进制）
Homebrew 安装的 Node 有时会混入 x86_64 依赖，尤其当你之前装过 Intel 版 Homebrew。稳妥做法是用 nvm 管理，并指定 ARM64 构建：
- 先卸载旧版：
brew uninstall node（如果存在） - 安装 ARM64 原生
nvm：curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash，然后确保~/.nvm路径写入~/.zprofile（不是.zshrc），因为 GUI 应用读取的是前者 - 安装 arm64 Node：
nvm install --lts（v20.x 或 v22.x LTS 默认提供 arm64 二进制） - 验证：
nvm use --lts && node -p process.arch→ 应输出"arm64"
VSCode 集成终端 PATH 不生效的典型表现与修复
你在 Terminal 里能跑 node，但在 VSCode 里提示 command not found，本质是 GUI 进程没加载你的 Shell 初始化脚本：
- 打开 VSCode 终端，运行
echo $PATH，对比系统终端输出 —— 如果缺失/opt/homebrew/bin或~/.nvm/versions/node，就是路径没传进来 - 编辑
~/.zprofile（不是.zshrc），添加：export NVM_DIR="$HOME/.nvm"和[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" - 重启 VSCode（不是 Reload Window），再开终端验证
which node是否指向~/.nvm/versions/node/...
npm install native 模块失败时的常见坑
即使 Node 是 arm64，npm install 仍可能因构建工具链错位而失败：
- 检查
which python3：必须是 ARM64 版本（比如通过pyenv安装的 3.11+，或 Homebrew 在/opt/homebrew/bin/python3） - 确认
clang架构：clang --version输出应含arm64-apple-darwin；若显示x86_64-apple-darwin，需重装 Xcode Command Line Tools（xcode-select --install） - 某些模块（如
sqlite3）需显式指定架构：npm install sqlite3 --build-from-source --sqlite3_build_type=source - VSCode 的 JavaScript Debugger 扩展若报 “Cannot find module ‘node:fs’”，大概率是 Node 版本太新（v22+）且调试器未同步更新，降级到 v20.x LTS 更稳
真正卡住的地方往往不是 Node 本身，而是它调用的 Python、Clang、make 这些底层工具是否全链路 arm64 —— 少一个，就可能让 npm install 在 binding.gyp 阶段静默失败。
