source-maps-debugging

使用 Source Maps 调试 TypeScript

概述

Source Maps 搭起了 TypeScript 源代码与实际运行的编译后 JavaScript 之间的桥梁。它们可以让调试器显示原始 TypeScript 代码、在 .ts 文件中设置断点，并提供有意义的堆栈跟踪。没有 Source Maps 时，你只能调试编译后的 JavaScript，这既令人沮丧，也容易出错。

正确配置 Source Maps 对高效调试 TypeScript 应用至关重要。

何时使用此技能

• 在浏览器或 Node.js 中调试 TypeScript
• 配置构建工具（webpack、vite、rollup）
• 堆栈跟踪显示编译后的 JavaScript
• TypeScript 文件中的断点不起作用
• 配置生产构建

铁律

在开发环境中启用 Source Maps 以便调试。可考虑在生产环境中使用单独的 Source Maps 来报告错误，同时保持较小的打包体积。

检测

留意以下调试问题：

// Stack trace shows compiled JavaScript:
Error: Something went wrong
    at Object.<anonymous> (app.js:42:15)
    at Module._compile (internal/modules/cjs/loader.js:1137:30)

// Should show TypeScript:
Error: Something went wrong
    at fetchUser (api.ts:15:10)
    at async loadData (app.ts:42:5)

启用 Source Maps

TypeScript 编译器

// tsconfig.json
{
  "compilerOptions": {
    "sourceMap": true,        // Generate .js.map files
    "inlineSourceMap": false, // Don't inline (for development)
    "inlineSources": false,   // Include source in map
    "sourceRoot": "/",        // Root for source paths
    "mapRoot": "/"            // Root for map paths
  }
}

构建工具

// webpack.config.js
module.exports = {
  devtool: 'source-map',  // or 'eval-source-map' for faster builds
};

// vite.config.ts
export default {
  build: {
    sourcemap: true,
  },
};

// rollup.config.js
export default {
  output: {
    sourcemap: true,
  },
  plugins: [typescript({ sourceMap: true })],
};

Source Map 选项

选项	使用场景	构建速度	质量
source-map	生产环境	慢	最佳
eval-source-map	开发环境	快	良好
inline-source-map	单个文件	中等	良好
hidden-source-map	生产环境（错误报告）	慢	最佳
nosources-source-map	生产环境（不含代码）	慢	仅堆栈跟踪

生产环境注意事项

// webpack.config.js - different for dev/prod
module.exports = (env) => ({
  devtool: env.production 
    ? 'hidden-source-map'  // Separate file, not referenced
    : 'eval-source-map',   // Fast, good for development
});

将 Source Maps 上传到错误报告服务：

// Sentry example
Sentry.init({
  dsn: 'your-dsn',
  release: process.env.RELEASE,
  // Source maps uploaded separately
});

验证 Source Maps

# Check if source map was generated
ls dist/*.js.map

# Inspect source map content
npx source-map-explorer dist/app.js

# Test in browser DevTools
# 1. Open DevTools
# 2. Go to Sources tab
# 3. Look for original .ts files
# 4. Set breakpoint in TypeScript

抗压协议

配置 Source Maps 时：

1. 在开发环境中启用：这是调试的必要条件
2. 选择生产环境策略：隐藏、无源码或不使用
3. 测试断点：确认它们在 TypeScript 文件中有效
4. 检查堆栈跟踪：应显示 .ts 文件和行号
5. 监控打包体积：Source Maps 可能很大

危险信号

症状	问题	解决方案
.ts 中的断点不起作用	未加载 Source Maps	在构建配置中启用
堆栈跟踪显示 .js	未生成 Source Maps	检查 tsconfig/构建工具
行号错误	Source Maps 已过期	重新构建生成
打包体积过大	使用了内联 Source Maps	使用单独的文件

常见借口

“Source Maps 会拖慢构建速度”

实际情况：开发时使用 eval-source-map 来提高速度。只有生产构建才使用完整的 Source Maps。

“我不需要它们，我能看懂 JS”

实际情况：调试经过类型、async/await 转换等处理的编译后 JS 很痛苦。Source Maps 能节省数小时。

“它们会暴露我的源代码”

实际情况：生产环境使用 hidden-source-map 或 nosources-source-map。只将它们上传到错误报告服务。

快速参考

环境	建议选项	备注
开发环境	eval-source-map	快速重建
生产环境 + 调试	source-map	质量最佳
生产环境 + 错误报告	hidden-source-map	上传到服务
生产环境（最精简）	nosources-source-map	仅堆栈跟踪

总结

启用 Source Maps 来调试 TypeScript。开发时使用快速选项，生产环境可考虑使用隐藏或无源码选项。它们能显著简化调试。

参考资料

• Dan Vanderkam 所著《Effective TypeScript》第 2 版
• 条目 73：使用 Source Maps 调试 TypeScript