📚 本方案将指导你如何在 Webpack 5 项目中集成 Sentry，实现生产环境的自动错误捕获和源码还原。

---

一、背景知识

1.1、什么是 SourceMap？

SourceMap（源代码映射）是一个用来生成源代码与构建后代码一一映射的文件的方案。

它会生成一个 xxx.map 文件，里面包含源代码和构建后代码每一行、每一列的映射关系。当构建后代码出错了，会通过 xxx.map 文件，从构建后代码出错位置找到映射后源代码出错位置，从而让浏览器提示源代码文件出错位置，帮助我们更快的找到错误根源。

---

1.2、开发环境的 SourceMap 配置

开发环境推荐使用 cheap-module-source-map：

// webpack.dev.js
module.exports = {
  mode: "development",
  devtool: "cheap-module-source-map",
};

特点	说明
✅ 优点	打包编译速度快，只包含行映射，可直接查看源码
❌ 缺点	没有列映射（不影响开发调试）

---

1.3、生产环境的 SourceMap 配置

在生产环境中，是否配置 SourceMap 取决于公司对性能、安全和调试便利性的权衡。目前主流的做法有以下几种：

方案一：配置 source-map（最常见）

大多数中大型项目的 webpack.prod.js 都会配置此选项。

// webpack.prod.js
module.exports = {
  mode: "production",
  devtool: "source-map",
};

特点：

• 打包后会生成主 JS 文件（如 main.js）和一个对应的 .map 文件
• 打包文件末尾会添加 //# sourceMappingURL=xxx.js.map 注释

优点	缺点
✅ 错误溯源方便，监控系统可利用 .map 文件还原源码行数	❌ 打包编译速度慢
✅ 主包体积不受影响，.map 文件独立，用户访问时不会下载	❌ 源码暴露风险，懂行的用户可通过控制台查看源码

//# sourceMappingURL 的核心作用：告诉浏览器去哪里下载对应的 SourceMap 文件，从而实现生产代码到开发源码的精准映射。

方案二：配置 hidden-source-map（推荐 + Sentry）

如果你既想在后台监控错误，又不希望用户在浏览器控制台看到源码，这是最佳方案。

// webpack.prod.js
module.exports = {
  mode: "production",
  devtool: "hidden-source-map",
};

特点：

• ✅ 会生成 .map 文件
• ❌ 打包后的 JS 文件结尾不会产生 //# sourceMappingURL=... 的引用注释
• 🔒 浏览器控制台不会自动关联源码，报错只显示压缩后的行数
• 📤 可将 .map 文件上传到 Sentry 等私有监控平台，实现内部调试

优势	说明
🔒 安全性	生成的 .map 文件不会在代码中引用，用户无法在浏览器控制台直接查看源码
🔐 隐私性	防止源码通过浏览器开发者工具被轻易获取，保护业务逻辑
🎯 精准定位	Sentry 服务器持有 SourceMap，可以精准还原错误位置
⚖️ 平衡性	既保证了线上代码的安全性，又能在 Sentry 后台看到详细的错误堆栈

方案三：不配置 SourceMap（极致安全）

如果项目非常敏感（比如金融、保密项目），或者是一个极简的小项目，可以选择完全不配置。

// webpack.prod.js
module.exports = {
  mode: "production",
  devtool: false,  // 或不写此配置
};

特点：

• ❌ 不生成任何映射文件
• ❌ 压缩后的代码完全无法调试
• ⚠️ 线上出 bug 只能通过”盲猜”或在本地模拟数据来复现

---

1.4、生产环境配置总结

项目类型	推荐配置	说明
中小型项目/后台管理系统	source-map	调试效率第一
大型互联网产品/C端应用	hidden-source-map + SentrySentry/私有监控	兼顾安全与调试
金融/保密项目	不配置	极致安全
个人练习项目	source-map	方便学习调试

---

1.5、hidden-source-map + Sentry 工作原理

┌─────────────────────────────────────────────────────────────┐
│                      构建阶段                                
├─────────────────────────────────────────────────────────────┤
│  源码 (main.js)  ──编译压缩──>  bundle.js + bundle.js.map 
│                                                            
│  hidden-source-map 模式：                                   
│  ✅ 生成 bundle.js.map 文件                                 
│  ❌ 不在 bundle.js 末尾添加 sourceMappingURL 注释           
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                      部署阶段                                
├─────────────────────────────────────────────────────────────┤
│  bundle.js      ──上传到服务器──>  用户访问（无源码暴露）    
│  bundle.js.map  ──上传到 Sentry──> 错误追踪时还原源码       
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                      错误发生时                              
├─────────────────────────────────────────────────────────────┤
│  用户浏览器：只能看到 bundle.js:1:23456                      
│  Sentry 后台：通过 .map 文件还原为 main.js:42:15            
└─────────────────────────────────────────────────────────────┘

---

二、准备工作

2.1、注册 Sentry 账号

访问 Sentry.io 注册账号

2.2、创建项目（Project）

选择 Browser JavaScript（根据自己项目来）

2.3、设置 Sentry SDK

2.4、获取 DSN

格式类似 https://xxxxxx@sentry.io/12345。

或者选择项目后，再鼠标放置设置图标上：

---

三、安装依赖

在项目根目录下执行：

npm install @sentry/browser
npm install @sentry/webpack-plugin --save-dev

---

四、代码集成

4.1、SDK 初始化

在入口文件（如 src/main.js）的顶部引入并初始化：

main.js

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

Sentry.init({
  dsn: "https://5fef42a12263056007b7df042b39a53b@o4510962147393536.ingest.de.sentry.io/4510962153619536",
  integrations: [
    Sentry.browserTracingIntegration(),
    Sentry.replayIntegration(),
  ],
  // 性能监控采样率
  tracesSampleRate: 1.0,
  // Session Replay 采样率
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,
});

---

五、Webpack 配置自动上传 SourceMap

这是生产环境最重要的步骤，确保 Sentry 能根据混淆代码还原源码。

webpack.prod.js

const { sentryWebpackPlugin } = require("@sentry/webpack-plugin");

module.exports = {
  mode: "production",
  devtool: "hidden-source-map", // ✨ 安全推荐：生成 map 但不添加关联注释，防止浏览器控制台泄露源码
  plugins: [
    // ... 其他插件
    sentryWebpackPlugin({
      authToken: "你的 Sentry Token",
      org: "你的组织名",
      project: "你的项目名",
      sourcemaps: {
        assets: ["./dist/**"],
        ignore: ["node_modules", "config"],
      },
    }),
  ],
};

5.1、authToken

1. 推荐使用：Personal Tokens（个人令牌）

这是最通用的选择，也是 Sentry 引导页面通常推荐的方式。

• 优点：配置最简单。在 sentryWebpackPlugin 配置中，你只需要提供一个 authToken 即可。它代表的是”你”这个开发者在 Sentry 里的权限。
• 权限要求：创建时至少勾选 project:write、project:releases 和 org:read。

2. 企业级选择：Organization Tokens（组织令牌）

这通常用于公司层面的 CI/CD 自动化流水线。

• 优点：与具体的个人账号解耦。即使某个员工离职了，只要组织令牌还在，自动化部署就不会挂掉。
• 配置差异：使用组织令牌时，有时在较老的插件版本中需要明确指定组织范围，但在最新的 sentryWebpackPlugin (v2/v5) 中，它的使用方式和 Personal Token 基本一致。

5.2、org 组织名

5.3、project 项目名

---

六、验证

在代码中手动抛出一个错误：

const sum = (...args) => {
  return args.reduce((pre, cur) => pre + cur, 0)();
};
console.log(sum(1, 2, 3, 4, 5));

执行 npm run build 打包并运行代码。片刻后，你将在 Sentry 后台看到这个错误，并且它能精准定位到 main.js 的具体行数。

配置 devtool: "hidden-source-map" 后，浏览器控制台定位不到是哪个文件哪一行报错的。

Sentry 中则可以详细看到那个文件、那一行报错：