Ubuntu 上 Node.js 出错的快速排查与修复
一 快速定位与通用修复
- 确认环境：运行 node -v、npm -v 检查是否已安装及版本；若未安装，先执行 sudo apt update && sudo apt install nodejs npm。
- 读懂报错：先看终端/日志的首个报错行，定位到具体的文件、行号与模块。
- 安装依赖：在项目根目录执行 npm install；若曾失败，先清理并重装：
- npm cache clean --force
- rm -rf node_modules package-lock.json
- 再 npm install
- 端口冲突：确认应用端口未被占用，例如端口 3000：
- 查占用：sudo lsof -i :3000
- 结束进程：kill -9
- 版本与兼容：旧版本可能与新依赖不兼容，建议用 nvm 安装/切换到 LTS 版本。
- 调试手段：使用 node inspect your_script.js 或 node --inspect app.js 进行断点调试；配合 console.log/console.error 输出关键变量。
- 查看日志：
- 原生/系统服务：journalctl -u your-node-service -f
- 文件日志：tail -f logs/app.log
- PM2：pm2 logs your-app
- 安全与更新：及时更新 Node.js/npm 与相关依赖，修复已知漏洞。
二 常见错误对照与处理
| 错误信息 |
含义 |
快速处理 |
| Error: listen EADDRINUSE: address already in use :::3000 |
端口被占用 |
sudo lsof -i :3000 查 PID；kill -9 ；或换端口 |
| Error: Cannot find module ‘xxx’ |
模块未安装/路径错误 |
npm install xxx；核对 require/import 拼写与相对路径 |
| Error: EACCES, permission denied |
权限不足 |
检查目录/文件权限；避免用 sudo 运行应用；必要时调整日志目录权限 |
| Error: EADDRNOTAVAIL |
绑定 IP 不可用 |
使用本机有效 IP（如 127.0.0.1 或服务器内网 IP），检查网络配置 |
| Error: ETIMEDOUT |
连接远程超时 |
检查网络连通性、目标服务状态；适当增加超时配置 |
| Error: ENOENT: no such file or directory |
文件/目录不存在 |
核对路径、工作目录；确认资源文件已部署 |
| Error: write EIO / 中文乱码 |
终端/文件系统编码问题 |
将源文件保存为 UTF-8 再运行 |
| DeprecationWarning / UnhandledPromiseRejectionWarning / MaxListenersExceededWarning |
过时 API / 未处理 Promise / 监听器泄漏 |
升级依赖与 Node；为 Promise 加 .catch()/try-catch；临时监听 process.on(‘unhandledRejection’)；排查事件监听重复添加 |
三 安装与环境问题
- 安装源过旧：系统 apt 仓库的 Node.js 可能不是最新 LTS，可用 NodeSource PPA 或 nvm 安装/管理版本。
- nvm 未找到：安装后若提示 nvm: command not found，将环境变量加入 ~/.bashrc 或 ~/.zshrc，并执行 source ~/.bashrc（或 source ~/.zshrc）刷新。
- 网络拉取失败：安装脚本访问 raw.githubusercontent.com 失败时，可临时在 /etc/hosts 添加解析记录以绕过 DNS 问题。
四 运行与进程管理
- PM2 无法停止进程：执行 pm2 stop 后进程仍在，先用 ps aux | grep node 确认进程，再 kill -9 ；必要时 pm2 delete 清理残留。
- 日志与告警：
- 实时查看：pm2 logs your-app；筛选告警：pm2 logs your-app --lines 50 | grep WARN
- 未处理 Promise：添加全局监听
- process.on(‘unhandledRejection’, (reason) => console.error(‘Unhandled:’, reason))
- 监听器泄漏：检查重复 on(‘event’)，必要时调用 emitter.setMaxListeners(0) 或优化逻辑。
五 高效求助与提交信息
- 提供关键要素：
- Node.js 版本、npm 版本、操作系统版本
- 复现步骤、完整错误堆栈、相关 代码片段
- 已尝试的方案与结果
- 附上运行方式：直接运行 node app.js 还是 pm2/系统服务；如是服务，附 systemd 单元或 PM2 配置。
- 提供精简复现仓库（如 GitHub 最小示例），便于快速定位。