Flashduty CLI 源码管理与异常追踪

概述

Flashduty CLI 是从 datadog-cli fork 而来的一款命令行工具，支持用户将 sourcemap 文件上传至 Flashduty 服务器。通过 sourcemap，前端开发者可以更高效地进行错误追踪和调试。用户可在「应用管理」 - 「源码管理」菜单查看已上传的 sourcemap 文件，并通过上传面板生成脚本在本地执行上传操作。本文档将详细介绍 sourcemap 的作用、生成与上传方法、管理方式，以及如何在异常追踪模块中利用 sourcemap 精确定位问题。

为什么需要 SourceMap？

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

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

精确定位错误：通过 SourceMap，可以在异常追踪中直接定位到原始源代码中的具体位置，而不仅是压缩后的文件。

提升调试效率：开发者无需手动解码压缩文件，节省排查问题的时间。

如何生成并上传 SourceMap？

生成 SourceMap

大多数现代构建工具（如 Webpack、Rollup 或 Vite）都支持生成 SourceMap。以下是以 Webpack 为例的配置方法：

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

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

上传 SourceMap 使用 Flashduty CLI

Flashduty CLI 提供了 sourcemaps 命令，用于将 sourcemap 文件上传至 Flashduty 服务器。以下是具体步骤：

安装 Flashduty CLI

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

配置 API Key 和服务信息
2025-05-15-17-34-06

在 应用管理 - 源码管理 菜单中，点击"上传源码"面板，填写以下信息并生成上传脚本：

API Key：用于认证您的身份（例如 test2）。

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

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

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

生成的脚本示例：

执行上传

在项目根目录下，运行生成的脚本，确保 sourcemap 文件位于指定路径（如 dist 目录）。Flashduty CLI 会将 sourcemap 文件上传至服务器。

注意：

确保 minified-path-prefix 与实际部署的压缩文件路径一致。

上传成功后，可在 应用管理 - 源码管理 中查看已上传的 sourcemap 文件。

SourceMap 如何管理？

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

查看已上传的 SourceMap：菜单中列出了所有已上传的 sourcemap 文件，包括文件路径、服务名、版本号、大小和上传时间。

版本管理：通过 service 和 release-version 参数，可以为不同版本的应用分别管理 sourcemap，便于多版本并行调试。

权限控制：通过 API Key 确保只有授权用户可以上传或管理 sourcemap。

如何在异常追踪模块查看源码？

Flashduty RUM（Real User Monitoring）集成了 sourcemap 功能，支持在异常追踪模块中直接查看原始源代码，精确定位问题。以下是操作流程：

捕获前端错误

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

示例：自动捕获未处理的异常

关联 SourceMap

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

例如，压缩文件 /assets/index-5e0391ac.js 的错误堆栈：

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

通过 sourcemap，映射到原始源代码 src/components/App.js：

Error: Something went wrong
    at App.render (src/components/App.js:45:10)

查看异常详情

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

错误消息：如 Something went wrong。

原始堆栈：映射后的源代码文件路径、行号和列号（如 src/components/App.js:45:10）。

上下文代码：显示错误位置附近的源代码片段，便于快速定位问题。

调试与修复

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

最佳实践

规范化 SourceMap 上传：

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

示例（GitHub Actions）：

版本管理：

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

清理源码：

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

测试映射效果：

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

常见问题

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

确认 sourcemap 是否成功上传，且 minified-path-prefix 与实际部署路径一致。

检查 service 和 release-version 是否与错误发生时的应用版本匹配。

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

确保 sourcemap 文件仅上传至 Flashduty 服务器，不直接暴露在公网。

在生产环境中，移除对 sourcemap 文件的直接访问（如通过 Nginx 配置）。

3. 上传 SourceMap 失败怎么办？

检查 API Key 是否有效。

确保网络连接正常，CLI 版本是最新的。

下一步

异常聚合

Issue 状态

源码映射

Flashduty CLI 源码管理与异常追踪#

概述#

为什么需要 SourceMap？#

如何生成并上传 SourceMap？#

生成 SourceMap#

上传 SourceMap 使用 Flashduty CLI#

SourceMap 如何管理？#

如何在异常追踪模块查看源码？#

最佳实践#

常见问题#

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

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

3. 上传 SourceMap 失败怎么办？#

下一步#