lw-source-map-support

🔧 修复带有 sourcemap 文件的堆栈跟踪，提供更好的调试体验。

📦 安装

npm install lw-source-map-support

✨ 特性

• 🎯 自动 Source Map 支持: 自动解析 source map 文件，提供准确的错误堆栈
• 🚀 零配置: 简单导入即可使用，无需复杂配置
• 📍 精确定位: 将编译后的错误位置映射到源文件的准确行号
• 💡 开发友好: 大幅提升 TypeScript/JavaScript 项目的调试效率
• 🔄 ES Module 支持: 完全支持现代 ES Module 规范

🚀 快速开始

基本使用

在您的应用入口处导入：

import "lw-source-map-support/dist/register.js";

// 您的应用代码
function main() {
  // 现在错误堆栈将显示源文件位置而不是编译后的位置
  throw new Error("This error will show correct source location!");
}

main();

Node.js 使用

# 使用 --import 标志
node --import lw-source-map-support/dist/register.js your-app.js

# 或者在代码中导入
node -e "import 'lw-source-map-support/dist/register.js'; import './your-app.js'"

TypeScript 项目

// 在您的 main.ts 文件顶部
import "lw-source-map-support/dist/register.js";

// 您的 TypeScript 代码
class MyApp {
  run() {
    console.log("Application started with source map support!");
  }
}

new MyApp().run();

🎯 使用场景

开发调试

// before: 错误显示编译后的位置
// Error: Something went wrong
//     at Object.<anonymous> (/dist/app.js:42:15)

// after: 错误显示源文件位置
// Error: Something went wrong
//     at MyClass.method (/src/app.ts:15:8)

生产环境错误追踪

import "lw-source-map-support/dist/register.js";

process.on("uncaughtException", (error) => {
  console.error("Uncaught Exception:", error.stack);
  // 现在堆栈跟踪将指向源文件位置
});

📁 项目结构

lw-source-map-support/
├── src/
│   ├── register.ts      # 主要注册逻辑
│   └── test.ts          # 测试文件
├── dist/                # 编译输出
├── package.json
├── tsconfig.json
└── README.md

🔧 开发

本地开发

# 克隆项目
git clone <repository-url> // 由于网络原因暂未上传到代码库，可以全局安装找到安装目录，拷贝出来再执行下面的操作
cd lw-source-map-support

# 安装依赖
npm install

# 运行测试
npm test

测试

# 运行测试以验证 source map 支持
npm test

# 手动测试
node --import ./dist/register.js ./dist/test.js

📋 API 参考

导入方式

// ES Module (推荐)
import 'lw-source-map-support/dist/register.js'

// Node.js 命令行
node --import lw-source-map-support/dist/register.js app.js

🎨 最佳实践

1. 在应用启动时立即导入

// main.ts - 第一行
import "lw-source-map-support/dist/register.js";

import { startServer } from "./server.js";
import { initDatabase } from "./database.js";

// 应用逻辑

2. 与构建工具集成

// package.json
{
  "scripts": {
    "start": "node --import lw-source-map-support/dist/register.js dist/app.js",
    "dev": "node --import lw-source-map-support/dist/register.js --watch dist/app.js"
  }
}

3. TypeScript 配置

// tsconfig.json
{
  "compilerOptions": {
    "sourceMap": true,
    "inlineSourceMap": false
  }
}

🔍 工作原理

1. 错误拦截: 重写 Error.prepareStackTrace 方法
2. Source Map 解析: 自动读取和解析 .map 文件
3. 位置映射: 将编译后的位置映射回源文件位置
4. 堆栈重建: 生成包含源文件信息的新堆栈跟踪

🤔 常见问题

Q: 为什么错误位置还是显示编译后的文件？

A: 请确保：

• Source map 文件 (.map) 存在且可访问
• 在应用的最早阶段导入了本库
• TypeScript 配置中启用了 sourceMap: true

Q: 支持哪些 Node.js 版本？

A: 支持 Node.js 14+ 和所有支持 ES Module 的环境。

Q: 如何在生产环境使用？

A:

// 仅在开发环境或需要调试的生产环境使用
if (process.env.NODE_ENV !== "production" || process.env.ENABLE_SOURCE_MAPS) {
  import("lw-source-map-support/dist/register.js");
}

📊 性能影响

• ✅ 启动开销: 极小，仅在错误发生时处理
• ✅ 内存使用: 最小化，按需加载 source map
• ✅ 运行时性能: 几乎无影响，仅影响错误处理路径

🆚 与其他方案对比

| 特性 | lw-source-map-support | source-map-support | @cspotcode/source-map-support | | ------------------- | --------------------- | ------------------ | ----------------------------- | | ES Module 支持 | ✅ | ❌ | ✅ | | TypeScript 原生支持 | ✅ | ⚠️ | ✅ | | 零配置 | ✅ | ✅ | ✅ | | 包大小 | 小 | 中 | 中 |

📄 许可证

ISC

👨‍💻 作者

785184273