Debian 环境下 JavaScript 日志常见错误与排查要点
一 常见错误类型与含义
- SyntaxError：语法错误，如缺少括号、引号、分号或花括号不匹配，导致脚本无法解析。
- ReferenceError：引用未声明变量，如访问了尚未定义的标识符。
- TypeError：对不符合预期类型的值进行操作，如读取 undefined/null 的属性。
- RangeError：数值或数据结构超出允许范围，如创建长度为负数的数组、递归过深。
- URIError：使用 encodeURI/encodeURIComponent/decodeURI/decodeURIComponent 处理非法 URI。
- EvalError：与 eval 使用不当相关，现代环境已较少见。
- Node.js 运行时特有：未处理的异常、流未监听 error 事件、堆内存不足（内存泄漏或大数据处理）、环境/版本不兼容、网络请求失败或超时等。
二 典型触发场景与修复建议
- SyntaxError：常见于构建产物包含语法错误、依赖包损坏或部署了未通过转译的 ESM 代码；建议本地/CI 先执行 node -c 或测试脚本校验语法，确保依赖版本一致并清理构建缓存。
- ReferenceError：变量未声明或作用域不可达；建议使用 let/const 并启用 “use strict”，在访问前做存在性检查。
- TypeError：对 undefined/null 取属性或调用方法；建议增加空值保护（可选链 ?.、默认值、类型守卫）。
- RangeError：递归缺少终止条件或数据规模超限；建议改为迭代、增加深度限制或分批处理。
- URIError：对非法字符进行编码/解码；建议先校验或转义输入。
- Node.js 运行时：
- 未处理的异常或流错误导致崩溃；建议为 process 添加 uncaughtException/ unhandledRejection 监听，并为所有 Stream 显式监听 error 事件。
- 堆内存不足；建议用 –max-old-space-size 调整上限，配合内存分析定位泄漏，优化大对象生命周期与批量处理。
- 环境/版本不兼容；建议固定 Node 与依赖版本，使用 nvm 或容器镜像确保一致性。
- 网络错误；建议设置超时、重试与熔断策略，并记录失败上下文以便排查。
三 快速定位与日志查看
- 定位日志位置：系统与应用日志多在 /var/log/；前端错误常写入 Nginx/Apache 错误日志（如 /var/log/nginx/error.log、/var/log/apache2/error.log），Node.js 应用可能写入自定义目录或使用 journalctl -u <service_name> 查看服务日志。
- 检索与跟踪：用 grep 搜索关键字（如 SyntaxError/ReferenceError/TypeError），用 tail -f 实时跟踪新日志，结合时间戳与堆栈定位上下文。
- 结构化分析：若日志为 JSON，使用 jq 解析字段；对海量日志可引入 ELK Stack（Elasticsearch/Logstash/Kibana） 或 Splunk 做聚合与可视化。
- 前端调试：使用 Chrome DevTools 的 Console/Sources 定位错误与源码映射（source map）。
四 预防与监控
- 在 CI/CD 中加入语法与单元测试，禁止未通过校验的构建与部署。
- 统一 Node 与依赖版本，使用 npm/yarn/pnpm 的 lockfile，并在容器/PM2 等运行环境中固定版本。
- 为异步与流操作添加完备的错误处理，记录关键上下文（请求 ID、用户、输入摘要）。
- 配置监控与告警：用 Prometheus/Grafana 监控进程存活、内存与错误率，异常时及时通知。