【前端】企业级前端调试体系设计（含日志埋点 + Eruda 动态注入 + Sentry）

下面是一套可落地的"企业级前端调试体系设计"，适配技术栈（React + Vite + 管理后台 / H5 / WebView）来设计，包含：

日志埋点（可观测性基础）

Eruda 动态注入（线上临时调试）

Sentry（错误监控与追踪）

一、整体架构（核心思路）

二、分层设计

第一层：本地调试（开发阶段）

工具：

Chrome DevTools
vConsole
Eruda

目标：快速开发 + 本地排错

第二层：运行时调试（真机 / 测试环境）

能力：

动态开启 Eruda
打印关键日志
查看接口请求

第三层：线上监控（生产环境）

核心工具：

Sentry

目标：

自动捕获错误
还原用户行为
快速定位问题

三、日志体系设计（核心基础）

1.日志分级（必须有）

javascript 复制代码

export enum LogLevel {
  DEBUG = "debug",
  INFO = "info",
  WARN = "warn",
  ERROR = "error",
}

2.封装 Logger（统一出口）

javascript 复制代码

class Logger {
  static debug(...args: any[]) {
    if (import.meta.env.DEV) {
      console.log("[DEBUG]", ...args);
    }
  }

  static info(...args: any[]) {
    console.info("[INFO]", ...args);
  }

  static warn(...args: any[]) {
    console.warn("[WARN]", ...args);
  }

  static error(...args: any[]) {
    console.error("[ERROR]", ...args);

    // 上报 Sentry
    Sentry.captureException(args);
  }
}

3.自动注入上下文（非常关键）

javascript 复制代码

function withContext(data: any) {
  return {
    ...data,
    userId: getUserId(),
    orgId: getOrgId(),
    url: location.href,
    ua: navigator.userAgent,
    time: Date.now(),
  };
}

解决问题：
"报错了，但不知道是谁、在哪、怎么触发的"

四、Sentry 集成（核心能力）

初始化

javascript 复制代码

import * as Sentry from "@sentry/react";

Sentry.init({
  dsn: "YOUR_DSN",
  integrations: [],
  tracesSampleRate: 1.0,
});

2.捕获错误

javascript 复制代码

try {
  throw new Error("test error");
} catch (e) {
  Sentry.captureException(e);
}

3.React 错误边界

javascript 复制代码

import { ErrorBoundary } from "@sentry/react";

<ErrorBoundary fallback={<div>Something went wrong</div>}>
  <App />
</ErrorBoundary>

4.用户行为追踪（重点）

javascript 复制代码

Sentry.addBreadcrumb({
  category: "click",
  message: "点击提交按钮",
  level: "info",
});

可以还原用户操作路径

五、Eruda 动态注入（实战重点）

错误做法

javascript 复制代码

import "eruda";
eruda.init();

会污染生产环境

正确做法（动态开启）

方式一：URL 控制

javascript 复制代码

if (location.search.includes("debug=true")) {
  import("eruda").then((eruda) => eruda.default.init());
}

方式二：localStorage 开关（推荐）

javascript 复制代码

if (localStorage.getItem("DEBUG") === "true") {
  import("eruda").then((eruda) => eruda.default.init());
}

方式三：远程开关（企业级）

javascript 复制代码

fetch("/api/debug-config").then(res => res.json()).then(config => {
  if (config.enableEruda) {
    import("eruda").then(e => e.default.init());
  }
});

可以远程给某个用户打开调试

六、请求层监控（非常重要）

Axios 拦截器

javascript 复制代码

axios.interceptors.request.use((config) => {
  Logger.info("Request:", config);
  return config;
});

axios.interceptors.response.use(
  (res) => {
    Logger.info("Response:", res);
    return res;
  },
  (err) => {
    Logger.error("API Error:", err);
    return Promise.reject(err);
  }
);

七、性能监控（进阶）

Sentry 支持：

javascript 复制代码

Sentry.init({
  tracesSampleRate: 1.0,
});

可监控：

页面加载时间
API 耗时
慢页面

八、企业级最佳实践（重点总结）

1. 三开关机制（必须有）

javascript 复制代码

{
  enableLog: true,
  enableEruda: false,
  enableSentry: true,
}

2. 不同环境策略

环境	策略
dev	全开
test	日志 + Eruda
prod	Sentry + 可控 Eruda

3. 敏感信息过滤

javascript 复制代码

function sanitize(data: any) {
  delete data.password;
  delete data.token;
  return data;
}

4. 日志不要滥用

错误：

javascript 复制代码

console.log("进入页面");

正确：

javascript 复制代码

Logger.info("User enter dashboard", { userId });

九、一句话架构总结

Logger 负责记录 → Eruda 负责查看 → Sentry 负责监控