源映射故障排除

源映射的故障排除指南。

如果您之前已经设置了源映射，我们建议更新您的工具（SDK、打包工具插件、Sentry CLI）。通常，升级到最新版本并遵循当前流程比使用旧版本进行故障排除要简单得多。

有关上传源映射的传统方法的信息，请参阅传统上传方法的指南。

需要使用传统方法上传源映射的依赖版本包括：

JavaScript SDK 版本 7.46.0 或更低
@sentry/webpack-plugin 包版本 1.x 或更低
sentry-cli 版本 2.16.1 或更低
Sentry 自托管或单租户版本 23.6.1 或更低

设置源映射可能会有些棘手，但正确配置它是值得的。要排查您的源映射设置问题，您可以选择：

使用 sentry-cli 中的自动化验证工具，或
按照以下列出的手动步骤进行

要使用自动化验证流程，请安装并配置 Sentry 命令行界面。然后，使用 sourcemaps explain 命令，并附带在 sentry.io 问题详情 页面左上角找到的相关事件 ID。

例如，"事件 ID: c2ad049f"：

Copied

sentry-cli sourcemaps explain c2ad049fd9e448ada7849df94575e019

CLI 输出应为您提供有关源映射设置问题的有用信息。如果它没有提供帮助，请通过在我们的 Sentry CLI 仓库上提交问题来告知我们，以便我们改进。

验证您的工件是否已上传到 Sentry。您可以在 [设置] > 项目 > 选择您的项目 > 源映射 中找到它们。为了使 Sentry 能够反混淆您的堆栈跟踪，您必须提供压缩文件（例如，app.min.js）及其对应的源映射文件。

生成代码的打包工具和工具（如 tsc）通常需要您手动设置特定选项以生成源映射。

如果您遵循了我们针对特定工具的指南，请验证您已配置工具以生成源映射，并确保源映射文件中的 sourcesContent 字段包含您的原始源代码。

当在开发模式/监听模式下运行 JavaScript 构建工具（如 webpack、Vite 等）时，生成的代码有时与我们的源映射上传流程不兼容。

我们建议，尤其是在本地测试时，运行生产构建以验证您的源映射上传设置。

在您上传到 Sentry 的 JavaScript 文件中，查找类似 e._sentryDebugIds=e._sentryDebugIds||{} 的代码片段。根据您处理代码的方式不同，此代码片段可能有所不同。

如果一个包中存在此代码片段，则该包可以与源文件匹配。您应用中部署的每个包都需要包含此代码片段，以便正确进行源映射。

如果您的源代码中没有此代码片段且您正在使用 Sentry 打包工具插件，请确保您使用的是最新版本，并验证插件是否正确处理了您的文件。将 debug 选项设置为 true 以打印有用的调试信息。

如果您使用的是 Sentry CLI，请确保在上传到 Sentry 之前和部署文件之前运行 inject 命令。

在 Sentry 中检查事件的有效负载 JSON 数据时，验证事件是否具有 debug_meta 属性。如果此属性缺失，并且您已经确认源文件包含调试 ID 注入代码片段，则很可能意味着您使用的是过时的 SDK。

我们通常建议升级到最新版本，为了使源映射正常工作，您至少需要使用版本 7.47.0。

在确认事件具有 debug_meta 属性后，接下来要检查的是事件中的 raw_stacktrace 属性内的所有帧是否都有一个与 debug_meta 图像中的 code_file 属性完全匹配的 abs_path 属性。

如果堆栈帧无法匹配 debug_meta 中的条目，请确保相关文件包含调试 ID 注入代码片段。

Sentry 期望给定版本的源代码和源映射文件在该版本中错误发生之前已上传到 Sentry。

如果您在错误被 Sentry 捕获之后上传工件，Sentry 不会回溯并为这些错误应用任何源注释。只有在工件上传后新触发的错误才会受到影响。

我们维护了一个在线验证工具，可以用于测试您的源映射与您托管的源代码：sourcemaps.io。

或者，如果您使用 Sentry CLI 上传源映射到 Sentry，可以使用 --validate 命令行选项来验证您的源映射是否正确。

如果您发现 Sentry 未能正确映射文件名、行号或列号，请验证您的源映射是否在本地正常工作。为此，您可以使用 Node.js 结合 Mozilla 的 source-map 库。

首先，全局安装 source-map 作为 npm 模块：

Copied

npm install -g source-map

然后，编写一个 Node.js 脚本来读取您的源映射文件并测试映射。以下是一个示例：

Copied

var fs = require("fs"),
  path = require("path"),
  sourceMap = require("source-map");

// Path to file that is generated by your build tool (webpack, tsc, ...)
var GENERATED_FILE = path.join(".", "app.min.js.map");

// Line and column located in your generated file (for example, the source
// of the error from your minified file)
var GENERATED_LINE_AND_COLUMN = { line: 1, column: 1000 };

var rawSourceMap = fs.readFileSync(GENERATED_FILE).toString();
new sourceMap.SourceMapConsumer(rawSourceMap).then(function (smc) {
  var pos = smc.originalPositionFor(GENERATED_LINE_AND_COLUMN);

  // You should see something like:
  // { source: 'original.js', line: 57, column: 9, name: 'myfunc' }
  console.log(pos);
});

如果您的本地结果与通过 Sentry 获取的结果相同（且不正确），请仔细检查您的源映射生成配置。

对于单个工件，Sentry 接受的最大文件大小为 40 MB。

用户经常遇到此限制是因为他们在中间构建阶段传输源文件。例如，在打包工具将所有源文件合并之后，但在压缩之前。如果可能，请发送原始源文件。

Sentry API 当前仅支持以纯文本（UTF-8 编码）格式上传的源映射和源文件。如果文件以压缩格式（例如，gzip）上传，则无法正确解析。

如果您使用 sentry-cli 上传工件，从版本 2.4.0 开始，您可以在 sourcemaps upload 或 files upload 命令中添加 --decompress 标志。

有时，构建脚本和插件会生成预先压缩的最小化文件（例如，webpack 的 compression plugin）。在这些情况下，您需要禁用此类插件，并在生成的源映射/源文件上传到 Sentry 之后再进行压缩。

如果您公开托管您的源映射，请确保在 [设置] > 项目 > 选择您的项目 > 基本设置 中启用了“启用 JavaScript 源文件获取”选项。

如果您正在运行自托管版本的 Sentry，可以通过检查容器的日志来验证 symbolicator 服务/容器是否正常运行。

Sentry 在其 workers 中进行源映射计算。这意味着 workers 需要访问通过前端上传的文件。请确保 cron workers 和 web workers 可以从同一磁盘读取/写入文件。

如果尚未将源映射上传到 Sentry，Sentry Node.js SDK 通常可以很好地与 source-map-support 包一起工作。

但是，如果您正在将源映射上传到 Sentry 或在浏览器中使用 Sentry SDK，则您的代码不能使用 source-map-support 包。source-map-support 会以一种阻止我们的源映射处理器正确解析的方式覆盖捕获的堆栈跟踪。

源码映射

传统上传方法