Debian Node.js日志中常见错误及解决方案

1. 端口冲突（Error: listen EADDRINUSE :::3000）
原因：应用程序尝试绑定的端口（如3000）已被其他进程占用，常见于多应用共存或进程未正常关闭的场景。
解决方法：

• 使用lsof -i :3000命令查找占用端口的进程ID（PID），再用kill -9 <PID>终止该进程；
• 修改应用程序的端口号（如将app.listen(3000)改为const port = process.env.PORT || 3001; app.listen(port)），避免端口冲突。

2. 依赖模块未找到（Error: Cannot find module ‘xxx’）
原因：项目依赖的模块未安装（如首次运行未执行npm install），或node_modules目录被误删除。
解决方法：

• 在项目根目录下运行npm install xxx安装缺失的模块；
• 若依赖较多，建议运行npm install安装package.json中定义的所有依赖，确保依赖完整性。

3. 语法错误（SyntaxError: Unexpected token）
原因：代码中存在语法错误（如缺少括号、引号、拼写错误），导致Node.js无法解析代码。
解决方法：

• 查看错误日志中的堆栈跟踪（Stack Trace），定位到具体代码行；
• 使用文本编辑器（如VSCode）的语法检查功能，修复拼写或符号错误（如将const x = { name: 'John'补全为const x = { name: 'John' };）。

4. 未捕获的异常（Error: Uncaught Exception）
原因：同步代码中抛出的异常未被try-catch捕获，或异步操作（如Promise、回调函数）中的错误未被处理，导致应用程序崩溃。
解决方法：

• 为同步代码添加try-catch块（如try { riskyOperation(); } catch (err) { console.error('Caught error:', err); }）；
• 添加全局异常处理器，捕获未处理的异常并优雅退出（如process.on('uncaughtException', (err) => { console.error('Uncaught exception:', err); process.exit(1); })）；
• 处理异步操作的错误（如Promise的.catch()或async/await的try-catch）。

5. 未处理的Promise拒绝（UnhandledPromiseRejectionWarning）
原因：Promise被拒绝（如reject()或抛出错误），但未通过.catch()或async/await的try-catch处理，可能导致内存泄漏或意外行为。
解决方法：

• 为Promise添加.catch()（如someAsyncFunction().catch(err => console.error('Promise rejected:', err))）；
• 使用async/await时，用try-catch包裹异步代码（如async function run() { try { await someAsyncFunction(); } catch (err) { console.error('Error:', err); } }）；
• 添加全局未处理拒绝处理器（如process.on('unhandledRejection', (reason, promise) => { console.error('Unhandled rejection:', reason); })）。

6. 文件或目录不存在（Error: ENOENT: no such file or directory）
原因：应用程序尝试访问的文件或目录不存在（如配置文件路径错误、上传目录未创建），或路径拼写错误。
解决方法：

• 检查错误日志中的文件路径，确认路径是否存在（如使用ls /path/to/file）；
• 使用path.join(__dirname, 'relative/path')构建跨平台兼容的路径（避免硬编码/或\）；
• 若目录不存在，使用mkdir -p /path/to/directory创建目录（如上传目录）。

7. 权限不足（Error: Permission denied）
原因：Node.js进程没有足够的权限访问文件、目录或端口（如绑定1024以下端口需要root权限，或日志目录无写入权限）。
解决方法：

• 避免使用root运行应用（使用sudo可能导致安全问题），改为用普通用户运行；
• 修改文件/目录权限（如chmod +x script.js赋予执行权限，chmod -R 755 logs/赋予日志目录写入权限）；
• 更改端口（如将端口改为3000以上，避免需要root权限）。

8. Node.js版本兼容性问题
原因：应用程序依赖的模块或代码需要特定版本的Node.js（如旧模块不支持Node.js 18+），导致运行错误。
解决方法：

• 使用node -v检查当前Node.js版本，确认是否符合应用要求；
• 使用n或nvm（Node Version Manager）切换版本（如sudo apt install n，然后sudo n 16切换到Node.js 16）；
• 更新应用依赖（如npm update），确保模块支持当前Node.js版本。

9. 内存溢出（Error: Memory Limit Exceeded / JavaScript heap out of memory）
原因：应用程序消耗过多内存（如处理大文件、内存泄漏），超过Node.js默认的1.4GB内存限制（64位系统）。
解决方法：

• 使用--max-old-space-size标志增加内存限制（如node --max-old-space-size=4096 app.js将内存限制提升至4GB）；
• 分析内存使用情况（如使用node --inspect配合Chrome DevTools，或clinic.js工具），找出内存泄漏点（如未释放的缓存、无限循环）；
• 优化代码（如分块处理大文件、避免全局变量、及时释放资源）。

10. 流未处理的异常（Stream Unhandled Error）
原因：流（如文件流、HTTP请求流、Socket流）操作中发生错误（如文件读取失败、网络中断），未附加错误处理程序导致进程崩溃。
解决方法：

• 为流对象附加error事件处理程序（如const stream = fs.createReadStream('file.txt'); stream.on('error', (err) => { console.error('Stream error:', err); })）；
• 使用try-catch包裹同步流操作（如fs.readFileSync），捕获可能的错误；
• 避免未处理的流错误导致进程退出（如监听process.on('uncaughtException')作为最后防线）。