自动记录异常日志的异步工具库需统一拦截全局未处理异常、提供带上下文捕获的wrapAsync包装器、异步容错写入、结构化JSON日志及动态上下文注入能力。
要编写能自动记录异常日志的异步工具库，核心是把异常捕获、上下文提取、日志格式化和异步写入这几个环节封装成可复用、不侵入业务逻辑的机制。关键不在“记录”，而在“自动”——即无需每个 await 处手动 try-catch，也能兜住未处理的 Promise 拒绝和未捕获异常。
统一拦截未处理的异步异常
Node.js 和现代浏览器都支持监听全局异步拒绝事件。这是实现“自动”的起点：
- 在 Node.js 中监听 unhandledRejection 和 uncaughtException 事件，捕获未 await 或未 catch 的 Promise 拒绝和同步异常
- 在浏览器中监听 window.onunhandledrejection 和 window.onerror，注意 onerror 无法捕获 Promise 拒绝，必须配合 unhandledrejection
- 拦截后不要直接 console.error，而是调用你库内部的标准化日志函数，确保带上时间、环境、堆栈、请求 ID（如有）等字段
提供带错误捕获能力的异步包装器
光靠全局监听不够：它无法关联业务上下文（比如哪个 API 调用失败、用户 ID 是什么）。你需要提供轻量级包装工具，让开发者一键增强函数：
- 导出一个 wrapAsync 工具函数，接收 async 函数和可选配置（如日志级别、额外字段、是否重抛）
- 内部自动 try/catch，捕获异常后合并执行上下文（如函数名、参数摘要、traceId），再交由日志管道处理
- 示例：const getUser = wrapAsync(async (id) => { ... }, { tag: 'user-service' })，调用时出错即自动记录，无需额外写 catch
异步日志写入不阻塞主流程
日志本身不能拖慢业务。所有日志操作必须真正异步且有容错：
- 使用 fs.promises.appendFile（Node）或 console.log + 后台上报（浏览器），避免同步 I/O
- 为防止日志写入失败导致异常丢失，加一层内存缓冲（如队列）+ 降级策略（失败时 fallback 到 console 或内存快照）
- 支持可选的批量提交与定时 flush，减少 I/O 频次；也支持立即写入（debug 场景）
支持结构化与可扩展的日志格式
自动记录的价值，取决于日志是否便于查询和归因：
- 默认输出 JSON 行格式（每条日志一行 JSON），包含 timestamp、level、message、stack、context（自定义字段）、type: 'unhandled-rejection' 等标识
- 暴露 addLogContext 方法，允许在请求入口（如 Express middleware 或 React useEffect）动态注入 traceId、userId 等，后续所有自动日志自动携带
- 预留 transformLog 钩子，方便对接 Sentry、ELK 或云厂商日志服务
