TypeScript (tsc)

使用 tsc 和 Sentry CLI 上传源映射。

在本指南中，您将学习如何成功使用我们的 sentry-cli 工具为 TypeScript 项目上传源映射。

本指南假设以下条件：

sentry-cli 版本 >= 2.17.0
Sentry JavaScript SDK 版本 >= 7.47.0

本指南仅适用于使用 tsc 编译项目的用户。如果您使用其他工具（如 webpack）与 TypeScript 结合，请参考相应的指南。

使用 tsc 和 sentry-cli 配置源映射上传最简单的方法是通过 Sentry 向导：

Copied

npx @sentry/wizard@latest -i sourcemaps

向导将引导您完成以下步骤：

登录 Sentry 并选择一个项目
安装必要的 Sentry 包
配置您的构建工具以生成和上传源映射
配置您的 CI 以上传源映射

如果您更愿意手动配置源映射，请按照以下步骤操作。

首先，配置 TypeScript 编译器以输出源映射：

tsconfig.json

Copied

{
  "compilerOptions": {
    "sourceMap": true,
    "inlineSources": true,

    // Set `sourceRoot` to  "/" to strip the build path prefix from
    // generated source code references. This will improve issue grouping in Sentry.
    "sourceRoot": "/"
  }
}

生成源映射文件可能会将其暴露给公众，从而导致您的源代码泄露。您可以通过配置服务器拒绝访问 .js.map 文件，或在部署应用程序之前删除源映射文件来防止这种情况。

您可以在以下链接找到 Sentry CLI 的安装说明：https://docs.sentry.io/cli/installation/

有关 sentry-cli 配置的更多信息，请参阅 Sentry CLI 配置文档。

确保 sentry-cli 已为您的项目配置好。为此，您可以使用环境变量：

.env.local

Copied

SENTRY_ORG=example-org
SENTRY_PROJECT=example-project
SENTRY_AUTH_TOKEN=sntrys_YOUR_TOKEN_HERE

调试 ID 用于将事件的堆栈帧与其对应的最小化源文件和源映射文件匹配。如果您想了解更多关于工件包和调试 ID 的信息，请访问什么是工件包。

要注入调试 ID，请使用以下命令：

Copied

sentry-cli sourcemaps inject /path/to/directory

最小化源文件应在末尾包含一个名为 debugId 的注释，例如：

example_minified_file.js

Copied

...
//# debugId=<debug_id>
//# sourceMappingURL=<sourcemap_url>

源映射文件应包含一个名为 debug_id 的字段，例如：

example_source_map.js.map

Copied

{
    ...
    "debug_id":"<debug_id>",
    ...
}

在您将调试 ID 注入工件后，使用以下命令上传它们。

Copied

sentry-cli sourcemaps upload /path/to/directory

打开 Sentry 并导航到 项目设置 > 源映射。如果您在选项卡导航中选择“工件包”，您将看到所有已成功上传到 Sentry 的工件包。

如果您是按照本指南在本地机器上操作，那么您已经成功完成了以下步骤：

通过运行应用程序的构建过程生成了最小化源文件和源映射文件（工件）。
将调试 ID 注入到刚刚生成的工件中。
使用我们的上传命令将这些工件上传到 Sentry。

最后一步是使用第一步中生成的工件部署应用程序的新版本。我们强烈建议您将 sentry-cli 集成到您的 CI/CD 流水线中，以确保每次后续部署都会自动将调试 ID 注入每个工件并直接上传到 Sentry。

警告

仅在您确定绝对需要这些可选步骤时才进行。使用 release 和 dist 值会使您的工件上传更加具体，但也会使整个过程更不宽容，可能导致您的代码无法被 Sentry 正确反混淆。

在您的 SDK 选项中提供一个 release 属性。

Copied

Sentry.init({
  // This value must be identical to the release name specified during upload
  // with the `sentry-cli`.
  release: "<release_name>",
});

之后，使用额外的 --release 选项运行 sourcemaps upload 命令。请确保为 <release_name> 指定的值与 SDK 选项中指定的值相同。

Copied

sentry-cli sourcemaps upload --release=<release_name> /path/to/directory

使用 --release 选项运行 upload 不会自动在 Sentry 中创建版本。您可以等待第一个带有新版本设置的事件通过 Sentry.init 发送到 Sentry，或者使用相同的名称在单独的步骤中通过 CLI 创建版本。

除了 release，您还可以为上传的工件添加 dist，以设置上传文件的分发标识符。为此，请使用额外的 --dist 选项运行 sourcemaps upload 命令。

在您的 SDK 选项中提供 release 和 dist 属性。

Copied

Sentry.init({
  // These values must be identical to the release and dist names specified during upload
  // with the `sentry-cli`.
  release: "<release_name>",
  dist: "<dist_name>",
});

分发标识符用于在同一版本内区分多个同名文件。dist 可用于区分不同的构建或部署变体。

Copied

sentry-cli sourcemaps upload --release=<release_name> --dist=<dist_name> /path/to/directory

在编译过程中，TypeScript 会在生成的输出文件中注入一些运行时依赖项（如果需要）。这可能包括函数生成器或多环境不可用的 API 的 polyfill。然而，由于这些注入的代码没有对应的原始源文件，导致无法将编译后的代码帧映射回原始源代码。

作为解决方法，您需要告诉 TypeScript 编译器使用 tslib（TypeScript 自己的第三方包，内部是编译器的一部分）而不是注入运行时依赖项。您只需要更改 TypeScript 配置文件中的内容，而不需要修改源代码。具体步骤如下：

确保 tslib 列为 package.json 文件中的依赖项。
完成后，在 tsconfig.json 文件的 compilerOptions 部分添加两个条目：
- "noEmitHelpers": true 和
- "importHelpers": true。

这样就可以正确映射所有堆栈跟踪帧的源映射，包括内部 TypeScript 编译器代码片段。

Webpack

Vite