sentry 上传 source-map 总结

前言

公司项目上已经有接入过 sentry，但当时出于某些原因考虑，没有加入对应的 sourceMap。以致于线上代码出现报错时，定位问题出现的位置不怎么方便。为解决这个问题，这两天对 sentry 的配置进行了一些修改。修过过程中遇见了好几个问题，在这里进行整理。

遇见的问题

1. 上传 sourceMap 报 Always get Invalid token (http status: 401) 错误
2. 配置并上传 sourceMap 后，和没有上传 sourceMap 一样，不能正确提示出错误位置
3. sourceMap 只需上传到 sentry，不需要上传到线上环境

为方便理解，我们还是从头来过一遍。

接入步骤

创建项目

注册一个 sentry 账户。然后选中 Projects 菜单栏。右边会提示创建项目。

选择我们项目使用的框架或语言

注意：不同的平台创建好后，使用的 sentry 包是不同的，所以一定要选择自己项目使用的前端框架。比如 react 会使用 @sentry/react、 vue 会使用 @sentry/vue。

这里以 Vue 项目举例。

创建好项目后，会自动进入到接入引导页面。

接入项目

安装必要的包

yarn add @sentry/vue @sentry/tracing

调用 Sentry.init 方法在项目中初始化 sentry。我使用的是 Vue2，所以 sentry 初始化代码如下：

Sentry.init({
  Vue,
  dsn: "https://****@o98647.ingest.sentry.io/****",
  integrations: [
    new BrowserTracing({
      routingInstrumentation: Sentry.vueRouterInstrumentation(router),
      tracePropagationTargets: ["localhost", "my-site-url.com", /^//],
    }),
  ],
  // Set tracesSampleRate to 1.0 to capture 100%
  // of transactions for performance monitoring.
  // We recommend adjusting this value in production
  tracesSampleRate: 1.0,
});

这里有三个参数要注意：

• dsn。作用：告诉 SDK 应该将事件发送到什么位置。在 Settings – Projects – $SELECT_PROJECT – Client Keys(DSN) 处可以找到。
• integrations。Sentry 使用 Tracing 概念上报性能数据。开启性能监控的 Tracing 采集需要在 Sentry.init 的时候初始化 ingegrations 配置。
• tracesSampleRate。选项设置为 0 到 1 之前的一个数字。设置此选项后，创建的每个 transaction 将有一定百分比的机会被发送到 Sentry。如果设置为 0.2，将记录和发送大约 20% 的 transactions。

注意：这里我们不加 release 参数。在后面的其它地方会添加。

验证接入

启动项目，在浏览器中打开一个页面。在 控制台 的 Network 处搜索 sentry，出现以下内容表示接入正常。

这里在代码中随意找一处位置，想办法让它报错，比如：

这时候刷新 sentry 的 Issues 页面，会出现以下问题。

点击进入这个错误，我们发现确实是记录了这个问题。但是，是哪个文件的哪个位置报的这个错？看不懂！

这里，就需要进入我们下一个步骤了。

上传 sourceMap

sourceMap 是什么？

简单来说，sourceMap 就是一个信息文件，里面存储为代码打包转换后的位置信息。实质是一个 JSON 描述文件，维护了打包前后的代码映射关系。

sentry 也需要通过上传 sourceMap 文件来让报错的内容与打包前的代码映射起来，让我们排除起问题来更加方便。效果如下所示：

它有两类上传方式，一个是可以通过 sentry-cli 手动上传。另外一个是通过 webpack、vite 等构建工具自动上传。这里以 webpack 自动上传举例：

安装 @sentry/webpack-plugin

yarn add --dev @sentry/webpack-plugin

修改 webpack 配置，添加 SentryWebpackPlugin

const SentryWebpackPlugin = require("@sentry/webpack-plugin");

module.exports = {
  // ... other config above ...

  devtool: "source-map", // devtool 必须设置成 source-map
  plugins: [
    new SentryWebpackPlugin({
      url: env.SENTRY_URL,
      org: env.SENTRY_ORG,
      project: env.SENTRY_PROJECT,
      include: path.join(process.cwd(), '/dist'),
      authToken: env.SENTRY_AUTH_TOKEN,
      release: process.env.PKM_VERSION,
      urlPrefix: process.env.PKM_CDN_PATH || '~/',
      ignore: ['node_modules'],
    }),
  ],
};

这里有几个参数和 sentry 的 Example 不一样。sentry 的 Example 中只写了 org、project、include、authToken 这四个。我们还多了 url、release、urlPrefix、ignore 这四个。所有的配置可以参考 https://github.com/getsentry/sentry-webpack-plugin#options。

特别注意下面三个参数的作用：

url

这个参数之所以 sentry 的 Example 中没有写是因为 sentry 默认使用的是它自己的服务器，也就是 https://sentry.io/。在公司中使用时，出于安全及性能考虑，基本上会联系运维搭建一个公司自己 sentry 服务器。而这个 url，就是我们自己的 sentry 服务器地址。如果我们使用了自己的 sentry 服务器，又没有配置这个 url，上传 sourceMap  就会报 caused by: sentry reported an error: Invalid token (http status: 401) 错误。

起初以为是 token 生成或者生成 token 时的权限没有给对，让我一阵好找。最后看到 https://blog.toothpickapp.com/upload-dsyms-files/ 里面的这个内容才恍然大悟。(其实也是怪自己对 插件的文档 阅读不深，因为其它项目有用过类似的，我在最初开发时，更多的是去参考之前做过的，而不是仔细地去看文档，根据文档来开发，后面再做类似的修改时，一定要注意这点)。

include

这个的值是我们通过 构建工具 打包后生成的文件地址。如果这个地址没写对，那生成好后的文件不会自动上传到 sentry 上。查看 sentry 上是否有上传对应的 sourceMap 文件可以在 菜单栏 – Releases 处看到。上传成功右边会有对应上传的 release 版本。

urlPrefix

官方文档中的描述为：

URL prefix to add to the beginning of all filenames. Defaults to ~/ but you might want to set this to the full URL. This is also useful if your files are stored in a sub folder. eg: url-prefix ‘~/static/js’.

意思就是这个 URL 前面的地址必须和我们真实访问的地址前缀一样。如果我们打包后的 js 是在我们自己服务器下面的 static/js 下面，那 urlPrefix 就设置成 ~/static/js。如果我们的文件有上传到 CDN 上面，那这个地址需要写上完整的 CDN 地址的前缀。

new SentryWebpackPlugin({
  // ...
  urlPrefix: process.env.PKM_CDN_PATH || '~/', // https://$CDN_URL/
  // ...
})

上传后在 Sentry – Release – artifacts 看到的效果如下：

这一点也是我当时上传成功了，但是代码报错了却仍然看不到具体错在哪里的问题之一。

删除 sourceMap

为了防止一些重要信息被盗取以及减小服务器空间，线上环境我们不需要 sourceMap 文件，deploy 前需要将它删掉或者不上传到服务器上：

执行 CI/CD 时，我们的配置文件类似于：

build:
  stage: build
  script:
    - npm install --registry=https://registry.npm.taobao.org
    - npm run build
    - deploy to server
  tags:
    - runner
  only:
    - master

由于是使用的 webpack 插件自动上传 sourceMap，所以在 build 时就上传到 Sentry 上了，所以在 deploy to server 前，我们可以先将 .map 文件删掉。修改 package.json 的 build：

"script": {
    // ...
    - "build": "umi build",
    + "build": "umi build && rm -rf dist/*.map",
    // ...
}

根据不同的构建工具配置，我是使用的默认的 dist，有些自己配置的 output，可能会是其它的文件夹名。

最后，测试一下是否执行成功。直接访问 https://***.js 能成功。直接访问对应的 https://***.js.map 不成功。就 OK 了。

能正常访问 js

不能正常请求对应的 .map 文件

注意：由于使用的服务器或工具不同，【不能正常请求对应的 .map 文件】时的错误提示页面可能不尽相同。

其他优化

设置用户信息

在获取到 user 后，调用

Sentry.setUser({
    id: userInfo.id,
    name: userInfo.name,
    email: userInfo.email,
});

这样 sentry 报错后，在 issue 详情中可以看到具体的用户信息

总结

1. 上传 sourceMap 报 Always get Invalid token (http status: 401) 错误。

对于这个问题我们可以先根据文档中 token 的生成方法，看我们生成的 token 是否正确，权限是否给够。如果都没问题，那就需要考虑一下我们生成 token 的服务器和我们上传的服务器地址是不是同一个了。

2. 配置并上传 sourceMap 后，没有正确提示出错误位置

对于这个问题，我们可以先在 Release 下面看我们是否有上传对应版本的 js 以及它对应的 .map 文件。如果没有，检查插件的 org、project、include 等参数是否配置正确。如果有，则检查一下 urlPrefix 是否配置得和真实访问的前缀一致。

3. sourceMap 只需上传到 sentry，不需要上传到线上环境

可以根据打包和发布的时机，在发布到线上前，将 sourceMap 文件删除。或者上传到服务器时，过滤掉 .map 文件。

对于上面遇见的问题，其实仔细阅读文档都可以避免。开发时，可以参考并借鉴写得比较好的同事的代码，但不能太过盲目，需要有自己的见解和想法。同时也需要在使用过后，好好地去了解一下它的具体实现。做得好，看能否做得更好。

以上如有不到之处，欢迎发消息一起交流探讨。

参考链接