hyf0/vue-debug-guides

vue-debug-guides 是做什么的？

Vue 3 调试与错误处理指南，涵盖运行时错误、警告、异步失败以及 SSR/水合问题。适用于诊断或修复 Vue 相关问题。

概述

本指南专注于 Vue 3 应用中的常见错误类型及调试方法。无论您遇到的是组件渲染错误、异步操作问题，还是 SSR 水合不匹配，这里都提供了系统化的排查思路和实用技巧。

常见错误类型

运行时错误

• 组件渲染过程中抛出的异常
• 计算属性或侦听器中未捕获的错误
• 模板语法错误

警告信息

• 数据未定义或类型不匹配
• 缺少 key 属性
• 生命周期钩子使用不当

异步失败

• async setup() 中的异常
• Promise 未捕获的拒绝
• 事件处理器中的错误

SSR/水合问题

• 客户端与服务端 DOM 不匹配
• 水合过程中数据不一致
• 第三方库在 SSR 环境下的兼容性

调试策略

全局错误处理

使用 app.config.errorHandler 捕获所有未处理的错误：

app.config.errorHandler = (err, instance, info) => {
  console.error('全局错误:', err, instance, info)
  // 发送到日志服务
}

开发环境调试

• 启用 Vue Devtools 进行组件树和状态检查
• 在 Chrome DevTools 中设置 breakpoint
• 使用 console.warn 替代 alert 进行调试

生产环境处理

• 区分开发和生产环境错误提示
• 使用错误追踪服务（如 Sentry）
• 避免在控制台暴露敏感信息

平台支持

• Vue 3（支持 Options API 和 Composition API）
• Vite 开发服务器
• Nuxt 3 SSR 应用
• 所有现代浏览器

使用建议

1. 遇到错误时，先确认环境（开发/生产）
2. 检查控制台完整的错误堆栈
3. 使用 Vue Devtools 定位组件实例
4. 隔离问题代码，编写最小复现案例
5. 参考 Vue 官方文档中的错误处理章节

---

本指南根据 Vue 3 官方文档和社区最佳实践编写。