Sentry 错误监控系统

小小小小宇
26 阅读5分钟

Vue2 项目从零搭建免费 Sentry 错误监控系统完整指南

老 Vue2 项目搭建免费的 Sentry 错误监控系统，从注册账号到最终使用的全部步骤。

第一部分：注册 Sentry 账号

1. 访问 Sentry 官网

打开浏览器，访问 sentry.io/signup/

2. 注册账号

有以下几种注册方式：

  • GitHub 账号登录（推荐，最快捷）
  • Google 账号登录
  • 邮箱注册

💡 免费套餐说明：Sentry 免费版每月支持 5,000 个错误事件，对于个人项目或小型团队完全够用。

3. 完成注册流程

  1. 选择登录/注册方式
  2. 填写组织名称（Organization Name），例如：my-company
  3. 确认邮箱（如果是邮箱注册）

第二部分：创建 Sentry 项目并获取 DSN

1. 创建新项目

登录后，进入 Sentry 控制台：

  1. 点击左侧菜单 "Projects"
  2. 点击右上角 "Create Project" 按钮
  3. 在平台列表中选择 "Vue"
  4. 设置告警规则（Alert Settings）：
    • 选择 "Alert me on every new issue"（推荐新手）
    • 或者选择自定义规则
  5. 输入项目名称，例如：my-vue2-app
  6. 选择团队（如果有多个团队）
  7. 点击 "Create Project"

2. 获取 DSN（数据源名称）

项目创建成功后，系统会自动跳转到配置页面，显示你的 DSN。

如果错过了这个页面，可以通过以下方式找到 DSN：

  1. 进入项目 → Settings（设置）
  2. 左侧菜单选择 Client Keys (DSN)
  3. 复制 DSN，格式类似： 
    https://xxxxxxxxxxxxxxxx@o123456.ingest.sentry.io/1234567

⚠️ 重要：DSN 是你项目的唯一标识，请妥善保管，不要泄露到公开的代码仓库中。

第三部分：在 Vue2 项目中安装 Sentry SDK

1. 安装依赖包

在你的 Vue2 项目根目录下执行：

# 使用 npm
npm install @sentry/vue@5 @sentry/tracing@5 --save

# 或使用 yarn
yarn add @sentry/vue@5 @sentry/tracing@5

⚠️ Vue2 必须使用 @sentry/vue@5 版本，@sentry/vue@7+ 版本只支持 Vue3。

2. 确认安装成功

查看 package.json，确保依赖已添加：

{
  "dependencies": {
    "@sentry/vue": "^5.x.x",
    "@sentry/tracing": "^5.x.x"
  }
}

第四部分：配置 Sentry 初始化代码

1. 修改入口文件 src/main.js

import Vue from 'vue'
import App from './App.vue'
import router from './router' // 如果你使用了 vue-router

// 引入 Sentry
import * as Sentry from '@sentry/vue'
import { Integrations } from '@sentry/tracing'

// 初始化 Sentry（必须在 new Vue() 之前）
Sentry.init({
  Vue,
  dsn: 'https://你的DSN@o123456.ingest.sentry.io/1234567', // 替换为你的 DSN
  integrations: [
    new Integrations.BrowserTracing({
      routingInstrumentation: Sentry.vueRouterInstrumentation(router),
      tracingOrigins: ['localhost', 'your-domain.com', /^\//]
    })
  ],
  // 性能监控采样率（1.0 = 100%，生产环境建议设置 0.1-0.2）
  tracesSampleRate: 1.0,
  // 环境标识
  environment: process.env.NODE_ENV || 'development',
  // 在控制台也输出错误（开发时有用）
  logErrors: true
})

Vue.config.productionTip = false

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

2. 如果没有使用 vue-router 的简化配置

import Vue from 'vue'
import App from './App.vue'
import * as Sentry from '@sentry/vue'

Sentry.init({
  Vue,
  dsn: 'https://你的DSN@o123456.ingest.sentry.io/1234567',
  tracesSampleRate: 1.0,
  environment: process.env.NODE_ENV || 'development',
  logErrors: true
})

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

第五部分：使用环境变量管理 DSN（推荐）

为了安全起见，建议使用环境变量管理 DSN。

1. 创建环境变量文件

在项目根目录创建 .env 文件：

# .env.development（开发环境）
VUE_APP_SENTRY_DSN=https://开发环境的DSN

# .env.production（生产环境）
VUE_APP_SENTRY_DSN=https://生产环境的DSN

2. 修改 main.js 使用环境变量

Sentry.init({
  Vue,
  dsn: process.env.VUE_APP_SENTRY_DSN,
  // ... 其他配置
})

3. 将 .env 文件添加到 .gitignore

# .gitignore
.env
.env.local
.env.*.local

第六部分：测试 Sentry 是否正常工作

1. 添加测试按钮

在任意组件中添加一个测试按钮，例如 App.vue：

<template>
  <div id="app">
    <h1>Sentry 测试</h1>
    <button @click="throwTestError">触发测试错误</button>
    <button @click="throwTypeError">触发类型错误</button>
  </div>
</template>

<script>
export default {
  name: 'App',
  methods: {
    throwTestError() {
      throw new Error('这是一个 Sentry 测试错误！')
    },
    throwTypeError() {
      // 故意访问未定义变量的属性
      const obj = undefined
      console.log(obj.property)
    }
  }
}
</script>

2. 运行项目并测试

npm run serve
  1. 打开浏览器访问项目
  2. 点击测试按钮触发错误
  3. 打开浏览器开发者工具（F12），查看 Network 标签
  4. 你应该能看到发送到 sentry.io 的请求

3. 在 Sentry 控制台查看错误

  1. 登录 sentry.io
  2. 进入你的项目
  3. 点击左侧 "Issues" 菜单
  4. 你应该能看到刚才触发的测试错误

💡 错误通常会在几秒钟内出现在 Sentry 控制台中。

第七部分：高级配置（可选但推荐）

1. 捕获 API 请求错误

如果你使用 axios，可以添加拦截器：

// src/utils/request.js
import axios from 'axios'
import * as Sentry from '@sentry/vue'

const service = axios.create({
  baseURL: process.env.VUE_APP_API_URL,
  timeout: 10000
})

// 响应拦截器
service.interceptors.response.use(
  response => response,
  error => {
    // 将 API 错误发送到 Sentry
    Sentry.captureException(error)
    
    // 添加额外上下文信息
    Sentry.setContext('api_error', {
      url: error.config?.url,
      method: error.config?.method,
      status: error.response?.status,
      data: error.response?.data
    })
    
    return Promise.reject(error)
  }
)

export default service

2. 添加用户信息（用于追踪特定用户的问题）

// 用户登录成功后调用
import * as Sentry from '@sentry/vue'

function onUserLogin(user) {
  Sentry.setUser({
    id: user.id,
    username: user.username,
    email: user.email // 可选，注意隐私保护
  })
}

// 用户登出时清除
function onUserLogout() {
  Sentry.setUser(null)
}

3. 使用 Vue 错误边界捕获组件错误

// 在 main.js 中添加全局错误处理
Vue.config.errorHandler = (err, vm, info) => {
  Sentry.captureException(err, {
    extra: {
      componentName: vm?.$options?.name,
      propsData: vm?.$options?.propsData,
      lifecycleHook: info
    }
  })
}

4. 手动捕获错误和消息

import * as Sentry from '@sentry/vue'

// 捕获异常
try {
  riskyOperation()
} catch (error) {
  Sentry.captureException(error)
}

// 发送自定义消息
Sentry.captureMessage('用户完成了重要操作', 'info')

// 添加面包屑（用于追踪用户操作路径）
Sentry.addBreadcrumb({
  category: 'user-action',
  message: '用户点击了购买按钮',
  level: 'info'
})

5. 配置不同环境的采样率

// src/config/sentry.js
export const sentryConfig = {
  development: {
    tracesSampleRate: 1.0,  // 开发环境 100% 采样
    debug: true
  },
  production: {
    tracesSampleRate: 0.2,  // 生产环境 20% 采样（节省配额）
    debug: false
  }
}

第八部分：Source Maps 配置（用于定位压缩代码）

生产环境的代码经过压缩后，错误堆栈很难阅读。上传 Source Maps 可以让 Sentry 显示原始代码位置。

1. 安装 Sentry CLI

npm install @sentry/cli --save-dev

2. 创建 .sentryclirc 配置文件

在项目根目录创建 .sentryclirc：

[defaults]
url = https://sentry.io
org = 你的组织名
project = 你的项目名

[auth]
token = 你的AuthToken

3. 获取 Auth Token

  1. 登录 Sentry
  2. 进入 Settings → Account → API → Auth Tokens
  3. 点击 Create New Token
  4. 勾选 project:releases 和 org:read 权限
  5. 复制生成的 Token

4. 在构建时上传 Source Maps

修改 package.json：

{
  "scripts": {
    "build": "vue-cli-service build",
    "postbuild": "sentry-cli releases files $npm_package_version upload-sourcemaps ./dist/js --url-prefix '~/js'"
  }
}

第九部分：Sentry 控制台功能介绍

Issues（问题列表）

  • 查看所有捕获的错误
  • 按频率、影响用户数排序
  • 标记问题状态（已解决/忽略）

Performance（性能监控）

  • 页面加载时间
  • API 请求耗时
  • 性能瓶颈分析

Alerts（告警设置）

  • 设置错误阈值告警
  • 配置邮件/Slack/钉钉通知

Releases（版本管理）

  • 关联代码版本
  • 追踪哪个版本引入了问题

第十部分：常见问题排查

问题解决方案
控制台没有收到错误检查 DSN 是否正确；确保网络能访问 sentry.io
错误信息不完整确认 SDK 版本正确（Vue2 用 v5）
Source Map 不生效检查 release 版本是否匹配；确认上传成功
免费额度用完降低 tracesSampleRate 采样率；或升级套餐

完整配置示例

最终的 src/main.js 完整代码：

import Vue from 'vue'
import App from './App.vue'
import router from './router'
import * as Sentry from '@sentry/vue'
import { Integrations } from '@sentry/tracing'

// 仅在有 DSN 时初始化 Sentry
if (process.env.VUE_APP_SENTRY_DSN) {
  Sentry.init({
    Vue,
    dsn: process.env.VUE_APP_SENTRY_DSN,
    integrations: [
      new Integrations.BrowserTracing({
        routingInstrumentation: Sentry.vueRouterInstrumentation(router),
        tracingOrigins: ['localhost', /^\//]
      })
    ],
    tracesSampleRate: process.env.NODE_ENV === 'production' ? 0.2 : 1.0,
    environment: process.env.NODE_ENV,
    release: process.env.VUE_APP_VERSION || '1.0.0',
    logErrors: process.env.NODE_ENV === 'development'
  })
}

// 全局错误处理
Vue.config.errorHandler = (err, vm, info) => {
  console.error('Vue Error:', err)
  Sentry.captureException(err, {
    extra: { componentName: vm?.$options?.name, info }
  })
}

Vue.config.productionTip = false

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

总结

完成以上步骤后，你的 Vue2 项目就已经成功接入了 Sentry 错误监控系统。当用户在使用你的应用时遇到错误，你可以：

  1. ✅ 实时收到错误通知
  2. ✅ 查看完整的错误堆栈和上下文
  3. ✅ 了解错误影响的用户数量
  4. ✅ 追踪用户操作路径（面包屑）
  5. ✅ 关联代码版本定位问题
avatar
文章
阅读
粉丝