要让 node.js 错误堆栈还原到 typescript 源码位置，需在入口顶部引入 source-map-support 插件并确保 source map 文件正确生成与加载：安装插件、首行注册、tsconfig 配置 "sourcemap": true、验证 .map 文件存在及 sourcemappingurl 正确，测试环境需适配框架配置。
Node.js 服务端运行报错时，默认堆栈指向编译后的 .js 文件和行号，无法直接定位到 TypeScript 源码。要让错误信息还原回 .ts 文件位置，核心是利用 source-map-support 插件劫持 V8 的错误堆栈生成流程，通过 source map 文件反查原始位置。
安装并启用 source-map-support
该插件需在应用入口最顶部（早于任何其他代码）加载，确保所有后续错误都能被拦截：
- 安装：
npm install source-map-support --save-dev（生产环境也建议保留，无性能开销） - 在
src/index.ts或主入口文件第一行添加：import 'source-map-support/register';
或使用 CommonJS：require('source-map-support').install(); - 注意：必须在
ts-node或tsc编译产物被 require 之前执行，否则部分早期错误（如模块解析失败）无法捕获
确保 source map 文件正确生成并可访问
插件本身不生成 source map，它只读取已存在的 .map 文件。因此构建环节必须配置输出：
- TypeScript 项目：在
tsconfig.json中设"sourceMap": true，且"outDir"与实际输出路径一致 - Webpack 构建 Node 服务：设置
devtool: 'source-map'或'inline-source-map'；target: 'node'和externals: [nodeExternals()]不影响 source map 生效 - 检查产物目录：确认
dist/index.js同级存在index.js.map，且index.js文件末尾有注释：//# sourceMappingURL=index.js.map
验证错误堆栈是否还原成功
启动服务后主动触发一个错误（例如 throw new Error('test')），观察控制台输出：
- 还原成功：堆栈显示类似
at src/utils/logger.ts:12:15，路径为.ts文件，行号准确 - 还原失败常见原因：
–.map文件缺失或路径不匹配（比如sourceMappingURL指向了不存在的路径）
–sourceRoot或sources字段中的相对路径无法从当前工作目录解析（可尝试在tsconfig.json中加"sourceRoot": "./src"）
– 使用了ts-node --transpile-only，跳过了类型检查但未生成 source map（应改用ts-node -r source-map-support/register启动）
测试环境特别注意事项
单元测试（如 Jest、Vitest）中容易出现堆栈还原异常，因为测试框架自身会包装错误、修改调用栈：
- Jest 用户：推荐关闭其内置 source map 处理，显式启用插件：
在jest.config.ts中设globals: { 'ts-jest': { isolatedModules: false, diagnostics: false } }，并在测试启动脚本开头注册source-map-support - Vitest 用户：启用
server.sourcemap: true并在vitest.config.ts的setupFiles中导入注册语句 - 若仍出现行号偏移，说明测试运行时的 frame 解析被干扰，此时可临时在
source-map-support初始化后加require('source-map-support').install({ handleUncaughtExceptions: false });，仅处理手动抛出的错误
