源码映射与异常追踪

本文档详细介绍如何使用 FlashCat RUM 进行源码映射管理，以及如何通过源码映射进行异常追踪和调试。

Flashduty CLI 是一款命令行工具，支持用户将 sourcemap 文件上传至 Flashduty 服务器。通过 sourcemap，前端开发者可以更高效地进行错误追踪和调试。

用户可在「应用管理」-「源码管理」菜单查看已上传的 sourcemap 文件，并通过上传面板生成脚本在本地执行上传操作。

​

为什么需要 SourceMap？

在现代前端开发中，JavaScript 和 CSS 文件通常会被压缩和混淆，以优化加载速度和性能。然而，这种压缩会导致错误堆栈中的代码位置信息无法直接映射到原始源代码，增加了调试难度。

映射压缩代码

SourceMap 记录了压缩代码与原始代码之间的映射关系，允许开发者在调试时查看未压缩的源代码

精确定位错误

通过 SourceMap 可以在异常追踪中直接定位到原始源代码中的具体位置

提升调试效率

开发者无需手动解码压缩文件，节省排查问题的时间

​

生成 SourceMap

大多数现代构建工具（如 Webpack、Rollup 或 Vite）都支持生成 SourceMap。

Webpack

在 webpack.config.js 中启用 SourceMap 生成：

module.exports = {
  mode: "production",
  devtool: "source-map", // 生成独立的 .map 文件
  output: {
    filename: "bundle.js",
    path: path.resolve(__dirname, "dist"),
  },
};

构建后，dist 目录中会生成 bundle.js 和对应的 bundle.js.map 文件。

Vite

在 vite.config.js 中配置：

export default {
  build: {
    sourcemap: true, // 生成 sourcemap
  },
};

Rollup

在 rollup.config.js 中配置：

export default {
  output: {
    sourcemap: true,
  },
};

​

上传 SourceMap

使用 Flashduty CLI 将 sourcemap 文件上传至 Flashduty 服务器。

1. 安装 Flashduty CLI

   确保已安装 Node.js，然后通过 npm 安装：

   npm install -g @flashcloud/flashcat-cli
   
2. 配置上传参数

   

   在「应用管理」-「源码管理」菜单中，点击「上传源码」面板，填写以下信息：

   API Key · string · 必填

   用于认证您的身份

   服务名 · string · 必填

   应用的服务名（例如 my-service）

   版本号 · string · 必填

   应用的发布版本（例如 1.0.0）

   压缩文件前缀 · string · 必填

   压缩文件的路径前缀（例如 /assets）

3. 执行上传

   在项目根目录下运行生成的脚本：

   flashcat-cli sourcemaps upload \
     --service my-service \
     --release-version 1.0.0 \
     --minified-path-prefix /assets \
     --api-key your-api-key \
     ./dist
   

• 确保 minified-path-prefix 与实际部署的压缩文件路径一致
• 上传成功后，可在「应用管理」-「源码管理」中查看已上传的 sourcemap 文件

​

SourceMap 管理

在 Flashduty 平台上，sourcemap 文件的管理通过「应用管理」-「源码管理」菜单完成：

功能	说明
查看已上传的 SourceMap	列出所有已上传的文件，包括路径、服务名、版本号、大小和上传时间
版本管理	通过 service 和 release-version 参数为不同版本的应用分别管理
权限控制	通过 API Key 确保只有授权用户可以上传或管理

​

在异常追踪中查看源码

Flashduty RUM 集成了 sourcemap 功能，支持在异常追踪模块中直接查看原始源代码，精确定位问题。

1. 捕获前端错误

   Flashduty RUM SDK 会自动捕获前端错误（如 JavaScript 异常、Promise 拒绝、网络错误等），并将错误堆栈信息发送至服务器。

   throw new Error("Something went wrong");
   
2. 关联 SourceMap

   当错误堆栈中的文件路径和行号与已上传的 sourcemap 匹配时，Flashduty 会自动将压缩代码的错误位置映射到原始源代码。

   压缩文件堆栈：

   Error: Something went wrong
       at Object.<anonymous> (/assets/index-5e0391ac.js:1:123)
   

   映射后的源代码：

   Error: Something went wrong
       at App.render (src/components/App.js:45:10)
   
3. 查看异常详情

   在异常追踪模块中，点击具体的错误记录，可以查看：

   • 错误消息：如 Something went wrong
   • 原始堆栈：映射后的源代码文件路径、行号和列号
   • 上下文代码：显示错误位置附近的源代码片段
4. 调试与修复

   根据映射后的源代码位置，直接在本地开发环境中找到对应代码，分析问题根因并修复。

​

最佳实践

规范化 SourceMap 上传

在 CI/CD 流水线中集成上传命令，确保每次发布时自动上传 sourcemap。

GitHub Actions 示例：

- name: Upload SourceMaps
  run: |
    flashcat-cli sourcemaps upload \
      --service my-service \
      --release-version ${{ github.sha }} \
      --minified-path-prefix /assets \
      --api-key ${{ secrets.FLASHCAT_API_KEY }} \
      ./dist

版本管理

使用 --release-version 参数与应用版本号保持一致，便于追踪特定版本的 sourcemap。

清理源码

在资源上传 CDN 之前删除 sourcemap 文件，避免将源码信息带入生产环境。

测试映射效果

上传 sourcemap 后，主动抛出测试错误，验证异常追踪模块是否能正确映射到源代码。

​

常见问题

为什么异常堆栈没有映射到源代码？

• 确认 sourcemap 是否成功上传，且 minified-path-prefix 与实际部署路径一致
• 检查 service 和 release-version 是否与错误发生时的应用版本匹配

如何避免 SourceMap 泄露敏感信息？

• 确保 sourcemap 文件仅上传至 Flashduty 服务器，不直接暴露在公网
• 在生产环境中，移除对 sourcemap 文件的直接访问（如通过 Nginx 配置）

上传 SourceMap 失败怎么办？

• 检查 API Key 是否有效
• 确保网络连接正常，CLI 版本是最新的

​

下一步

异常聚合

了解异常聚合机制

Issue 状态

管理 Issue 状态流转