登录
Sentry 错误监控系统
2026年1月28日 14:30
Vue2 项目从零搭建免费 Sentry 错误监控系统完整指南
老 Vue2 项目搭建免费的 Sentry 错误监控系统，从注册账号到最终使用的全部步骤。
第一部分：注册 Sentry 账号
1. 访问 Sentry 官网
打开浏览器，访问 sentry.io/signup/
2. 注册账号
有以下几种注册方式：
- GitHub 账号登录（推荐，最快捷）
- Google 账号登录
- 邮箱注册
💡 免费套餐说明：Sentry 免费版每月支持 5,000 个错误事件，对于个人项目或小型团队完全够用。
3. 完成注册流程
- 选择登录/注册方式
- 填写组织名称（Organization Name），例如：
my-company - 确认邮箱（如果是邮箱注册）
第二部分：创建 Sentry 项目并获取 DSN
1. 创建新项目
登录后，进入 Sentry 控制台：
- 点击左侧菜单 "Projects"
- 点击右上角 "Create Project" 按钮
- 在平台列表中选择 "Vue"
- 设置告警规则（Alert Settings）：
- 选择 "Alert me on every new issue"（推荐新手）
- 或者选择自定义规则
- 输入项目名称，例如：
my-vue2-app - 选择团队（如果有多个团队）
- 点击 "Create Project"
2. 获取 DSN（数据源名称）
项目创建成功后，系统会自动跳转到配置页面，显示你的 DSN。
如果错过了这个页面，可以通过以下方式找到 DSN：
- 进入项目 → Settings（设置）
- 左侧菜单选择 Client Keys (DSN)
- 复制 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
- 打开浏览器访问项目
- 点击测试按钮触发错误
- 打开浏览器开发者工具（F12），查看 Network 标签
- 你应该能看到发送到
sentry.io的请求
3. 在 Sentry 控制台查看错误
- 登录 sentry.io
- 进入你的项目
- 点击左侧 "Issues" 菜单
- 你应该能看到刚才触发的测试错误
💡 错误通常会在几秒钟内出现在 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
- 登录 Sentry
- 进入 Settings → Account → API → Auth Tokens
- 点击 Create New Token
- 勾选
project:releases和org:read权限 - 复制生成的 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 错误监控系统。当用户在使用你的应用时遇到错误，你可以：
- ✅ 实时收到错误通知
- ✅ 查看完整的错误堆栈和上下文
- ✅ 了解错误影响的用户数量
- ✅ 追踪用户操作路径（面包屑）
- ✅ 关联代码版本定位问题
