怎样解读nodejs错误日志

解读 Node.js 错误日志，核心目标是：定位“在哪里出错、为什么出错、如何复现和修复”。下面从「日志结构 → 常见错误类型 → 解读方法 → 实战示例 → 排查工具」系统讲一下。

一、Node.js 错误日志通常长什么样

一个典型的 Node.js 错误日志示例：

TypeError: Cannot read properties of undefined (reading 'name')
    at getUser (/app/user.js:12:15)
    at processTicksAndRejections (node:internal/process/task_queues:95:5)

关键信息：

1. 错误类型：TypeError
2. 错误信息：Cannot read properties of undefined
3. 调用栈（stack）：
   • 出错函数：getUser
   • 文件与行号：/app/user.js:12:15
4. 异步上下文（如果是 Promise / async）

二、常见 Node.js 错误类型及含义

1. SyntaxError（语法错误）

SyntaxError: Unexpected token 'export'

• 原因：ESM / CommonJS 混用、Node 版本不支持
• 解读重点：编译阶段就失败，不会运行代码

2. ReferenceError（引用错误）

ReferenceError: req is not defined

• 变量未声明或被作用域隔离
• 常见于回调、async 函数

3. TypeError（类型错误，最常见）

TypeError: user.getName is not a function

• 对象不是你以为的类型
• 常见于：
  • 接口返回 null
  • 异步未 await
  • 第三方库版本变化

4. RangeError

RangeError: Maximum call stack size exceeded

• 死循环 / 递归
• JSON 循环引用

5. UnhandledPromiseRejectionWarning

UnhandledPromiseRejectionWarning: Error: DB connection failed

• Promise 没有被 catch
• Node 15+ 会直接崩溃

6. ERR_*（Node 内部错误）

Error: listen EADDRINUSE: address already in use :::3000

• 端口占用
• 文件权限
• 模块找不到（ERR_MODULE_NOT_FOUND）

三、如何“正确解读”错误日志（方法论）

✅ 第一步：先看错误类型

✅ 第二步：看“最上面一行 stack”

不是最下面，是最上面你写的代码

at getUser (/app/user.js:12:15)  ← 看这里

Node 内部代码可以忽略：

at processTicksAndRejections

✅ 第三步：结合上下文推断原因

例如：

const name = user.profile.name;

报错：

Cannot read properties of undefined (reading 'profile')

→ user 存在，但 profile 是 undefined

✅ 第四步：判断是同步还是异步错误

• 同步错误：直接 stack
• 异步错误：看 Promise / async

UnhandledPromiseRejection

说明：

• 没有 try/catch
• 没有 .catch()

四、实战示例解读

示例 1：接口 500 错误

TypeError: Cannot read properties of undefined (reading 'id')
    at getUserById (/service/user.js:20:22)

解读：

• req.params 或数据库返回为 undefined
• 修复：

if (!user) throw new Error('User not found');

示例 2：服务启动失败

Error: listen EADDRINUSE: address already in use :::3000

解读：

• 端口被占用
• 解决：

lsof -i:3000
kill -9 <pid>

示例 3：Promise 崩溃

UnhandledPromiseRejectionWarning: Error: timeout

修复：

async function main() {
  try {
    await fetchData();
  } catch (e) {
    logger.error(e);
  }
}

五、提升日志可读性的做法（很重要）

1. 使用结构化日志

logger.error({
  event: 'user_query_failed',
  userId,
  error: err.message
});

2. 保留 stack

console.error(err.stack);

3. 全局捕获

process.on('unhandledRejection', e => {
  console.error('Unhandled:', e);
});

六、常用排查工具

七、一句话总结

Node.js 错误日志 = 错误类型 + 最上层业务 stack + 上下文数据

如果你愿意，可以把具体的错误日志贴出来，我可以直接帮你“逐行解读 + 给出修复方案”。