Debian 环境下 JS 日志常见错误代码与含义
一 标准 JavaScript 运行时错误类型
- SyntaxError：语法错误，如缺少括号、引号、分号或花括号不匹配，常见于构建产物或动态拼接的脚本。
- ReferenceError：引用未声明变量，如访问了尚未定义的变量或作用域外的标识符。
- TypeError：对值执行了不适配类型的操作，如读取 undefined/null 的属性、把非函数当函数调用。
- RangeError：数值或参数超出允许范围，如创建长度为负数的数组、递归过深导致栈溢出。
- URIError：encodeURI / decodeURI 等处理非法 URI 时抛出。
- EvalError：与 eval 使用不当相关，现代环境已较少见。
这些错误类型在 Debian 上的 Node.js 或前端运行环境中含义一致，通常伴随文件名、行号与列号，便于定位。
二 Node.js 常见错误场景与含义
- 未处理的异常（Unhandled Exception）：异步回调或事件中的错误未被捕获，可能导致进程崩溃。
- 未处理的 Promise 拒绝（Unhandled Rejection）：Promise 被 reject 但未通过 .catch() 或 try/catch 处理。
- JavaScript 堆内存不足（JavaScript heap out of memory）：处理大数据或内存泄漏时触发，需要优化算法或增大内存上限。
- 流未附加错误处理器（Stream unhandled error）：读写流在出错时未监听 error 事件，错误会冒泡并可能终止进程。
- 网络与通信错误：如 ECONNRESET、ETIMEDOUT、ENOTFOUND 等，常见于 HTTP 请求、数据库连接或微服务调用。
- 环境/版本不兼容：依赖包与 Node.js 版本不匹配，或原生模块编译失败。
以上场景在 Debian 服务器上运行 Node.js 应用时非常典型，应结合堆栈与错误码一并排查。
三 业务系统自定义错误码说明
- 许多后端或网关会在日志中输出自定义业务错误码（如：xnaa0201x005、xcca02010004、xnca0201x056 等），其语义由具体系统统一定义，并非 JavaScript 或 Node.js 标准。
- 解读步骤：
- 在项目中查找错误码定义（如 errors/ 目录、错误码枚举、API 文档）；
- 在日志平台或网关（如 Nginx Ingress、API Gateway）检索该错误码的映射说明；
- 若仍无定义，联系对应系统负责人或查阅发布记录/变更单。
这类错误码在不同业务线可能完全不同，需以系统文档为准。
四 在 Debian 上快速定位与修复
- 定位日志
- 系统/服务日志：使用 journalctl 或查看 /var/log/（如 syslog、nginx/error.log、app.log）。
- 容器内日志：使用 docker logs <容器名> 或 kubectl logs 。
- 关键字检索：例如 grep -n ‘SyntaxError|TypeError’ /var/log/syslog 或 journalctl -u your-node-app | grep ‘heap out of memory’。
- 修复要点
- 语法/引用/类型错误：依据报错的文件与行列号修正代码，必要时在访问对象前做 null/undefined 判断。
- 异步与 Promise：为所有异步操作添加 try/catch 或 .catch()，并在顶层监听 process.on(‘unhandledRejection’)。
- 流处理：为每个 Readable/Writable/Duplex 显式监听 error 事件。
- 内存问题：排查泄漏（如全局缓存、闭包引用）、分批处理大数据、必要时通过 –max-old-space-size 调整堆上限。
- 生效变更：代码修复后重启服务，例如 sudo systemctl restart your-app。
以上流程可快速从日志定位到根因并恢复服务稳定性。
