这个 skill 是否覆盖 Nuxt 的 SSR、路由与数据获取？

不覆盖。Nuxt 自身那一层（自动导入、useFetch、服务端路由）由独立的 nuxt skill 处理；本 skill 直接覆盖 Vue 3、Vue Router 和 Pinia。

能否协助处理 Vite 构建配置？

不能。Vite 插件与构建配置不在范围内，相关问题请使用 vite skill。

宏的推荐按哪个 Vue 版本划线？

defineSlots 与泛型组件需要 3.3+，defineModel 需要 3.4+，useTemplateRef、useId、onWatcherCleanup 以及 reactive props 解构需要 3.5+。不存在的宏会编译为空、运行时报未定义标识符，所以推荐前应先核对 package.json 中的版本。

文档

Vue

针对 Vue 3 响应式、组件、路由和性能问题，依据控制台报错与代码形态给出具体修复方案。

它能做什么

Vue 3 开发与调试参考，覆盖响应式（ref 与 reactive、watcher、computed）、组件与 composables、Pinia、Vue Router、表单、SSR 水合、scoped 样式、TypeScript、测试，以及 Vue 2 到 Vue 3 的迁移。把特定控制台警告与症状（"Maximum recursive updates exceeded"、"Failed to resolve component"、"getActivePinia() was called"、template ref 为 null、未捕获异常导致页面空白）映射到对应修复方法。对宏的使用给出 Vue 版本门槛：defineModel 需要 3.4+，defineSlots 需要 3.3+，reactive props 解构需要 3.5+。不覆盖 Nuxt、Vite 构建配置以及其他前端框架。

什么时候用它

排查 watcher 死循环或不触发
把 Vue 2 Options API 组件迁移到 Composition API 与 script setup
恢复因解构或重新赋值丢失的响应式
修复 template ref 为 null 或 SSR 水合不匹配

技能文档

User preferences and memory live in ~/Clawic/data/vue/ (see setup.md on first use, memory-template.md for the file format). If you have data at an old location (~/vue/ or ~/clawic/vue/), move it to ~/Clawic/data/vue/.

When To Use

Writing or reviewing Vue 3 components, composables, stores, and router configuration
Debugging: state changes that never reach the DOM, watchers that loop or never fire, null template refs, hydration mismatches, memory leaks, a page that goes blank after an uncaught error
Choosing between ref and reactive, computed and watch, props and provide/inject, Pinia and a plain composable
Performance work: slow lists, laggy typing, oversized bundles, components that re-render on every keystroke
Migrating Vue 2 / Options API code to Composition API and ``
Not for Nuxt's own layer (auto-imports, useFetch, server routes, ``) → nuxt; Vite plugin and build config → vite

Quick Reference

Situation	Play
State changes, DOM does not	Reactivity was lost or never established — walk the Reactivity Loss table below
Forgot `.value` and got a Ref object in a log	`.value` in script, auto-unwrapped in template — but NOT inside arrays or Map/Set (`arr[0].value`)
`state = {...}` stopped working	`reactive` cannot be reassigned; use `ref` and set `.value`, or `Object.assign(state, next)`
Destructuring killed reactivity	`toRefs(state)`, `storeToRefs(store)`, or pass `() => state.x` — props destructure is safe only on `vue >=3.5`
"Maximum recursive updates exceeded"	A watcher or computed mutates its own dependency → `debug.md` Infinite Loops
Watcher reads stale DOM	Default `flush: 'pre'` runs before render; use `flush: 'post'` or `await nextTick()` (rule 4)
Template ref is `null`	Refs bind at mount — read in `onMounted`, not in setup body (`components.md`)
Child does not receive updates through `v-model`	`:modelValue` + `@update:modelValue`, or `defineModel()` on `vue >=3.4` (`forms.md`)
Route param changes, component does not reload	Vue Router reuses the instance — `watch(() => route.params.id)` (`routing.md`)
Chart / map / editor library misbehaves in a `ref`	Deep proxy broke instance identity — `markRaw()` or `shallowRef()` (rule 6)
Typing lags, list of thousands re-renders	`shallowRef` + `v-memo` + virtualize above `virtualize_threshold` (`performance.md`)
Hydration mismatch after SSR	Non-deterministic render or invalid HTML nesting → `ssr.md`
Scoped style does not reach child markup	`:deep()` selector; `>>>` and `::v-deep` are the deprecated spellings (`sfc.md`)
`vue-tsc` errors that `tsc` never showed	`.vue` files only type-check through `vue-tsc` (`typescript.md`)
Test asserts before the DOM updates	`await nextTick()` / `await flushPromises()`; `trigger()` returns a promise (`testing.md`)
Vue 2 code, `$on` / filters / `.sync` gone	All removed in Vue 3 → `migration.md`
Page goes blank after a throw, one console error	Nothing catches errors by default — a setup-phase throw unmounts the subtree (`errors.md`)
Async component stuck on its loader, or `Failed to fetch dynamically imported module`	`timeout` + `errorComponent` + `onError` retry; a post-deploy chunk miss needs a guarded reload (`errors.md`)
Installing something app-wide: helper, component, directive, config	A plugin's `install(app)`; prefer `app.provide` over `globalProperties` (`plugins.md`)
Screen reader announces nothing after a route change	Focus stayed on the old page — move it to the new view's heading (`routing.md`)
Anything else	Reproduce in an isolated SFC with no props and no store, then add one input at a time until it breaks

Depth on demand: debug.md symptom→cause chains · reactivity.md refs, watchers, effect scopes · components.md props, emits, slots, built-in components · composables.md reusable logic · templates.md directives and rendering · sfc.md script setup macros and scoped CSS · state.md Pinia, Vuex 4, provide/inject · routing.md Vue Router · forms.md inputs and validation · errors.md boundaries, the app error handler, failure states · plugins.md app.use, global config, registration · performance.md render and bundle cost · ssr.md hydration · typescript.md typing components · testing.md Test Utils, Vitest, Jest · migration.md Vue 2 to Vue 3 · security.md XSS and template injection.

Core Rules

Pass the source, not the value. A watcher, computed, or composable receives a ref or a getter (() => props.id) — never the already-read value, which is a dead snapshot. Test: if deleting the arrow function still compiles, the reactivity is already gone. This single mistake explains most "my watcher never fires".
ref by default; reactive only for a bounded object you never reassign. reactive fails four ways — reassignment breaks it, destructuring breaks it, it rejects primitives, and its ref-unwrapping stops inside arrays and Map/Set. ref has one cost (.value) and no cliffs.
computed derives, watch acts. A computed is cached and must be pure: same dependencies in, same value out, zero side effects. The moment you need to fetch, write, or navigate, that is a watcher. A computed with a fetch inside runs an unpredictable number of times, because caching decides when it evaluates.
Know the flush phase before you read the DOM. Watchers default to flush: 'pre' (before the component re-renders), so DOM reads see the previous frame. Order: sync (immediately, on every mutation) → pre (batched, before render) → post (after DOM patch). Reading layout or measuring elements requires post or await nextTick().
Only what is registered synchronously in setup is cleaned up for you. Effects, watchers, and lifecycle hooks created before the first await are bound to the component's scope and stopped at unmount. Anything created inside a timer, a promise callback, or after await leaks — keep the stop handle, or wrap the work in effectScope() and dispose it (reactivity.md).
markRaw or shallowRef for every non-plain object. Class instances (Chart.js, Leaflet, CodeMirror, WebSocket, IndexedDB handles, Web Audio nodes) put in ref()/reactive() get deep-proxied: the cost is proportional to the object graph, and instanceof plus === against the raw object start failing because the proxy is not the instance. Vue warns on components stored reactively; for library instances it stays silent and you get "the map went blank".
:key is identity, not position. :key="index" on a list that reorders, filters, or splices makes Vue reuse the wrong component instance: the DOM shows row 3's text with row 5's checkbox state. Use a stable ID; use the index only for a list that is append-only and never sorted.
Gate every macro on the installed version. defineSlots and generic components need vue >=3.3; defineModel needs vue >=3.4; useTemplateRef, useId, onWatcherCleanup, and reactive props destructure need vue >=3.5. Check package.json before recommending one — a macro that does not exist compiles to nothing and fails at runtime with an undefined identifier.

Console Warnings

Vue's warnings name the cause precisely; treat each as a lookup, not a puzzle. (Production builds strip them — reproduce in dev.)

Warning	Real cause	Fix
`Failed to resolve component: X`	Not registered, or a case/typo mismatch between import and tag	Import in `` (auto-registers), or check PascalCase vs kebab-case
`Extraneous non-props attributes ... could not be automatically inherited`	Component has multiple root nodes, so Vue cannot pick a fallthrough target	Single root, or `defineOptions({ inheritAttrs: false })` + explicit `v-bind="$attrs"`
`Maximum recursive updates exceeded`	An effect writes to state it also reads	Isolate the write behind a condition, or derive with `computed` (`debug.md`)
`Invalid watch source`	A plain value was passed where a ref/getter belongs	Wrap in `() => ...` (rule 1)
`Property "x" was accessed during render but is not defined`	Not returned from `setup()`, or typo; also fires when `and a plain` disagree	Return it, or declare it in ``
`Hydration node mismatch`	Server HTML ≠ first client render	`ssr.md` — non-determinism or invalid nesting
`inject() can only be used inside setup()`	Called in a callback, after `await`, or in a plain module	Call synchronously at the top of setup and store the result
`Set operation on key "x" failed: target is readonly`	Mutating a prop or a `readonly()` proxy	Emit upward, or clone before editing
`Vue received a Component that was made a reactive object`	A component definition stored in `ref`/`reactive`	`shallowRef` for dynamic components; `markRaw` for anything class-like (rule 6)
`Component provided template option but runtime compilation is not supported`	Runtime-only build plus a string template	Move it to an SFC, or switch to the bundler build with the compiler (`security.md` — it needs `unsafe-eval`)
`"getActivePinia()" was called but there was no active Pinia` (Pinia <2.1 worded it `getActivePinia was called with no active Pinia`)	Store used before `app.use(pinia)`, or at module scope	Call the store inside setup or after install (`state.md`)

Reactivity Loss

Every "the UI doesn't update" bug is one row of this table. Diagnose by asking what you held onto: the source, or a value read from it.

You wrote	What you hold	Write instead
`const { count } = reactive(state)`	A number, frozen at read time	`toRefs(state)`, or `state.count` at the point of use
`const { items } = useStore()` (Pinia)	A frozen snapshot of state; actions survive destructuring, state does not	`storeToRefs(store)` for state, plain destructure for actions
`state = { ...state, x: 1 }` on a `reactive`	A new unproxied object; the old proxy still feeds the DOM	`Object.assign(state, patch)`, or hold a `ref` and swap `.value`
`watch(props.id, ...)`	The current id, a primitive	`watch(() => props.id, ...)`
`const first = arr.value[0]` where items are refs	A ref (arrays do not unwrap)	`arr.value[0].value`, or store plain objects
`provide('user', user.value)`	A snapshot; injectors never update	`provide('user', user)` — provide the ref itself
`const cfg = toRaw(state)` then mutate `cfg`	The raw object; writes bypass tracking	Mutate the proxy; use `toRaw` only to hand data to a non-Vue library
`Object.freeze(data)` then `ref(data)`	Frozen data Vue cannot proxy — silently non-reactive	Freeze after rendering, or use `shallowRef` deliberately
`const { x } = defineProps()` on `vue <3.5`	A snapshot (the compiler transform only landed in 3.5)	`toRef(props, 'x')`, or upgrade and keep the destructure

Component Communication

Pick the narrowest mechanism that reaches the target; every step outward costs traceability.

From → To	Mechanism	Breaks down when
Parent → child	Props (`defineProps`)	The chain is 3+ levels — prop drilling; move to provide/inject
Child → parent	Emits (`defineEmits`)	You need a return value; then it is a callback prop, not an event
Two-way on one value	`defineModel()` (`vue >=3.4`), else `modelValue` + `update:modelValue`	Multiple values — use named models (`v-model:title`)
Ancestor → deep descendant	`provide` / `inject` with an `InjectionKey`	Consumers outside that subtree, or you need writes from anywhere → store
Parent → child imperative call	Template ref + `defineExpose`	You are reaching in to read state you should have passed down
Slot content → slot owner	Scoped slot props	The content needs the owner's lifecycle, not just its data
Siblings / any-to-any	Pinia store	It is one screen's local concern — lift state to the common parent instead
Across routes	Route params for identity, store for payload	You are stuffing objects in query strings (`routing.md`)
Anything else	Pinia store, then narrow it once the shape is known	—

Output Gates

Before emitting a component, composable, or store, verify:

Every reactive source crossing a function boundary is a ref or a getter, never a read value?
Each v-for has a stable identity :key, and no v-if on the same element?
Watchers and listeners created outside synchronous setup have a stop handle or an effectScope?
Props treated as read-only; every mutation routed through an emit or a model?
Any class instance or third-party object wrapped in markRaw/shallowRef?
Every macro used exists in the project's Vue version (rule 8)?
No user-controlled string reaching v-html, :is, or :href (security.md)?
Every async region has a loading, an error, and an empty state, and something above it catches a throw (errors.md)?

Configuration

User-dependent variables. Defaults apply until the user states a preference; store them in ~/Clawic/data/vue/config.yaml.

Variable	Type	Default	Effect
vue_version	3.2 \| 3.3 \| 3.4 \| 3.5 \| later	3.5	Gates which macros and APIs get recommended (rule 8) and which workarounds appear in examples; 3.2 is the supported floor (`sfc.md`), and `later` means assume everything through 3.5 and check the release notes before using a newer API
api_style	script-setup \| setup-function \| options	script-setup	Shapes every code sample and the `migration.md` target style
language	ts \| js	ts	Whether examples carry type annotations and whether `typescript.md` guidance is volunteered
state_library	pinia \| vuex \| none	pinia	Selects the store patterns in `state.md`; `vuex` switches to its Vuex 4 section (`useStore`, commit/dispatch, namespaced paths); `none` routes shared state to composables and provide/inject
rendering_mode	spa \| ssr \| ssg	spa	Turns on SSR-safety review (module-scope state, browser APIs, hydration) from `ssr.md`
virtualize_threshold	number (rows)	200	Row count above which `performance.md` recommends virtual scrolling instead of `v-memo`
test_runner	vitest \| jest \| none	vitest	Shapes the setup and mocking examples in `testing.md`; `jest` swaps `vi.` for `jest.` and adds the transform and `transformIgnorePatterns` config that Vitest does not need

Preference areas to record as the user reveals them:

conventions — ref vs reactive house style, component and composable naming, SFC block order, feature-folder vs type-folder layout
tooling — build tool, package manager, UI kit, validation and i18n libraries, whether VueUse is welcome or the project prefers hand-rolled composables
safety posture — v-html policy, whether to run codemods without confirmation, how loudly to flag missing keys and unbounded watchers
output format — whether components ship with a test, how much explanation accompanies code, comment density
platform — browser support target, CSP strictness (which decides runtime-only vs compiler build), SSR host

Traps

Trap	Why it fails	Do instead
`v-if` and `v-for` on the same element	In Vue 3 `v-if` evaluates first and cannot see the loop variable — "Property 'item' is not defined" (the opposite of Vue 2's precedence)	`` wrapping the `v-if`, or filter in a `computed`
`v-html` with anything a user typed	Vue escapes mustaches but never `v-html` — this is the XSS door	Render as text, or sanitize server-side (`security.md`)
`watch(obj, ...)` on a reactive object	Vue forces `deep: true` and the callback gets the same object as old and new value	Watch a getter of the field you care about
`deep: true` on a large tree	Traversal cost is proportional to the node count, on every mutation	Watch specific getters, or `deep: 2` on `vue >=3.5`
Mutating a prop object because "it works"	It does mutate — same reference — but the parent has no record and DevTools shows no source	`defineModel()` or an explicit emit
`async setup()` without ``	The component never resolves and renders nothing, silently	Sync setup + a loading ref, or an explicit `` boundary
Registering a listener in `onMounted` with no `onUnmounted`	Survives the component; every remount adds another	Pair them, or use a composable that owns the cleanup
Module-scope `const state = reactive({})` in SSR	The module is shared across requests — one user's data leaks into another's page	State factory per request (`ssr.md`)
`KeepAlive` without `max`	Every visited view stays in memory for the session	`` and `onActivated` for refresh
Index as `:key` on a sortable list	Instance reuse mixes rendered content with stale local state	Stable ID (rule 7)

Where Experts Disagree

ref everywhere vs reactive for objects. The ref-only camp wins on consistency and on never hitting the reassignment cliff; the reactive camp wins on template and script ergonomics for a form-shaped object. Default: ref, with reactive allowed for an object that is created once and mutated in place. Do not mix styles inside one module.
Pinia store vs a shared composable. A composable holding module-scope refs is a global store with no devtools, no SSR safety, and no plugin surface. Reach for it only for a singleton with no server rendering; anything crossing routes or touched by more than two features belongs in a store (state.md).
Options API is legacy. It is supported indefinitely and still the fastest onboarding for a large team; Composition API's real payoff is logic extraction and typing. Boundary: mixins and cross-cutting logic mean migrate; a stable CRUD screen in Options API is not technical debt.
VueUse vs hand-rolled composables. Depending on a 200-utility library for useLocalStorage is a genuine cost; reimplementing useIntersectionObserver correctly (SSR guard, cleanup, ref-or-value input) is a bigger one. Split on whether the utility touches a browser API lifecycle.

More Clawic skills, get them at https://clawic.com/skills/vue (install if the user confirms):

nuxt — Nuxt's SSR, file routing, data fetching, and server layer
vite — build, dev server, and bundle configuration
typescript — type-system design beyond component typing
javascript — language-level semantics (async, coercion, closures)
playwright — end-to-end tests that a component test cannot cover

Feedback

If useful, star it: https://clawic.com/skills/vue
Latest version: https://clawic.com/skills/vue

Part of Clawic, the verified skill library. Get this skill: https://clawic.com/skills/vue.

常见问题

这个 skill 是否覆盖 Nuxt 的 SSR、路由与数据获取？: 不覆盖。Nuxt 自身那一层（自动导入、useFetch、服务端路由）由独立的 nuxt skill 处理；本 skill 直接覆盖 Vue 3、Vue Router 和 Pinia。
能否协助处理 Vite 构建配置？: 不能。Vite 插件与构建配置不在范围内，相关问题请使用 vite skill。
宏的推荐按哪个 Vue 版本划线？: defineSlots 与泛型组件需要 3.3+，defineModel 需要 3.4+，useTemplateRef、useId、onWatcherCleanup 以及 reactive props 解构需要 3.5+。不存在的宏会编译为空、运行时报未定义标识符，所以推荐前应先核对 package.json 中的版本。

Vue

它能做什么

什么时候用它

技能文档

When To Use

Quick Reference

Core Rules

Console Warnings

Reactivity Loss

Component Communication

Output Gates

Configuration

Traps

Where Experts Disagree

Feedback

常见问题

相关技能

React

Svelte

Flutter

Tailwind CSS

Kotlin

Android

它能做什么

什么时候用它

技能文档

When To Use

Quick Reference

Core Rules

Console Warnings

Reactivity Loss

Component Communication

Output Gates

Configuration

Traps

Where Experts Disagree

Related Skills

Feedback

常见问题

相关技能

React

Svelte

Flutter

Tailwind CSS

Kotlin

Android