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

在Debian环境下运行Node.js应用，日志里突然冒出个错误，心里难免咯噔一下。其实，绝大多数错误都可以归结为几个常见类型，摸清它们的规律，解决起来并不复杂。下面这十种高频错误，基本覆盖了日常开发中会遇到的大部分情况。

先说第一个常见问题：端口冲突。错误信息通常是 Error: listen EADDRINUSE :::3000。这很好理解，程序想绑定的3000端口，已经被别的进程占用了，常见于多个应用打架，或者上次进程没正常退出。

解决办法很直接：先用 lsof -i :3000 找出是哪个进程占着端口，拿到它的PID，然后 kill -9 把它干掉。或者，干脆换个端口，比如把代码里的 app.listen(3000) 改成 const port = process.env.PORT || 3001; app.listen(port)，从根源上避免冲突。

再来看第二种情况，Error: Cannot find module ‘xxx’。这通常是因为依赖模块没装，或者 node_modules 目录被人误删了。解决方案也简单，在项目根目录下跑 npm install xxx 安装缺失的模块就行。如果依赖很多，建议直接执行 npm install，一次性把 package.json 里定义的所有依赖都装好，确保完整。

第三种是语法错误，SyntaxError: Unexpected token。代码里少了个括号、引号，或者拼写错误，导致Node.js解析不了。解决方法是查看错误日志里的堆栈跟踪，定位到具体行。用VSCode这类编辑器，语法检查功能会直接标红，把漏掉的符号补上就行，比如把 const x = { name: 'John' 补全为 const x = { name: 'John' };。

第四种，Error: Uncaught Exception。这是同步代码抛出的异常没被 try-catch 接住，或者异步操作里的错误没处理，直接导致应用崩溃。解决办法是为同步代码加上 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 包裹。

第五种，UnhandledPromiseRejectionWarning。Promise被拒绝了，但没通过 .catch() 或 async/await 的 try-catch 处理，这可能导致内存泄漏或奇怪的行为。解决办法很简单，给Promise加上 .catch()：someAsyncFunction().catch(err => console.error('Promise rejected:', err))。使用 async/await 时，用 try-catch 包裹异步代码。当然，也可以加一个全局的未处理拒绝处理器：process.on('unhandledRejection', (reason, promise) => { console.error('Unhandled rejection:', reason); })。

第六种，Error: ENOENT: no such file or directory。程序要访问的文件或目录不存在，比如配置文件路径错了，或者上传目录没创建，也可能是路径拼写错误。解决方法是检查错误日志里的文件路径，用 ls /path/to/file 确认一下是不是真的存在。建议用 path.join(__dirname, 'relative/path') 构建跨平台兼容的路径，别硬编码斜杠。如果目录不存在，就用 mkdir -p /path/to/directory 先创建好。

第七种，Error: Permission denied。权限不足。Node.js进程没有足够的权限去访问文件、目录，或者绑定端口（比如绑定1024以下的端口需要root权限）。注意，千万别用root去跑应用，sudo 存在安全隐患。正确做法是用普通用户运行，或者修改文件/目录权限，比如 chmod +x script.js 赋予执行权限，chmod -R 755 logs/ 赋予日志目录写入权限。如果是因为端口问题，直接改成3000以上的端口即可。

第八种，Node.js版本兼容性问题。应用依赖的模块或代码需要特定版本的Node.js，比如旧模块不支持Node.js 18+。先通过 node -v 检查当前版本，看是否符合要求。如果不符合，可以用 n 或 nvm 切换版本，比如 sudo apt install n 安装 n 后，用 sudo n 16 切换到Node.js 16。或者，更新一下应用依赖，npm update 确保模块支持当前版本。

第九种，Error: Memory Limit Exceeded / Ja vaScript 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 工具。优化代码也很关键，比如分块处理大文件、避免全局变量、及时释放资源。

最后一种，流未处理的异常。流操作（文件流、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') 作为最后防线，也能避免未处理的流错误导致进程退出。