【前端定位线上问题的多种方案（不依赖 Sentry）】

news2025/2/26 17:37:24

前端定位线上问题的多种方案（不依赖 Sentry） 🛠️

一、构建时注入调试信息 🔧

1. 注入版本信息与 Git 提交哈希

Webpack 配置：

// webpack.config.js
const webpack = require('webpack');
const gitRevision = require('child_process').execSync('git rev-parse --short HEAD').toString().trim();

module.exports = {
  plugins: [
    new webpack.DefinePlugin({
      __VERSION__: JSON.stringify(`v1.0.0-${gitRevision}`)
    })
  ]
};

代码中使用：

console.log('当前版本：', __VERSION__);
// 输出：当前版本：v1.0.0-3a5b7d9e

优势：

精准定位代码版本，结合 Git 历史快速回溯问题
无需第三方工具，纯前端实现

2. 生成 Source Map 并选择性部署

Webpack 生产配置：

// webpack.config.js
module.exports = {
  devtool: 'hidden-source-map', // 生成 Source Map 但不暴露给浏览器
  output: {
    sourceMapFilename: '[file].map[query]'
  }
};

调试流程：

构建时生成 .map 文件，但不上传至 CDN
报错时通过行号/列号（如 main.js:123:45）

本地使用 source-map 库解析错误位置：

npx source-map analyze main.js.map --line 123 --column 45

优势：

安全：不暴露源码到生产环境
精准：还原压缩代码到源码位置

二、浏览器端主动捕获与上报 🌐

1. 全局错误监听

基础代码：

window.addEventListener('error', (e) => {
  const errorInfo = {
    msg: e.message,
    file: e.filename,
    line: e.lineno,
    col: e.colno,
    stack: e.error?.stack,
    version: __VERSION__ // 构建时注入的版本
  };
  
  // 上报到自有API
  fetch('/api/log-error', {
    method: 'POST',
    body: JSON.stringify(errorInfo)
  });
});

增强方案（Promise 错误）：

window.addEventListener('unhandledrejection', (e) => {
  console.error('Unhandled Rejection:', e.reason);
});

2. Console 日志重定向

捕获所有 console.log：

const originalConsoleLog = console.log;
console.log = (...args) => {
  originalConsoleLog(...args); // 保持原功能
  sendToServer('log', args); // 自定义上报
};

三、动态调试模式开关 🔌

1. URL 参数控制调试模式

代码示例：

const urlParams = new URLSearchParams(location.search);
const debugMode = urlParams.has('debug');

if (debugMode) {
  localStorage.setItem('debug', 'true'); // 持久化调试状态
  console.log('调试模式已开启');
}

// 根据调试模式加载不同资源
if (debugMode) {
  import('./src/dev-tools.ts'); // 加载调试工具
}

安全措施：

后端校验参数权限（如特定IP或Token）
生产环境默认隐藏调试入口

2. 环境变量区分构建模式

Vite 配置：

// vite.config.js
export default defineConfig(({ mode }) => ({
  define: {
    __DEBUG__: mode === 'development' // 开发模式下启用调试
  }
}));

代码中使用：

if (__DEBUG__) {
  console.log('当前为调试模式，敏感操作已禁用');
}

四、本地 Source Map 调试方案 🔍

1. 浏览器直接关联本地源码

步骤：

构建时生成 source-map
在 Chrome DevTools 中配置：
- 打开 Sources 面板 → Overrides
- 映射网络资源到本地文件系统

效果：

2. VS Code 调试生产代码

配置 .vscode/launch.json：

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "chrome",
      "request": "launch",
      "name": "Debug Production",
      "url": "http://localhost:3000?debug",
      "webRoot": "${workspaceFolder}/src",
      "sourceMaps": true,
      "sourceMapPathOverrides": {
        "webpack:///./*": "${webRoot}/*"
      }
    }
  ]
}

五、方案对比与选型建议 📊

方案	适用场景	优点	缺点
构建注入版本	所有项目	无第三方依赖，快速定位版本	需自行实现错误收集
Source Map 解析	需要精准定位生产错误	安全可靠，还原源码位置	需手动管理 .map 文件
全局错误捕获	自有错误监控系统	完全可控，数据私有	需后端支持，开发成本较高
动态调试模式	紧急问题排查	灵活开关，不影响普通用户	存在安全风险，需严格权限控制
浏览器 Overrides	前端开发者本地调试	直接修改生产代码，实时生效	仅限本地使用，无法团队协作