Source Map 与生产错误定位

🗺️ Source Map 让你在生产环境的压缩代码中定位到原始源码位置。正确配置是远程错误分析的前提。

Source Map 原理

什么是 Source Map

构建工具在压缩代码旁生成 .map 文件，记录压缩代码每一个字符对应的原始文件和行列号。

// 压缩代码末尾指向 map 文件
//# sourceMappingURL=bundle.js.map

Source Map 内容

{
  "version": 3,
  "sources": ["src/app.ts", "src/utils.ts"],
  "names": ["myFunction", "result"],
  "mappings": "AAAA;AACA...",  // Base64 VLQ 编码的位置映射
  "sourcesContent": ["// 原始 TS 代码..."]
}

---

Vite 配置

// vite.config.ts
export default defineConfig({
  build: {
    // 生产环境推荐：不内联到 HTML，单独文件
    sourcemap: 'hidden',  // 生成 .map 但不内联
    // sourcemap: true,   // 内联（暴露源码）
    // sourcemap: false,  // 不生成
  }
})

生产环境推荐配置

方式	安全性	调试能力
sourcemap: false	高	无法定位
sourcemap: 'hidden'	中（需保护 .map）	可上传上跟踪服务
sourcemap: true	低（暴露源码）	完整调试

---

错误监控与 Source Map 上传

Sentry 集成

# 构建后上传 Source Map
npx sentry-cli releases files <release> upload-sourcemaps ./dist \
  --url-prefix '~/static/js'

# 删除本地 .map 文件（安全）
rm dist/**/*.map

Vite 自动上传插件

import { sentryVitePlugin } from '@sentry/vite-plugin'

export default defineConfig({
  plugins: [
    sentryVitePlugin({
      authToken: process.env.SENTRY_AUTH_TOKEN,
      org: 'your-org',
      project: 'your-project',
    })
  ],
  build: { sourcemap: true }
})

---

错误堆栈解读

压缩后的堆栈

TypeError: Cannot read property 'x' of undefined
    at t (bundle.js:1:5423)
    at r (bundle.js:1:8901)

映射后的堆栈

TypeError: Cannot read property 'x' of undefined
    at fetchUser (src/api/users.ts:42:8)
    at UserProfile.componentDidMount (src/components/UserProfile.tsx:31:5)

本地解析工具

# 使用 source-map-cli 解析
npx source-map resolve bundle.js.map 1 5423

# WebStorm / VS Code 可直接加载 .map 文件调试

---

常见误区

• 以为 hidden sourcemap 绝对安全，实际任何人自己上传到 CDN 后都能访问 .map 文件
• Source Map 没有上传到错误监控，居然还在手动解析堆栈
• 生产和测试环境使用不同的 Source Map 配置，导致测试没有覆盖真实问题