CentOS 上配置 Node.js 的常见错误与排查要点
一 环境与路径配置
- 使用 export 临时设置的环境变量只在当前终端有效，重启或新开会话后丢失；应写入持久化文件（如 ~/.bashrc、~/.bash_profile 或 /etc/profile），并执行 source 使其生效。
- 未将 Node.js 的 bin 目录加入 PATH，导致执行 node/npm 提示“command not found”；排查用 which node、echo $PATH，修复示例：在 ~/.bashrc 中添加 export PATH=$PATH:/usr/local/nodejs/bin。
- 多版本共存导致调用混乱；建议使用 nvm 安装与切换版本，例如：安装 nvm 后执行 nvm install 18、nvm use 18。
- 通过 yum 安装时未启用 EPEL 源导致找不到包；可先执行 sudo yum install epel-release，若失败可重建 rpm 数据库后再安装。
- 使用 yum 安装的 Node.js 版本过旧（如 v6.17.1），运行现代工具（如 PM2）会报语法错误；应升级 Node（如用 n 或 nvm）。
二 权限与全局安装
- 全局安装模块出现 EACCES 或“权限不足”，多因当前用户对全局目录无写权限；推荐做法是更改 npm 全局目录到用户目录：
- 创建目录：mkdir ~/.npm-global
- 配置前缀：npm config set prefix ‘~/.npm-global’
- 加入 PATH：export PATH=~/.npm-global/bin:$PATH（写入 ~/.bashrc 持久化）
- 不建议直接用 sudo npm install -g；若必须提权，应谨慎评估安全风险。
- 项目本地依赖因目录权限不当导致 EACCES（如无法创建/写入 node_modules 或缓存）；应修正项目目录属主与权限，避免使用 root 长期运行应用。
- 某些原生模块（如 node-sass）安装阶段需要写二进制文件，可能因权限被拒；可在可控范围内使用 npm 的 --unsafe-perm 选项，或优先选择无需编译的替代包。
三 端口与系统限制
- 监听 80/443 等特权端口出现 EACCES；应避免以 root 直接运行应用，推荐采用反向代理（如 Nginx）或 setcap 授权：
- 示例：sudo setcap ‘cap_net_bind_service=+ep’ $(which node)（赋予 Node 绑定低端口的能力）
- 端口被占用报 EADDRINUSE；排查占用进程并释放端口，或调整应用端口。
- 文件/目录监控触发 ENOSPC（inotify 实例或监视数达上限）；提升内核参数：
- 编辑 /etc/sysctl.conf：fs.inotify.max_user_watches=524288
- 使生效：sudo sysctl -p
- 依赖服务未启动或网络策略阻断导致 ECONNREFUSED/超时；检查目标服务状态、地址与防火墙策略。
四 版本兼容与依赖管理
- 运行依赖新语法的代码时报 SyntaxError: Unexpected identifier，多为 Node.js 版本过低；使用 nvm 升级到合适版本。
- 本地或 CI 环境报 “No acceptable C compiler found!” 等编译错误；安装编译工具链：sudo yum install gcc，必要时启用 devtoolset。
- 二进制依赖与系统 glibc 版本不匹配（如报错含 glibc_2.27 not found）；选择兼容的 Node.js 版本或升级系统库（升级 glibc 需谨慎）。
- 网络慢或无法访问官方仓库导致 npm install 失败；配置 npm registry 为国内镜像（如 https://registry.npm.taobao.org）。
五 快速排查清单
- 基础可用性：node -v、npm -v、which node、echo $PATH 是否符合预期。
- 全局命令可用性：执行 npm root -g 检查全局模块目录是否在 PATH 中。
- 端口与进程：netstat -tulpen | grep <端口> 或 ss -ltnp | grep <端口> 检查占用；必要时释放或更换端口。
- 权限与目录：项目与 node_modules 目录属主/权限是否正确，避免以 root 运行。
- 依赖安装：清理缓存 npm cache clean --force，必要时使用镜像源或离线包。
- 日志与堆栈：查看应用与 PM2 日志，依据错误码（如 EACCES/EADDRINUSE/ECONNREFUSED）定位问题。