前端错误可观测最佳实践_前端错误提示

off999 2025-09-21 21:11 21 浏览 0 评论

场景解析

对于前端项目，生产环境的代码通常经过压缩、混淆和打包处理，当代码在运行过程中产生错误时，通常难以还原原始代码从而定位问题，对于深度混淆尤其如此，因此 Mozilla 自 2011 年开始发起并推动 Sourcemap 规范成为行业标准，用于将处理后的代码还原为原始代码，帮助开发者快速找到具体的错误文件、行号和函数，大幅缩短故障排查时间，提升问题解决效率，Webpack、Babel、TypeScript 都有相关的实现，主流浏览器也能够通过构建产物中 JS 文件末尾的 //# sourceMappingURL=xxx.map 注释加载 Sourcemap 文件。

但是暴露 Sourcemap 文件会由于原始代码泄露引起一系列的安全问题，通常会采用选择适当的 Sourcemap 类型，或者使用内部的监控工具收集错误并完成源码映射。

方案解析

观测云是一款全链路的可观测数据分析工具，支持客户端应用接入，对于错误分析，包含了前文提到的两个关键步骤，即错误收集和源码映射，这涉及到以下两类 SDK：

RUM SDK，完成 RUM 数据收集，包含对错误的收集，例如用于 WEB 应用的 @cloudcare/browser-rum；
上传 Sourcemap 的打包工具插件，作为开发依赖，将生成的源映射文件打包上传至观测云，在查看错误时将自动映射源代码，支持用于 Webpack（@cloudcare/webpack-plugin）和 Vite（@cloudcare/vite-plugin-sourcemap）的插件。

在完成两类 SDK 安装和配置后，最终的成功映射涉及两个基本的细节：

RUM 和打包上传的 Sourcemap 文件必须具有一致的环境（env）和版本（version）标签，通过 SDK 初始化配置中的 env 和 version 选项配置；
原始错误的路径必须与 Sourcemap 文件的目录结构保持一致才能成功映射，观察以下示例，假设原始报错的路径是 http://192.168.195.52:8080/js/app.5cd0447b.js:1:2979，其中 http://192.168.195.52:8080/ 是站点的根路径，js/app.5cd0447b.js 是具体报错文件的路径，则解压后的 sourcemap.zip 文件必须以相同的路径提供原始报错文件的 map 文件：prod-1.0.0/js/app.5cd0447b.js.map，其中 prod-1.0.0/ 是 SDK 中配置的环境和版本标签，js/app.5cd0447b.js.map 则对应了原始报错文件，map 文件的路径通过 SDK 初始化配置中的 filepaths 和 root 选项调整。

除去以上介绍的部分，其实还涉及一些工程方面的问题，我们将通过 vue-cli 创建一个 Vue2 示例项目来进行说明。

演示用例

创建项目

本实验使用脚手架快速生成一个示例项目：

# 安装脚手架
npm install -g @vue/cli
# 生成示例项目，选择 Default ([Vue 2] babel, eslint) 
vue create guance-demo-sourcemap-upload

为项目引入错误

在构建项目后，需要为项目添加一个手动触发错误的场景便于观察源映射的具体表现，修改项目的
src/components/HelloWorld.vue 文件，为默认页面增加一个可以抛出异常的按钮，仅列出存在变更的代码：

<template>
  <div class="hello">
    ......
    <h3>Experimental scene</h3>
    <ul>
    <li><button @click="throwError">Clicking triggers an exception</button></li>
    </ul>
    <div v-if="notificationMessage" class="notification-message">
      {{ notificationMessage }}
    </div>
  </div>
</template>

<script>
export default {
  ......
  data() {
    return {
      notificationMessage: ''
    }
  },
  methods: {
    throwError() {
      try {
        this.generateError();
      } catch (error) {
        this.notificationMessage = error.message;
        console.error('An exception has been caught:', error);
      }
    },
    generateError() {
      throw new Error('This is an exception triggered by a button click.');
    }
  }
}
</script>

<style scoped>
......
.notification-message {
  color: #f44336;
  margin-top: 10px;
  font-weight: bold;
}
</style>

修改后的界面如下，增加了一个场景按钮：

集成 RUM SDK

首先集成 RUM SDK 用于实现错误采集，SDK 的初始化选项涉及类似环境、版本这样的多 SDK 共用配置，也涉及类似 clientToken 的不适合推送至仓库的保密配置，因此我们以环境变量文件的方式存储这些配置，在项目的根目录下创建 .env.local，在脚手架生成的项目中，他们会被默认的 .gitignore 忽略，.env.local 中的内容如下：

# 应用标识，在观测云界面创建 RUM 应用时配置
VUE_APP_CLOUDCARE_APPLICATION_ID=demo_sourcemap_upload_vue2

# 统一标签
VUE_APP_CLOUDCARE_SERVICE=demo_sourcemap_upload_vue2
VUE_APP_CLOUDCARE_ENV=prod
VUE_APP_CLOUDCARE_VERSION=1.0.0

# RUM 数据上报配置，在观测云界面创建 RUM 应用时获得
VUE_APP_CLOUDCARE_SITE=https://rum-openway.guance.com
VUE_APP_CLOUDCARE_CLIENT_TOKEN=xxx

# Webpack plugin 上传 Sourcemap 配置
VUE_APP_CLOUDCARE_SERVER=https://openapi.guance.com
VUE_APP_CLOUDCARE_API_KEY=xxx

然后在项目根路径下执行 npm install @cloudcare/browser-rum 并在项目文件 src/main.js 中的 new Vue() 之前初始化 SDK，以确保更加全面的数据采集，初始化代码如下：

import Vue from 'vue'
import App from './App.vue'
import { datafluxRum } from '@cloudcare/browser-rum';

Vue.config.productionTip = false

// 在 new Vue() 之前初始化 SDK，确保更全面的数据采集
datafluxRum.init({
    applicationId: process.env.VUE_APP_CLOUDCARE_APPLICATION_ID,
    site: process.env.VUE_APP_CLOUDCARE_SITE,
    clientToken: process.env.VUE_APP_CLOUDCARE_CLIENT_TOKEN,
    env: process.env.VUE_APP_CLOUDCARE_ENV,
    version: process.env.VUE_APP_CLOUDCARE_VERSION,
    service: process.env.VUE_APP_CLOUDCARE_SERVICE,
    sessionSampleRate: 100,
    sessionReplaySampleRate: 100,
    compressIntakeRequests: true,
    trackInteractions: true,
    traceType: 'ddtrace',
    allowedTracingOrigins: [/.*/],
});
datafluxRum.startSessionReplayRecording()

new Vue({
  render: h => h(App),
}).$mount('#app')

运行项目并点击按钮触发错误将看到观测云采集的错误信息，未上传 Sourcemap 映射源码时候的原始错误如下所示，不具备可读性，无法了解具体的错误位置：

集成 Webpack Plugin 在 Build 阶段上传 Sourcemap

接下来集成上传 Sourcemap 的 SDK，这里要注意几个问题：

示例项目中开发环境运行时 Webpack 生成的文件指向本地路径，而 SDK 上传的 map 文件使用相对路径，是无法建立映射的，生产环境部署不涉及此问题，且一般来说开发环境下可以在本地快捷的查看映射后的源码，不用等待数据上传至远端后再进行分析，因此演示项目中仅在非开发环境引入该 Webpack Plugin；
演示项目默认生成 Sourcemap，因此无需进行额外的配置，如果你的项目默认没有启用，或者需要修改默认的 Sourcemap 类型，都需要增加相应的配置；
filepaths 选项决定了搜索 map 文件的路径，最终 sourcemap.zip 中的路径是 <env>-<version>/<root 选项指定的路径>/<map 文件相对 filepaths 的相对路径>，因此，sourcemap.zip 中的路径与原始错误不一致时，可以通过 filepaths 和 root 选项调整；
一般来说可以在 webpack.config.js 中配置插件，但是演示项目中的脚手架 vue-cli 包装了 webpack，因此在 vue.config.js 中配置即可；
建议将选项 logLevel 设置为 verbose，以暴露一些插件上传的细节，便于发现和排除问题；
如有需要，可以为 SDK 增加 deleteAfterUpload: true 选项，在上传后删除构建产物中的 map 文件，以提高安全性。

然后，在项目根路径下执行 npm install @cloudcare/webpack-plugin -D 并在项目文件 vue.config.js 中初始化 SDK，初始化代码如下：

const { defineConfig } = require('@vue/cli-service')
const { GuanceSourceMapUploadWebpackPlugin } = require('@cloudcare/webpack-plugin')

module.exports = defineConfig({
  transpileDependencies: true,
  configureWebpack: (config) => {
    // 为非开发环境引入 Sourcemap 上传插件
    if (process.env.NODE_ENV !== 'development') {
      config.plugins.push(
        new GuanceSourceMapUploadWebpackPlugin({
          applicationId: process.env.VUE_APP_CLOUDCARE_APPLICATION_ID,
          apiKey: process.env.VUE_APP_CLOUDCARE_API_KEY,
          server: process.env.VUE_APP_CLOUDCARE_SERVER,
          filepaths: ['dist/'],
          logLevel: 'verbose',
          root: '',
          env: process.env.VUE_APP_CLOUDCARE_ENV,
          version: process.env.VUE_APP_CLOUDCARE_VERSION,
        })
      )
    }
  }
})

执行构建后可在观测云界面看到上传成功的 sourcemap.zip：

部署项目

使用以下配置将项目部署至 Nginx：

server {
    listen  8080;
    server_name  localhost;
    location / {
        root  /usr/share/nginx/demo-sourcemap-upload-vue2/dist;
        try_files  $uri $uri/ /index.html;
        index  index.html index.htm;
    }
    error_page  500 502 503 504  /50x.html;
    location = /50x.html {
        root  /usr/share/nginx/html;
    }
}