feat: downgrade tech stack to stable versions and integrate GA4 error monitoring

- 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
2026-05-12 12:45:18 +08:00
parent f08874f5c4
commit 8840c4398a
24 changed files with 8567 additions and 3632 deletions
@@ -0,0 +1,448 @@
+# 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 就拥有了**企业级的错误监控能力**！🎉