基于VSCode的Node项目借助Sentry-SDK达成全天候运行异常主动抛出调试

Node.js服务端异常需主动上报Sentry：必须在入口文件先调用Sentry.init()，再监听process.on('uncaughtException')和process.on('unhandledRejection')事件并调用Sentry.captureException()，避免静默崩溃。

Node.js 服务端异常怎么主动上报到 Sentry

默认情况下，Node.js 进程不会把未捕获的异常（uncaughtException）或 Promise 拒绝（unhandledRejection）自动发给 Sentry。必须手动 hook 这两类事件，否则错误就静默崩溃了。

• 在 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，直接 return null
• 对 event.user 做脱敏：删除 ip_address 字段，或替换为哈希值，避免违反 GDPR
• 别在 beforeSend 里调用 console.log —— 某些日志驱动会递归触发异常，形成死循环上报

本地开发时如何验证上报链路通不通

光看控制台没报错不等于 Sentry 收到了。最可靠的方式是触发一次真实异常，然后立刻去 Sentry 控制台搜 event.timestamp 的分钟级时间范围。

• 在路由 handler 里写一行：throw new Error('test-sentry-local-' + Date.now())
• 访问对应接口，等 5–10 秒，刷新 Sentry 的 Issues 页面，按时间倒序找最新一条
• 如果找不到，检查 SENTRY_DSN 是否用了前端 DSN（以 https:// 开头）—— Node 必须用后端 DSN（含 :<secret>@</secret> 结构）
• 终端执行 curl -v http://localhost:3000/xxx 触发异常，同时用 tail -f logs/sentry-debug.log（如果启用了 debug: true）确认 SDK 是否发出 POST 请求

实际部署后，unhandledRejection 比 uncaughtException 更容易漏——尤其在 async/await 链中忘记 try/catch 或没 .catch()，这种错误不会终止进程，但也不会触发任何日志，除非你显式监听。