Ubuntu 下 Node.js 模块安装失败的常见原因与排查
一 可执行文件与路径问题
- Debian/Ubuntu 将 Node.js 可执行文件命名为 nodejs，部分脚本仍按“node”调用，导致“command not found: node”或安装脚本报错。现象常见于全局安装 CLI 工具时。修复方式：安装兼容包创建符号链接 /usr/bin/node → /usr/bin/nodejs，或手动建立软链；更推荐用 nvm 管理 Node，避免系统包冲突与权限问题。示例：sudo apt-get install nodejs-legacy；或 ln -s /usr/bin/nodejs /usr/bin/node；或 whereis nodejs 后 ln -s [路径] /usr/bin/node。使用 nvm 可避免 sudo 与路径错配。
二 权限与多版本冲突
- 直接使用系统包管理器全局安装，易出现权限不足与多版本并存引发的冲突。建议：用 nvm 安装与切换 Node 版本（避免 sudo 全局安装），必要时清理冲突版本与全局包路径。示例：nvm install 18；nvm use 18；npm config delete prefix 后再设置用户级全局目录。旧版 npm 与 Node 组合也更易出错，优先升级到受支持的 LTS 版本。
三 网络与镜像源问题
- 报错如“failed to fetch from registry”常见于网络不通、公司代理未配置、或使用了过时/不可达的镜像。处理：优先确保网络可达；如必须走代理，配置 npm 的 proxy 与 https-proxy；必要时临时切换或恢复官方仓库：npm config set registry https://registry.npmjs.org/；检查是否使用了过旧或已停更的仓库源。
四 原生模块编译依赖缺失
- 带 node-gyp 的本地扩展（如 gdal）需要编译工具链与系统库。典型错误包括：找不到 Python（node-gyp 调用失败）、缺少 build-essential/g++、或缺少 libgdal-dev 等依赖，亦可能遇到预编译二进制 404。处理：安装构建工具与依赖（sudo apt-get install build-essential g++ libgdal-dev；sudo apt install python-is-python3），必要时回退到与包兼容的 Node 版本（如 v16/v18）再安装。
五 快速排查清单
- 核对命令可用性：which node / which npm；若报“node: command not found”，按上文创建 /usr/bin/node → /usr/bin/nodejs 软链或使用 nvm。
- 查看 npm 配置：npm config list；如有公司网络，设置 proxy/https-proxy；必要时 npm config set registry https://registry.npmjs.org/。
- 统一版本与权限：用 nvm 安装并使用受支持的 LTS 版本；避免 sudo 全局安装，优先用户级安装。
- 准备编译环境：sudo apt-get update && sudo apt-get install -y build-essential g++ python-is-python3；涉及 GIS/数据库等原生库时同步安装对应 -dev 包（如 libgdal-dev）。
- 复现与定位：npm install -g -verbose 查看首条报错；针对报错关键词（如 Python、gyp、404、EACCES）对症下药。
