张翔
8840c4398a
- Downgrade Next.js 16→14.2, React 19→18.3, Tailwind 4→3.4 - Add comprehensive GA4 error monitoring system - Create Jenkins CI/CD pipeline with quality gates - Fix build issues: ESLint, SWC conflict, config format - Add documentation for deployment and error tracking
449 lines
11 KiB
Markdown
449 lines
11 KiB
Markdown
# Sentry 错误监控快速接入指南（免费版）
|
||
|
||
> **适用场景**: Novalon Website 项目
|
||
> **Sentry 版本**: 免费版 (5,000 errors/month)
|
||
> **预计耗时**: 15-30 分钟
|
||
|
||
## 📋 前置条件
|
||
|
||
- ✅ Sentry 账号 (如果没有，见下方注册步骤)
|
||
- ✅ 项目已安装 `@sentry/nextjs` 依赖
|
||
- ✅ 已创建 `sentry.*.config.ts` 配置文件
|
||
|
||
## 🚀 步骤 1：注册 Sentry 免费账号（如果还没有）
|
||
|
||
### 1.1 访问 Sentry 官网
|
||
|
||
打开浏览器访问: **https://sentry.io/signup**
|
||
|
||
### 1.2 注册账号
|
||
|
||
**推荐方式（最快）**：
|
||
- 点击 "Sign up with GitHub" 或 "Sign up with Google"
|
||
- 使用你的 Gitea/GitHub 账号直接登录
|
||
|
||
**或者使用邮箱注册**：
|
||
1. 输入工作邮箱（建议用 `dev-team@novalon.cn`）
|
||
2. 设置密码
|
||
3. 验证邮箱（检查收件箱，点击验证链接）
|
||
|
||
### 1.3 创建组织（Organization）
|
||
|
||
注册成功后：
|
||
1. 进入 Dashboard
|
||
2. 点击 "Create Organization"
|
||
3. 组织名称填写: `Novalon` 或 `Novalon-Tech`
|
||
4. 选择团队类型: **Developer Team**（免费）
|
||
5. 点击 "Create Organization"
|
||
|
||
### 1.4 创建项目（Project）
|
||
|
||
在组织内创建新项目：
|
||
|
||
1. 点击 "Create Project"
|
||
2. 搜索并选择框架: **Next.js**
|
||
3. 项目名称填写: `novalon-website`
|
||
4. 团队选择: 默认团队即可
|
||
5. 点击 "Create Project"
|
||
|
||
### 1.5 获取 DSN（Data Source Name）
|
||
|
||
项目创建完成后：
|
||
|
||
1. 进入项目 → **Settings** → **Client Keys (DSN)**
|
||
2. 复制 **DSN** 值，格式如下：
|
||
```
|
||
https://examplePublicKey@o0.ingest.sentry.io/123456
|
||
```
|
||
|
||
3. **保存这个 DSN 值**，下一步会用到！
|
||
|
||
---
|
||
|
||
## ⚙️ 步骤 2：配置环境变量
|
||
|
||
### 2.1 编辑 `.env.local` 文件
|
||
|
||
在项目根目录下创建或编辑 `.env.local`：
|
||
|
||
```bash
|
||
# 复制示例配置
|
||
cp .env.example .env.local
|
||
```
|
||
|
||
编辑 `.env.local`：
|
||
|
||
```bash
|
||
# Google Analytics (如果有真实值，请替换)
|
||
NEXT_PUBLIC_GA_MEASUREMENT_ID=G-XXXXXXXXXX
|
||
|
||
# Sentry DSN (替换为你在步骤 1.5 中获取的真实 DSN)
|
||
NEXT_PUBLIC_SENTRY_DSN=https://your-real-dsn@o0.ingest.sentry.io/your-project-id
|
||
SENTRY_DSN=https://your-real-dsn@o0.ingest.sentry.io/your-project-id
|
||
|
||
# CDN 配置（可选）
|
||
CDN_DOMAIN=
|
||
```
|
||
|
||
**⚠️ 重要提醒：**
|
||
- ❌ 不要将 `.env.local` 提交到 Git！它已经在 `.gitignore` 中
|
||
- ✅ 只在本地开发环境和生产服务器上配置此文件
|
||
- 🔒 DSN 是公开的，不包含敏感信息（可以安全地用在客户端）
|
||
|
||
---
|
||
|
||
## 📦 步骤 3：安装 Sentry SDK
|
||
|
||
```bash
|
||
# 安装 @sentry/nextjs 及其依赖
|
||
npm install @sentry/nextjs @sentry/tracing
|
||
|
||
# 或者使用 pnpm（如果你用 pnpm）
|
||
pnpm add @sentry/nextjs @sentry/tracing
|
||
```
|
||
|
||
---
|
||
|
||
## 🔄 步骤 4：修改 next.config.ts 以集成 Sentry
|
||
|
||
当前你的 [next.config.ts](./next.config.ts) 需要添加 Sentry wrapper：
|
||
|
||
```typescript
|
||
import type { NextConfig } from "next";
|
||
import { withSentryConfig } from "@sentry/nextjs";
|
||
|
||
const cdnDomain = process.env.CDN_DOMAIN || '';
|
||
|
||
const nextConfig: NextConfig = {
|
||
distDir: 'dist',
|
||
output: 'export',
|
||
assetPrefix: cdnDomain || undefined,
|
||
images: {
|
||
unoptimized: true,
|
||
},
|
||
compress: true,
|
||
poweredByHeader: false,
|
||
reactStrictMode: true,
|
||
experimental: {
|
||
optimizePackageImports: ['lucide-react'],
|
||
},
|
||
compiler: {
|
||
removeConsole: process.env.NODE_ENV === 'production',
|
||
},
|
||
};
|
||
|
||
export default withSentryConfig(
|
||
nextConfig,
|
||
{
|
||
silent: true,
|
||
disableLogger: true,
|
||
hideSourceMaps: true,
|
||
// 自动上传 source maps 到 Sentry（推荐生产环境开启）
|
||
disableClientWebpackPlugin: process.env.NODE_ENV !== 'production',
|
||
disableServerWebpackPlugin: process.env.NODE_ENV !== 'production',
|
||
},
|
||
);
|
||
```
|
||
|
||
**注意**：我已经为你创建了修改后的版本，可以直接替换原文件。
|
||
|
||
---
|
||
|
||
## ✅ 步骤 5：验证 Sentry 是否正常工作
|
||
|
||
### 5.1 启动开发服务器
|
||
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
### 5.2 触发测试错误
|
||
|
||
浏览器访问以下地址之一：
|
||
|
||
```bash
|
||
# 方法 A：访问 Sentry 内置的错误页面
|
||
http://localhost:3000/sentry-example-error
|
||
|
||
# 方法 B：在浏览器控制台手动触发（更灵活）
|
||
# 打开 http://localhost:3000，然后在控制台执行：
|
||
throw new TestError('Sentry 测试错误 - 如果你能看到这条错误，说明 Sentry 工作正常！');
|
||
```
|
||
|
||
### 5.3 在 Sentry Dashboard 验证
|
||
|
||
1. 登录 https://sentry.io
|
||
2. 进入你的组织 → `novalon-website` 项目
|
||
3. 点击左侧菜单 **Issues**
|
||
4. 应该能看到刚刚触发的测试错误！
|
||
|
||
**预期结果**：
|
||
```
|
||
✅ Issues 列表中显示:
|
||
- Error Type: Error (或 TestError)
|
||
- Message: "Sentry 测试错误..."
|
||
- First Seen: 几秒钟前
|
||
- Events: 1
|
||
```
|
||
|
||
---
|
||
|
||
## 🎯 步骤 6：配置告警规则（可选但强烈推荐）
|
||
|
||
### 6.1 创建错误数量告警
|
||
|
||
1. 在 Sentry Dashboard 中，点击 **Alerts** → **Create Alert**
|
||
2. 选择 alert 类型: **"When an issue is created"** 或 **"Number of errors is high"**
|
||
3. 配置阈值：
|
||
```
|
||
Alert Type: Number of Errors
|
||
Threshold: > 10 errors in 5 minutes
|
||
Environment: production
|
||
```
|
||
4. 配置通知方式：
|
||
- **Email**: 发送到 dev-team@novalon.cn
|
||
- **Slack/DingTalk**: 如果集成了的话
|
||
5. 保存告警规则
|
||
|
||
### 6.2 创建性能退化告警（进阶）
|
||
|
||
如果你想监控 Core Web Vitals：
|
||
|
||
1. 进入 **Settings** → **Performance**
|
||
2. 开启 **Web Vitals** 监控
|
||
3. 设置阈值：
|
||
- LCP (Largest Contentful Paint): > 2.5 秒
|
||
- FID (First Input Delay): > 100 ms
|
||
- CLS (Cumulative Layout Shift): > 0.1
|
||
|
||
---
|
||
|
||
## 🛠️ 步骤 7：在生产环境中启用 Sentry
|
||
|
||
当你准备部署到生产环境时：
|
||
|
||
### 7.1 在生产服务器上配置环境变量
|
||
|
||
SSH 到你的生产服务器 (139.155.109.62)：
|
||
|
||
```bash
|
||
ssh root@139.155.109.62
|
||
|
||
# 编辑 Docker 环境变量或 .env 文件
|
||
nano /home/novalon/docker-app/.env.production
|
||
```
|
||
|
||
添加以下内容：
|
||
|
||
```bash
|
||
NODE_ENV=production
|
||
NEXT_PUBLIC_GA_MEASUREMENT_ID=你的真实GA_ID
|
||
NEXT_PUBLIC_SENTRY_DSN=你的真实SENTRY_DSN
|
||
SENTRY_DSN=你的真实SENTRY_DSN
|
||
```
|
||
|
||
### 7.2 重新构建和部署
|
||
|
||
```bash
|
||
# 回到本地开发机
|
||
./deploy-dist.sh
|
||
```
|
||
|
||
Jenkins Pipeline 会自动：
|
||
1. 运行测试
|
||
2. 构建生产版本
|
||
3. 部署到服务器
|
||
4. Sentry 开始收集生产环境的错误数据
|
||
|
||
---
|
||
|
||
## 📊 步骤 8：查看和分析错误报告
|
||
|
||
### 8.1 Issues 页面（问题列表）
|
||
|
||
进入 **Issues** 标签页，你可以看到：
|
||
|
||
| 列 | 说明 | 示例 |
|
||
|---|------|------|
|
||
| **Issue Title** | 错误标题 | TypeError: Cannot read property 'x' of undefined |
|
||
| **First Seen** | 首次发生时间 | 2 hours ago |
|
||
| **Events** | 发生次数 | 23 users, 45 events |
|
||
| **Users Affected** | 影响用户数 | 23 users |
|
||
| **Level** | 严重程度 | error / warning / info |
|
||
|
||
### 8.2 Performance 页面（性能监控）
|
||
|
||
如果你的应用开启了性能监控：
|
||
|
||
- **Transaction**（事务）：每个页面加载的详细耗时
|
||
- **Span**（时间跨度）：具体操作的时间分解
|
||
- **Web Vitals**：LCP、FID、CLS 的趋势图
|
||
|
||
### 8.3 Releases 页面（版本追踪）
|
||
|
||
每次部署后，Sentry 会自动关联到 Git commit：
|
||
|
||
```
|
||
Release: v1.0.0-stable
|
||
Commit: abc1234 (feat: downgrade to stable stack)
|
||
Deploy Time: 2026-05-12 14:30:00
|
||
Errors: 0 (or X if any)
|
||
```
|
||
|
||
---
|
||
|
||
## 💡 高级用法（按需启用）
|
||
|
||
### #1：标记用户身份（提升错误排查效率）
|
||
|
||
在你的业务代码中（如用户登录后）：
|
||
|
||
```typescript
|
||
import * as Sentry from '@sentry/nextjs';
|
||
|
||
// 当用户登录后
|
||
Sentry.setUser({
|
||
id: user.id,
|
||
email: user.email,
|
||
segment: 'premium', // or 'free'
|
||
});
|
||
```
|
||
|
||
**收益**：当某个用户报错时，你可以直接看到是哪个用户遇到的问题。
|
||
|
||
### #2：附加自定义上下文（业务相关信息）
|
||
|
||
```typescript
|
||
// 在关键操作中添加上下文
|
||
Sentry.setContext('order', {
|
||
orderId: 'ORD-20260512-001',
|
||
amount: 999,
|
||
product: 'Enterprise License',
|
||
});
|
||
|
||
// 如果这里出错，Sentry 会自动附带这些信息
|
||
```
|
||
|
||
### #3：手动捕获特定错误
|
||
|
||
```typescript
|
||
try {
|
||
const response = await fetch('/api/contact');
|
||
if (!response.ok) {
|
||
throw new Error(`Contact form submission failed: ${response.status}`);
|
||
}
|
||
} catch (error) {
|
||
// 手动发送到 Sentry，并附加额外信息
|
||
Sentry.captureException(error, {
|
||
tags: { feature: 'contact-form' },
|
||
extra: { formData: { name, email, subject } },
|
||
});
|
||
}
|
||
```
|
||
|
||
### #4：设置面包屑导航（Breadcrumbs）—— 记录用户操作路径
|
||
|
||
Sentry 会自动记录：
|
||
- UI 交互（click、input、keypress）
|
||
- 导航变化（URL 变化）
|
||
- Console 日志
|
||
- HTTP 请求（XHR/Fetch）
|
||
- DOM 变化
|
||
|
||
你还可以手动添加：
|
||
|
||
```typescript
|
||
Sentry.addBreadcrumb({
|
||
category: 'ui',
|
||
message: 'User clicked "Submit" on contact form',
|
||
level: 'info',
|
||
});
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 故障排除
|
||
|
||
### 问题 1：Sentry Dashboard 看不到任何错误
|
||
|
||
**可能原因及解决方案**：
|
||
|
||
| 原因 | 解决方案 |
|
||
|------|---------|
|
||
| DSN 未正确配置 | 检查 `.env.local` 中的 `NEXT_PUBLIC_SENTRY_DSN` 是否有值 |
|
||
| 环境变量未生效 | 重启开发服务器 (`npm run dev`) |
|
||
| `enabled: false` 在开发环境 | 检查 `sentry.client.config.ts` 中的 `enabled` 条件 |
|
||
| 网络问题 | 检查是否能访问 `o0.ingest.sentry.io` |
|
||
|
||
**调试方法**：
|
||
```typescript
|
||
// 在 sentry.client.config.ts 中临时添加
|
||
console.log('[Sentry] DSN:', SENTRY_DSN);
|
||
console.log('[Sentry] Enabled:', process.env.NODE_ENV !== 'development');
|
||
```
|
||
|
||
### 问题 2：Source Maps 未上传
|
||
|
||
**现象**：Sentry 显示的错误堆栈是压缩后的代码，难以阅读。
|
||
|
||
**解决方案**：
|
||
|
||
1. 安装 `@sentry/webpack-plugin`：
|
||
```bash
|
||
npm install --save-dev @sentry/webpack-plugin
|
||
```
|
||
|
||
2. 在 `next.config.ts` 中配置：
|
||
```typescript
|
||
export default withSentryConfig(
|
||
nextConfig,
|
||
{
|
||
silent: true,
|
||
hideSourceMaps: false, // 改为 false
|
||
// 其他配置...
|
||
},
|
||
{
|
||
include: './dist/**',
|
||
ignore: ['node_modules'],
|
||
urlPrefix: '~/_next',
|
||
}
|
||
);
|
||
```
|
||
|
||
### 问题 3：免费额度超限
|
||
|
||
**Sentry 免费版限制**：
|
||
- 每月 5,000 个错误事件
|
||
- 保留 30 天的数据
|
||
- 5 个团队成员
|
||
|
||
**如果超限**：
|
||
1. 升级到 Developer 版本 ($26/月，50,000 errors/month)
|
||
2. 或者优化错误过滤（减少噪音）
|
||
3. 或者在 `ignoreErrors` 中添加更多模式
|
||
|
||
---
|
||
|
||
## 📚 相关文档链接
|
||
|
||
- **Sentry 官方文档**: https://docs.sentry.io/platforms/javascript/guides/nextjs/
|
||
- **Next.js 集成指南**: https://docs.sentry.io/platforms/javascript/guides/nextjs/
|
||
- **最佳实践**: https://docs.sentry.io/product/best-practices/event-grouping/
|
||
|
||
---
|
||
|
||
## ✅ 接入完成清单
|
||
|
||
请逐项确认：
|
||
|
||
- [ ] 已注册 Sentry 账号并创建项目
|
||
- [ ] 已获取 DSN 并配置到 `.env.local`
|
||
- [ ] 已安装 `@sentry/nextjs` 和 `@sentry/tracing`
|
||
- [ ] 已修改 `next.config.ts` 添加 `withSentryConfig`
|
||
- [ ] 已运行 `npm run dev` 并访问 `/sentry-example-error`
|
||
- [ ] 已在 Sentry Dashboard 看到测试错误
|
||
- [ ] （可选）已配置告警规则
|
||
- [ ] （可选）已部署到生产环境并验证
|
||
|
||
全部完成后，你的 Novalon Website 就拥有了**企业级的错误监控能力**！🎉
|