{T}

生产报错定位与 SourceMap 调试

概述

生产环境报错最怕“只看到控制台红字，却不知道哪个组件炸了”。本节先用 app.config.errorHandler 把错误上下文打全、锁定出错组件，再临时打开 build.sourcemap 把报错映射回源码位置，结合“图表仍能渲染但控制台报错”的现象，反推出 vue-echarts 的按需 use() 注册逻辑在生产环境已失去必要性，并用 mode !== "production" 把它裁掉。最后强调调试能力应按需打开、不长期污染生产构建。

学习目标

  • 能用 app.config.errorHandler 统一捕获并打印错误、组件实例与附加信息。
  • 理解 build.sourcemap 如何从“组件级定位”走向“源码级定位”。
  • 能从“报错存在但功能仍在”的现象，判断问题在附加链路而非主链路。
  • 掌握用 mode !== "production" 把开发态才需要的初始化逻辑从生产产物中裁掉。
  • 建立“调试能力按需开、不常驻生产包”的工程边界意识。

一、先统一接住错误，打出组件上下文

生产构建里控制台报错但看不出是哪个组件导致的，如果只盯压缩后的报错信息很难排。第一步是在 main.ts 挂 app.config.errorHandler，把三类信息一起打出来：捕获到的错误对象、当前组件实例、附带的错误信息上下文。

ts
const app = createApp(App)

app.config.errorHandler = (err, instance, info) => {
  console.error("捕获到错误:", err)
  console.error("组件实例:", instance)
  console.error("附加信息:", info)
}

有了组件实例，才能顺着 target、生命周期钩子、组件名去缩小范围。统一错误捕获不是最终方案，但它是定位生产 bug 的第一层抓手，重点不是优雅上报，而是先把错误上下文打全。

二、build.sourcemap 映射回源码位置

errorHandler 解决的是组件级定位，但你还需要代码级定位。打开 vite.config.ts 里的 build.sourcemap 后，浏览器报错不再只指向压缩后的 bundle，而能回映射到某个 .vue、某一行、某个具体方法。

ts
export default defineConfig({
  build: {
    sourcemap: true,
  },
})

sourcemap: true 更适合调试阶段而非长期默认开启，因为它会增加构建产物并暴露源码结构。这一步的关键在于“只在定位生产 bug 时临时开启”。

三、从“报错但功能仍在”反推冗余逻辑

课程里 vue-echarts 的 use() 注册逻辑在控制台报错，但图表页面仍然能正常渲染。这个现象很关键：说明 option 本身能被正确初始化和渲染，出问题的不是图表“不能画”，而是某个附加步骤在生产环境已不成立。

顺着这个现象往下想：既然生产环境已经通过 CDN 全量引入了 echarts，那么 vue-echarts 里那段“按需 use() 注册图表和组件”的逻辑，在生产环境下其实已经没有存在必要了。这是一种“从现象倒推机制”的排错方法。

text
现象：
  use() 报错
  图表仍然正常显示

推论：
  报错不在 option 初始化
  而在按需注册阶段

四、用 mode 条件裁剪开发态注册逻辑

最终修复看似“离谱”但逻辑成立：开发模式保留 onBeforeMount 里的按需 use()，生产模式直接跳过整段逻辑。

  • 开发模式：没有全局 CDN 版 echarts，必须按需注册用到的图表、组件和特性；
  • 生产模式：echarts 已通过 CDN 全量导入，按需 use() 反而会因模块路径与 external 策略冲突而报错。

所以不是“修 use() 公式”，而是让它在不需要时根本不进入构建产物。

ts
if (import.meta.env.MODE !== "production") {
  onBeforeMount(() => {
    // 仅开发模式执行按需 use()
    // use([charts, components, features])
  })
}

这套逻辑必须建立在“生产环境已全量引入 echarts”的前提上，若未来改回本地按需打包，就不能继续无脑跳过。

五、排错方法论比最终代码更值得记住

本文最值得保留的不是最后那句 if (mode !== "production")，而是整个排查路径：先用 errorHandler 锁定出错组件；再开 sourcemap 锁定源码位置；在开发模式打印比对关键变量；观察“报错存在但功能还在”的现象；反推某些逻辑在当前环境是否冗余。

真正高质量的修复通常来自完整排查路径，而不是拍脑袋猜。“功能没坏但控制台报错”这类问题，很适合优先考虑环境差异。

六、调试能力按需开、不常驻

sourcemap 打开后会产生一堆 .map 文件，暴露源码结构，长期开着既不安全也增加产物负担；统一错误打印这类调试逻辑也不一定适合长在最终线上产物里。建议：调试生产 bug 时临时打开，定位完成后收回。

ts
build: {
  sourcemap: process.env.SOURCE_MAP === "true",
}

这和前面 visualizer 的处理思路一致：调试能力按需开，不是永久默认开。任何调试型能力都值得考虑按环境变量单独打开。

七、external 越多，越要意识到开发态与生产态初始化已分叉

这一节表面在修一个 vue-echarts 报错，背后其实点出了一个更大的工程现实：当项目开始大量 external 第三方库，开发态和生产态加载依赖的方式会越来越不一样。

  • 开发态：没有全局 CDN 版库，组件内部往往要按需注册、本地引入；
  • 生产态：库已被 CDN 全量注入，某些“按需注册”逻辑反而成了冗余甚至报错源。

所以组件内部不能再默认“所有环境的初始化链路都一样”。external 做得越多，越要回头检查组件里那些依赖加载、注册、初始化的代码，确认它们是否按 mode 分了环境。构建优化和组件内部初始化策略，到这一节才算真正联动起来——这也是前面所有 CDN external 工作的自然延伸。

常见问题

问题原因解决方案
生产报错但看不出哪个组件炸了只看到 bundle 报错，没有组件上下文在 main.ts 挂 app.config.errorHandler 打印错误、实例和附加信息
知道组件报错但定位不到源码压缩后代码不可读临时打开 build.sourcemap，通过浏览器堆栈映射回源码
vue-echarts 报错但图表还能显示出错的是按需注册链路，非 option 初始化先验证运行现象，再判断是否属于环境差异导致的冗余逻辑
为什么开发需 use() 生产却不需要生产已通过 CDN 全量导入 echarts用 mode !== "production" 把按需注册限制在开发态
SourceMap 长期开着可以吗会暴露源码结构并增加产物只在调试模式通过环境变量临时开启
external 后同一库不同环境行为不一致开发态与生产态依赖加载策略已不同开始按环境思考组件初始化路径，不要假设所有环境都一样

延伸阅读