VSCode Node项目集成Sentry SDK实现异常主动抛出调试

Node.js 服务端一旦发生异常，若未能自动上报至 Sentry，则监控形同虚设。常见陷阱是进程静默崩溃，导致问题根源无从知晓。解决方案其实非常明确：在入口文件中执行两项关键操作——首先初始化 Sentry，随后手动捕获全局异常事件。 具体而言，在 `main.js` 或应用入口文件顶部，首先调用 `Sentry.init()`，紧接着监听 `process.on('uncaughtException')` 与 `process.on('unhandledRejection')` 两个事件。在回调函数中，通过 `Sentry.captureException()` 捕获错误，并调用 `process.exit(1)` 使进程优雅退出。针对 `unhandledRejection`，务必对 `reason` 参数进行判空处理，防止传入 `undefined` 导致 SDK 自身报错。 这里有一个容易被忽视的细节：切勿在监听器中执行异步操作，例如写入文件或发送 HTTP 请求。尽管 `Sentry.captureException` 是同步触发，但 flush 等待过程可能被进程退出打断。推荐在 `beforeSend` 回调中执行轻量级过滤，将上报逻辑交由 SDK 自身调度。

Node.js 服务端异常如何主动上报至 Sentry

默认情况下，Node.js 进程不会将未捕获异常（`uncaughtException`）或 Promise 拒绝（`unhandledRejection`）自动发送至 Sentry。必须手动挂钩这两类事件，否则错误将静默崩溃。 - 在 `main.js` 或应用入口文件顶部，依次调用 `Sentry.init()` 并注册全局监听器。 - 务必监听 `process.on('uncaughtException')`，在回调中调用 `Sentry.captureException()`，随后执行 `process.exit(1)`。 - 同样监听 `process.on('unhandledRejection')`，对 `reason` 进行判空处理后上报，避免传入 `undefined` 导致 SDK 异常。 - 避免在监听器中执行异步操作（如写文件、HTTP 请求），Sentry 的 `captureException` 虽为同步触发，但 flush 等待可能被进程退出打断；建议在 `beforeSend` 中做轻量过滤，将上报逻辑交由 SDK 调度。

VSCode 调试时 Sentry 为何收不到错误

VSCode 默认调试模式会拦截并“吞掉”首次抛出的异常，导致 Sentry 的 `uncaughtException` 监听器无法接收到事件。这并非 Sentry 配置问题，而是调试器的行为特性。 - 打开 VSCode 的「运行和调试」侧边栏，点击右上角齿轮图标，编辑 `launch.json`。 - 在配置中添加 `"console": "integratedTerminal"`，以避免调试器独占异常流。 - 关键设置项：`"internalConsoleOptions": "neverOpen"`，防止调试控制台抢走错误上下文。 - 若仍无效，可临时在 `launch.json` 中添加 `"stopOnEntry": false` 和 `"trace": true`，以检查是否被断点中断了异常传播路径。

beforeSend 中可进行的实用过滤操作

Node 环境下噪音虽比浏览器少，但仍有几类异常必须拦截：Express 默认的 404 响应、健康检查探针失败、已知第三方库的伪异常（例如 `dns.lookup` 超时被包装成 `Error`）。 - 检查 `event.exception.values[0].type` 是否为 `'Error'` 且消息包含 `'ENOTFOUND'` 或 `'ECONNREFUSED'`，这类网络错误可降级为 warning 上报，或直接丢弃。 - 若 `event.request?.url` 匹配 `/health` 或 `/metrics`，直接返回 null。 - 对 `event.user` 进行脱敏：删除 `ip_address` 字段，或替换为哈希值，以避免违反 GDPR。 - 切勿在 `beforeSend` 中调用 `console.log` —— 某些日志驱动会递归触发异常，形成死循环上报。

本地开发时如何验证上报链路是否畅通

仅凭控制台无报错并不能保证 Sentry 已收到异常。最可靠的方式是主动触发一次真实异常，随后立即前往 Sentry 控制台，根据 `event.timestamp` 的分钟级时间范围进行搜索。 - 在路由处理器中写入一行：`throw new Error('test-sentry-local-' + Date.now())`。 - 访问对应接口，等待 5–10 秒，刷新 Sentry 的 Issues 页面，按时间倒序查找最新一条记录。 - 若找不到，请检查 `SENTRY_DSN` 是否误用了前端 DSN（以 `https://` 开头）—— Node 必须使用后端 DSN（包含 `:@` 结构）。 - 在终端执行 `curl -v http://localhost:3000/xxx` 触发异常，同时使用 `tail -f logs/sentry-debug.log`（若已启用 `debug: true`）确认 SDK 是否发出了 POST 请求。 实际部署后，`unhandledRejection` 比 `uncaughtException` 更容易遗漏——尤其是在 async/await 链中忘记使用 `try/catch` 或未添加 `.catch()`，这类错误不会终止进程，也不会触发任何日志，除非你显式监听。