vue-debug-guides

vue-debug-guides skill 概览

vue-debug-guides skill 适合解决什么问题

vue-debug-guides 是一个面向 Vue 3 故障排查的 skill，重点处理运行时 bug、警告、异步加载失败、响应式异常，以及 SSR / hydration 不匹配等问题。它最适合这样的场景：你手头已经出现了异常或行为诡异的页面，需要一条比泛泛而谈的“帮我调试 Vue”更快、更有针对性的排障路径。

谁适合使用 vue-debug-guides

最适合的用户，是正在真实 Vue 3 项目里排查问题的开发者，比如遇到意外重复渲染、ref 不更新、事件处理器触发两次、异步组件加载失败、路由加载写法有误，或 DOM 时序相关问题。对于希望拿到“按问题类型给建议”而不是看大而全框架教程的团队来说，它尤其有用。

它真正解决的工作任务是什么

它要解决的并不是“从零学 Vue”。真正的任务，是把一个模糊的 bug 描述快速收敛到最可能的 Vue 特有陷阱，再用更少试错找到正确修复方式。vue-debug-guides 的价值，就在于它能把常见症状映射到具体坑点和对应修复示例。

它和普通提问有什么不同

普通 prompt 往往只能给出宽泛的调试建议。而 vue-debug-guides skill 更适合那种明显依赖 Vue 语义的问题：比如响应式规则、computed 使用约束、异步组件行为、Suspense、keep-alive、fallthrough attrs、事件修饰符、nextTick，或 script setup 的限制。这个仓库本身就是按这些典型故障模式组织的，所以输出通常会更具体，也更容易直接落地。

最值得安装的理由

安装 vue-debug-guides 最有说服力的一点，是它覆盖了许多高摩擦、又很容易从表面现象误判的边界问题。参考内容里包含不少非常实用的话题，比如异步组件错误处理、为什么 Vue Router 的路由组件不该用 defineAsyncComponent、为什么 Suspense 可能让异步组件的 loading 和 error 配置看起来“失效”，以及为什么组件 ref 会在 keep-alive 重新激活后出问题。

它不能替代什么

这个 skill 不能替代 Vue 基础学习、应用性能分析工具，也不能替代框架官方文档。如果你的需求是架构建议、代码风格约定，或泛化的“最佳实践”，仓库本身也提示了：vue-best-practices 会更适合。vue-debug-guides for Debugging 更适合你已经碰到失败、警告或难以解释的行为，需要定位并修复的时候。

如何使用 vue-debug-guides skill

vue-debug-guides 的安装方式与使用前提

在任何支持 skill 的环境中，都可以从 vuejs-ai/skills 仓库安装。常见方式是：

npx skills add vuejs-ai/skills --skill vue-debug-guides

从仓库现有信息来看，SKILL.md 里没有展示额外的内建安装命令，所以如果你是通过目录方式使用，请把它理解为“内容优先”的 skill：先装进你的 agent 环境，再配合一个具体的 Vue 调试任务去调用。

先看哪些文件最有效

先读 skills/vue-debug-guides/SKILL.md，了解“症状 -> 参考文档”的映射关系。然后再打开 reference/ 下与你问题最接近的文件。适合作为第一批阅读的包括：

• reference/async-component-error-handling.md
• reference/async-component-suspense-control.md
• reference/async-component-vue-router.md
• reference/cleanup-side-effects.md
• reference/component-ref-requires-defineexpose.md
• reference/dom-update-timing-nexttick.md
• reference/computed-no-side-effects.md
• reference/attrs-event-listener-merging.md

这个仓库的核心价值很大程度上在参考文档层，所以更适合把它当成“决策树”来用，而不是从头到尾线性阅读的一篇指南。

先把 bug 对准最接近的症状

高质量的 vue-debug-guides usage，第一步不是贴一堆代码，而是先把症状说清楚。与其问“帮我 debug 这个组件”，不如直接描述可观察到的故障：

• “Ref 在 script 里更新了，但 template 还是旧值”
• “异步路由组件始终不显示我的 loading UI”
• “Hydration warning 只在首次加载时出现”
• “包了一层按钮后，click handler 会触发两次”
• “切换 tab 后，子组件 ref 上的方法变成 undefined”

这种“症状优先”的表达，能帮助 skill 更快命中对应坑点，而不是回你一堆泛化的 Vue 建议。

要让 skill 发挥效果，你需要提供什么输入

尽量提供足够支撑 Vue 特定诊断的上下文：

• Vue 版本，以及主要生态组件：Vue Router、Pinia、SSR/Nuxt、Vite
• 问题是仅客户端出现、仅 SSR 出现，还是只在 hydration 时出现
• 最小组件代码或路由代码
• 完整警告或报错文本
• 预期行为与实际行为
• 是否涉及 Suspense、keep-alive、异步组件或 script setup

如果缺少这些信息，skill 仍然可以给出一些高概率猜测，但因为很多 Vue bug 的表面症状很像，输出质量通常会明显下降。

如何把模糊请求改成高质量 prompt

弱 prompt：

Use vue-debug-guides to debug why my Vue component is broken.

更强的 prompt：

Use vue-debug-guides to diagnose a Vue 3 issue. In a route component loaded with Vue Router, I wrapped the page in defineAsyncComponent and added loadingComponent, but the loading state never appears and navigation feels inconsistent. We use Vue Router 4 and Vite. Explain the likely mistake, show the correct route lazy-loading pattern, and tell me when Suspense would change the behavior again.

为什么这个写法更有效：它同时给出了症状、可疑 API、生态上下文，以及希望输出的结果形式。

vue-debug-guides 的实用工作流

1. 用一句话描述症状。
2. 贴出仍能复现问题的最小代码片段。
3. 让 agent 先判断最可能违反了哪条 Vue 特定规则。
4. 先要一个正确修复版本，不要一上来要五种方案。
5. 如果需要，再让它补一个简短 checklist，用于在 DevTools 或浏览器控制台验证修复。

这样能让 skill 聚焦在“诊断 + 修复”，而不是逐渐跑偏成泛泛的重构建议。

这个仓库里最值得看的参考路径

有几份参考文档对应的是最容易浪费调试时间的问题边界：

• async-component-vue-router.md：路由懒加载写法错误
• async-component-suspense-control.md：为什么 loadingComponent 和 errorComponent 看起来被忽略
• async-component-keepalive-ref-issue.md：重新激活后 ref 消失
• attrs-event-listener-merging.md：fallthrough listener 导致 click 行为重复
• computed-no-side-effects.md：computed getter 里隐藏了副作用修改
• dom-update-timing-nexttick.md：Vue 还没 flush 更新就开始读 DOM

如果你的 bug 落在这些边界附近，那么 vue-debug-guides install 往往很值得，因为普通 prompt 很容易漏掉这些细节。

能明显提升输出质量的提问技巧

让 agent 按下面三个步骤回答，效果通常最好：

1. 先点名最可能的 Vue 规则或坑点。
2. 再指出是哪一行代码或哪种模式触发了它。
3. 最后给出最小且安全的修复方案。

这种结构能有效避免又长又虚的猜测型回答，让这个 skill 更像调试助手，而不是 Vue 教程老师。

什么时候该用它，而不是一般性的 Vue 帮助

当你的 bug 大概率由框架行为引起，而不是业务逻辑本身时，就该优先用 vue-debug-guides guide。如果你的问题是“API 返回了错误数据”，这个 skill 并不是主工具；但如果问题是“watcher 莫名触发”“ref 是 undefined”“transition 卡顿”“路由组件加载行为很奇怪”，那它就非常对口。

vue-debug-guides skill 常见问题

vue-debug-guides 适合初学者吗

适合，但前提是这个初学者已经遇到了一个具体 bug。仓库里的参考内容很实用，也有较强的示例导向。不过，如果你是想从零系统学习 Vue 概念，它并不是最佳第一入口，因为这些材料是围绕“失败案例”组织的，而不是按教学顺序展开。

vue-debug-guides 最擅长覆盖哪些 bug

vue-debug-guides 最强的方向，是 Vue 3 运行时调试：响应式边界问题、computed 误用、watcher 行为、异步组件失败、DOM 更新时间点、事件与 attrs 合并，以及 keep-alive、Suspense 这类组件生命周期交互问题。

它能处理 SSR 和 hydration 问题吗

可以。skill 描述里明确包含了 SSR 和 hydration 类 bug。这一点很重要，因为 hydration 失败往往需要基于 Vue 机制本身来推断，不能只靠通用前端调试思路。你仍然应该提供完整警告文本，并说明这个不匹配是只在生产环境出现，还是只在首次渲染时出现。

它和普通提问的差别到底在哪

普通提问很容易得到“检查一下 state”这类泛泛建议。vue-debug-guides skill 的价值，在于它能命中那些已知的 Vue 坑点，例如模板顶层 ref 解包规则、同一个 tick 内的批量更新，或与普通异步组件不同的路由组件加载模式。

Vue Router 相关问题也适合用它吗

适合，尤其是当路由问题牵涉到组件加载、过渡效果或渲染时序时。仓库里有一份非常有用的参考文档，专门说明了路由组件应该直接使用动态导入，而不是套 defineAsyncComponent，这正是很多人容易混淆的地方。

什么情况下 vue-debug-guides 不太适合

如果你要处理的是 design system、应用架构、状态建模，或与 Vue 语义无关的通用 JavaScript 错误，那它就不算合适。另一个不太适用的场景是：你需要的是编码规范或工程规范，而不是调试导向的指导。

如何提升 vue-debug-guides skill 的使用效果

给 vue-debug-guides 一个可复现的症状

想更快拿到有效结果，最直接的办法就是提供最小复现。带上仍然能触发问题的最小组件、路由配置或 composable。这样 skill 才能把你的案例映射到已有参考，而不是在大代码库背景里盲猜。

明确点出涉及到哪些 Vue 特性

请说明你的代码里是否用到了：

• script setup
• defineAsyncComponent
• Suspense
• keep-alive
• Vue Router
• SSR 或 hydration
• composables、watchers 或 computed values

这些信息能迅速缩小排查范围，很多时候甚至能直接对应到某一篇参考指南。

提供原始警告文本，不要只做转述

像“Vue 好像报了个 hydration 相关的东西”这种转述，远不如完整的 console message 有用。这个 skill 是围绕一类类具体错误模式构建的，所以原始警告文本越完整，匹配越准，误修复的概率也越低。

先要诊断，再要重构

一个常见失误，是太早就要求“重写一版”。更好的 prompt 是：

Use vue-debug-guides to identify the likely Vue rule being broken here, explain why this symptom happens, and then show the smallest fix.

这种顺序通常比一开始就要求完整重构，更容易拿到干净、准确的答案。

明确写出预期行为和实际行为

不要只贴代码。请补充说明：

• 你的预期是什么
• 实际发生了什么
• 问题是稳定复现还是偶发
• 是否是在加入 Suspense 或 keep-alive 这类 Vue 特性后才出现变化

这些对比信息，能帮助 skill 区分：这到底是业务逻辑 bug，还是框架交互层面的 bug。

第一轮回答后继续迭代

如果第一轮结果已经接近，但还不够，可以继续追问更具体的条件：

• “现在假设这个组件在 <Suspense> 里面。”
• “现在把 SSR hydration 也考虑进去。”
• “现在解释一下为什么事件会触发两次。”
• “现在给我一个用 Vue DevTools 验证修复的方法。”

这是从 vue-debug-guides for Debugging 挖出更深价值的最好方式之一，同时又不会把问题范围扩得太散。

留意常见的低质量输入模式

在下面这些情况下，结果通常会变差：

• 贴了太多不相关代码
• 没有给出报错信息
• 没说明是否涉及路由或 SSR
• 一上来就问“所有可能原因”
• 把调试、重构、架构设计混在一次请求里

尽量把任务收窄。这个 skill 最适合回答“有证据、有症状、以诊断为核心”的问题。

把 reference 文件夹当成后续验证来源

当 agent 指出一个高概率原因后，最好再打开对应 markdown 文件，把你的代码与其中的 “bad” / “good” 模式对照一遍。在这个仓库里，真正有深度的信息层就在 reference/ 文件中。最佳的 vue-debug-guides guide 工作流通常是：先定位可能主题，读一篇匹配文件，应用修复，再视情况回来做第二轮更细的提问。