Source Map

生成并上传 source map，让生产栈追踪指向原始 TypeScript。

为什么

prod 栈追踪说'at a (chunk-abc123.js:1:4587)'无用——无翻译不能调试压缩 bundled 代码。Source map 是翻译层：有它 Sentry 显'at checkout (src/routes/checkout.ts:42:7)'，30 秒修；无它盯压缩一行 1 小时放弃。坑是 map 不能公开服务（泄源码），故工作流：构建生、CI 上传错误追踪器、再从部署产物删。跳过此是'prod bug 不可调试'最大原因。

何时使用

首次 prod 部署前。接 CI 约 15-30 分钟。仅发布未压缩代码可跳过。

如何做

1. 构建配置启 source map（devtool / sourcemap）
   - Vite：build.sourcemap = true
   - Next.js：productionBrowserSourceMaps: true（或 server 实验性）
   - esbuild/tsc：--sourcemap 标志

2. 选隐藏 source map（prod bundle 无 // sourceMappingURL 注释）
   - bundle 干净；map 单独上传错误追踪器
   - Vite：sourcemap: 'hidden'；Webpack：devtool: 'hidden-source-map'

3. CI 上传 map 到错误追踪器，按 release 版本键
   - Sentry：sentry-cli sourcemaps upload --release <version> ./dist
   - release 标签须匹配应用运行时报告

4. 上传后从部署产物删 .map 文件
   - 永不公开服务——它们为任何下载者反向压缩你的代码
   - 加 CI 步：上传后 rm -rf dist/**/*.map

5. 端到端验证：prod 触发故意错误，确认 trace 显 .ts 文件和行
   - 若仍显 .js，release 标签不匹配或 map 未上传

示例

// vite.config.ts——prod 隐藏 source map
export default defineConfig({
  build: {
    sourcemap: process.env.NODE_ENV === "production" ? "hidden" : true,
  },
});

# .github/workflows/release.yml——上传后删
- run: pnpm build
- run: |
    pnpm exec sentry-cli sourcemaps upload \
      --release ${{ github.sha }} \
      --dist-prefix ./dist ./dist
- run: Remove-Item -Recurse -Force dist/**/*.map   # 永不公开服务 map
- run: pnpm exec vercel deploy --prebuilt

// 运行时验证——错误追踪器应显 .ts 路径
throw new Error("故意 prod 测试");  // 期望：src/routes/checkout.ts:42

常见问题

⚠公开随 bundle 服务 .map——任何者可反向压缩 app 到全源码。
⚠忘用 release 版本标上传，Sentry 不能匹配错误到 map。
⚠仅客户端启 source map 非服务端——serverless 函数错误不透明。
⚠上传 map 但不从产物删，部署比需大 2 倍。

最佳实践

✓用隐藏 source map（无 sourceMappingURL 注释）浏览器永不请求但错误追踪器可按 release 标找。
✓每 release 用 git SHA 标，同 SHA 传上传和运行时 SDK——不匹配是 trace 不解析 #1 原因。
✓serverless 每函数上传 map（Sentry 支持），每函数 trace 独立解析。
✓每 release 用故意错误测管道——trace 不解析则真 bug 来前修。