vue-debug-guides

Vue 3 の実行時の問題、警告、非同期処理の失敗、ハイドレーションの不具合に対するデバッグとエラー処理です。 開発のベストプラクティスやよくある落とし穴については、vue-best-practices をご覧ください。

リアクティビティ

• 予期しない再レンダリングや状態更新の追跡 → reactivity-debugging-hooks をご覧ください
• .value へのアクセス漏れによって Ref の値が更新されない → ref-value-access をご覧ください
• リアクティブオブジェクトを分割代入すると状態が更新されなくなる → reactive-destructuring をご覧ください
• 配列、Map、Set 内の Ref がアンラップされない → refs-in-collections-need-value をご覧ください
• ネストされた Ref がテンプレートで [object Object] として表示される → template-ref-unwrapping-top-level をご覧ください
• リアクティブプロキシの同一性比較が常に false を返す → reactivity-proxy-identity-hazard をご覧ください
• サードパーティーのインスタンスがプロキシ化によって壊れる → reactivity-markraw-for-non-reactive をご覧ください
• ウォッチャーが予期せず各ティックで一度しか実行されない → reactivity-same-tick-batching をご覧ください

算出プロパティ

• 算出プロパティのゲッターが予期せず変更やリクエストを引き起こす → computed-no-side-effects をご覧ください
• 算出プロパティの値を変更すると変更が消える → computed-return-value-readonly をご覧ください
• 条件分岐の後、算出プロパティの値が更新されなくなる → computed-conditional-dependencies をご覧ください
• 配列のソートや逆順化によって元の状態が壊れる → computed-array-mutation をご覧ください
• 算出プロパティにパラメーターを渡せない → computed-no-parameters をご覧ください

ウォッチャー

• 非同期処理によって古いデータで上書きされる → watch-async-cleanup をご覧ください
• 非同期コールバック内でウォッチャーを作成する → watch-async-creation-memory-leak をご覧ください
• リアクティブオブジェクトのプロパティに対してウォッチャーが実行されない → watch-reactive-property-getter をご覧ください
• 非同期の watchEffect が await 後の依存関係を検出できない → watcheffect-async-dependency-tracking をご覧ください
• ウォッチャーのコールバック内で DOM を読み取ると値が古い → watch-flush-timing をご覧ください
• ディープウォッチャーが同一の古い値と新しい値を報告する → watch-deep-same-object-reference をご覧ください
• watchEffect がテンプレート参照の更新前に実行される → watcheffect-flush-post-for-refs をご覧ください

コンポーネント

• 子コンポーネントで「component not found」エラーが発生する → local-components-not-in-descendants をご覧ください
• カスタムコンポーネントでクリックリスナーが実行されない → click-events-on-components をご覧ください
• 親から script setup 内の子コンポーネントの Ref データにアクセスできない → component-ref-requires-defineexpose をご覧ください
• HTML テンプレートの解析によって Vue コンポーネントの構文が壊れる → in-dom-template-parsing-caveats をご覧ください
• 名前の衝突によって誤ったコンポーネントがレンダリングされる → component-naming-conflicts をご覧ください
• 複数ルートコンポーネントに親のスタイルが適用されない → multi-root-component-class-attrs をご覧ください

Props と Emits

• defineProps で参照されている変数が原因でエラーが発生する → prop-defineprops-scope-limitation を参照
• コンポーネントが宣言されていないイベントを発行し、警告が表示される → declare-emits-for-documentation を参照
• defineEmits を関数内または条件分岐内で使用している → defineEmits-must-be-top-level を参照
• defineEmits に型引数とランタイム引数の両方がある → defineEmits-no-runtime-and-type-mixed を参照
• ネイティブイベントリスナーがクリックに反応しない → native-event-collision-with-emits を参照
• クリック時にコンポーネントイベントが 2 回発生する → undeclared-emits-double-firing を参照

テンプレート

• 文を含むテンプレートのコンパイルエラーが発生する → template-expressions-restrictions を参照
• 「undefined のプロパティを読み取れません」というランタイムエラーが発生する → v-if-null-check-order を参照
• 動的ディレクティブ引数が正しく機能しない → dynamic-argument-constraints を参照
• v-else 要素が常に無条件でレンダリングされる → v-else-must-follow-v-if を参照
• v-if と v-for の併用によって優先順位の不具合や移行時の問題が発生する → no-v-if-with-v-for を参照
• テンプレート内の関数呼び出しによる状態変更が、予測不能な再レンダリングの不具合を引き起こす → template-functions-no-side-effects を参照
• ループ内の子コンポーネントに undefined のデータが表示される → v-for-component-props を参照
• ソートまたは反転後に配列の順序が変わる → v-for-computed-reverse-sort を参照
• リスト項目が消えたり、状態が予期せず入れ替わったりする → v-for-key-attribute を参照
• 範囲の反復処理で 1 つずれるエラーが発生する → v-for-range-starts-at-one を参照
• template 要素で v-show または v-else が機能しない → v-show-template-limitation を参照

テンプレート参照

• 要素が条件付きで非表示になると ref が null になる → template-ref-null-with-v-if を参照
• ループ内で ref 配列のインデックスがデータ配列と一致しない → template-ref-v-for-order を参照
• テンプレート参照の名前を変更すると、コード内で気づかないまま問題が発生する → use-template-ref-vue35 を参照

フォームと v-model

• v-model を使用するとフォームの初期値が表示されない → v-model-ignores-html-attributes を参照
• textarea の内容を変更しても ref が更新されない → textarea-no-interpolation を参照
• iOS ユーザーがドロップダウンの最初の項目を選択できない → select-initial-value-ios-bug を参照
• 親コンポーネントと子コンポーネントで値が異なる → define-model-default-value-sync を参照
• オブジェクトのプロパティの変更が親に同期されない → definemodel-object-mutation-no-emit を参照
• 中国語または日本語の入力でリアルタイム検索／検証が機能しない → v-model-ime-composition を参照
• 数値入力で 0 ではなく空文字列が返される → v-model-number-modifier-behavior を参照
• カスタムチェックボックスの値がフォーム送信時に送信されない → checkbox-true-false-value-form-submission を参照

イベントと修飾子

• 複数のイベント修飾子を連結すると、予期しない結果になります → event-modifier-order-matters を参照してください
• システム修飾キーを使うと、キーボードショートカットが実行されません → keyup-modifier-timing を参照してください
• 意図しない修飾キーの組み合わせで、キーボードショートカットが実行されます → exact-modifier-for-precise-shortcuts を参照してください
• passive 修飾子と prevent 修飾子を組み合わせると、イベントの動作に問題が生じます → no-passive-with-prevent を参照してください

ライフサイクル

• イベントリスナーを削除しないとメモリーリークが発生します → cleanup-side-effects を参照してください
• コンポーネントのマウント前は、DOM にアクセスできません → lifecycle-dom-access-timing を参照してください
• 状態の変更後に DOM を読み取ると、古い値が返されます → dom-update-timing-nexttick を参照してください
• SSR のレンダリングとクライアントでのハイドレーションの結果が異なります → lifecycle-ssr-awareness を参照してください
• 非同期に登録されたライフサイクルフックは実行されません → lifecycle-hooks-synchronous-registration を参照してください

スロット

• スロットコンテンツ内で子コンポーネントのデータにアクセスすると、undefined 値が返されます → slot-render-scope-parent-only を参照してください
• 名前付きスロットとスコープ付きスロットを組み合わせると、コンパイルエラーが発生します → slot-named-scoped-explicit-default を参照してください
• ネイティブ HTML 要素で v-slot を使用すると、コンパイルエラーが発生します → slot-v-slot-on-components-or-templates-only を参照してください
• 暗黙のデフォルトスロットの動作により、コンテンツが予期しない場所に配置されます → slot-implicit-default-content を参照してください
• スコープ付きスロットの props に、期待される name プロパティがありません → slot-name-reserved-prop を参照してください
• ラッパーコンポーネントによって、子コンポーネントのスロット機能が損なわれます → slot-forwarding-to-child-components を参照してください

Provide/Inject

• 非同期処理の後に provide を呼び出すと、何も通知されずに失敗します → provide-inject-synchronous-setup を参照してください
• 提供された値の出所を追跡する → provide-inject-debugging-challenges を参照してください
• プロバイダーが変更されても、注入された値は更新されません → provide-inject-reactivity-not-automatic を参照してください
• 複数のコンポーネントで同じデフォルトオブジェクトが共有されます → provide-inject-default-value-factory を参照してください

属性

• 内部のイベントハンドラーとフォールスルーするイベントハンドラーの両方が実行されます → attrs-event-listener-merging を参照してください
• 明示的に指定した属性が、フォールスルーした値によって上書きされます → fallthrough-attrs-overwrite-vue3 を参照してください
• ラッパー内で、属性が誤った要素に適用されます → inheritattrs-false-for-wrapper-components を参照してください

コンポーザブル

• コンポーザブルを setup コンテキストの外、または非同期に呼び出しています → composable-call-location-restrictions を参照してください
• 入力が変更されても、コンポーザブルのリアクティブな依存関係が更新されません → composable-tovalue-inside-watcheffect を参照してください
• コンポーザブルが外部の状態を予期せず変更します → composable-avoid-hidden-side-effects を参照してください
• コンポーザブルの戻り値を分割代入すると、予期せずリアクティビティが失われます → composable-naming-return-pattern を参照してください

Composition API

• 非同期処理後にライフサイクルフックが何も通知せず失敗する → composition-api-script-setup-async-contextを参照してください
• 親コンポーネントの参照から公開されたプロパティにアクセスできない → define-expose-before-awaitを参照してください
• 関数型プログラミングのパターンにより、期待される Vue のリアクティビティの動作が崩れる → composition-api-not-functional-programmingを参照してください
• React Hook のメンタルモデルにより Composition API の使い方を誤る → composition-api-vs-react-hooks-differencesを参照してください

アニメーション

• DOM ノードが再利用されるとアニメーションが開始されない → animation-key-for-rerenderを参照してください
• 負荷がかかると TransitionGroup のリスト更新が遅く感じられる → animation-transitiongroup-performanceを参照してください

TypeScript

• 可変なプロパティのデフォルト値により、コンポーネントインスタンス間で状態が漏れる → ts-withdefaults-mutable-factory-functionを参照してください
• reactive() のジェネリック型指定により、ref のアンラップに不整合が生じる → ts-reactive-no-generic-argumentを参照してください
• マウント前または v-if によるアンマウント後に、テンプレート参照で null アクセスエラーが発生する → ts-template-ref-null-handlingを参照してください
• オプショナルな boolean プロパティが undefined ではなく false として動作する → ts-defineprops-boolean-default-falseを参照してください
• インポートした defineProps の型で、解決不能または複雑な型参照エラーが発生する → ts-defineprops-imported-types-limitationsを参照してください
• 型指定のない DOM イベントハンドラーが厳格な TypeScript 設定でエラーになる → ts-event-handler-explicit-typingを参照してください
• 動的コンポーネントの参照によりリアクティブコンポーネントの警告が発生する → ts-shallowref-for-dynamic-componentsを参照してください
• 型の絞り込みを行わないと、ユニオン型のテンプレート式で型チェックに失敗する → ts-template-type-castingを参照してください

非同期コンポーネント

• defineAsyncComponent の遅延読み込みをルートコンポーネントで誤って設定する → async-component-vue-routerを参照してください
• コンポーネントの読み込み時にネットワーク障害やタイムアウトが発生する → async-component-error-handlingを参照してください
• コンポーネントの再アクティブ化後にテンプレート参照が undefined になる → async-component-keepalive-ref-issueを参照してください

レンダー関数

• 状態が変化してもレンダー関数の出力が静的なままになる → rendering-render-function-return-from-setupを参照してください
• 再利用された vnode インスタンスが正しくレンダリングされない → render-function-vnodes-must-be-uniqueを参照してください
• 文字列のコンポーネント名が HTML 要素としてレンダリングされる → rendering-resolve-component-for-string-namesを参照してください
• vnode の内部情報へのアクセスにより Vue の更新時に問題が発生する → render-function-avoid-internal-vnode-propertiesを参照してください
• Vue 2 のレンダー関数のパターンにより Vue 3 でクラッシュする → rendering-render-function-h-import-vue3を参照してください
• h() からスロットのコンテンツがレンダリングされない → rendering-render-function-slots-as-functionsを参照してください

KeepAlive

• Vue Router のネストされたルートで子コンポーネントが二度マウントされる → keepalive-router-nested-double-mountを参照してください
• KeepAlive と Transition アニメーションを組み合わせるとメモリ使用量が増加する → keepalive-transition-memory-leakを参照してください

トランジション

• done コールバックがないと JavaScript のトランジションフックが停止します → transition-js-hooks-done-callbackを参照してください
• インラインのリスト要素で移動アニメーションが失敗します → transition-group-flip-inline-elementsを参照してください
• リスト項目が滑らかにアニメーションせず、跳ねるように移動します → transition-group-move-animation-position-absoluteを参照してください
• Vue 2 から Vue 3 への移行で TransitionGroup のラッパーが変わり、レイアウトが崩れます → transition-group-no-default-wrapper-vue3を参照してください
• ネストされたトランジションが完了前に途切れます → transition-nested-durationを参照してください
• 再利用可能なトランジションラッパーでスコープ付きスタイルが機能しなくなります → transition-reusable-scoped-styleを参照してください
• RouterView のトランジションが初回のレンダリングで予期せずアニメーションします → transition-router-view-appearを参照してください
• CSS トランジションとアニメーションを併用するとタイミングの問題が発生します → transition-type-when-mixedを参照してください
• トランジションの切り替えが速いとクリーンアップフックが実行されません → transition-unmount-hook-timingを参照してください

Teleport

• DOM 内に Teleport のターゲット要素が見つかりません → teleport-target-must-existを参照してください
• Teleport で移動したコンテンツにより SSR のハイドレーションが失敗します → teleport-ssr-hydrationを参照してください
• Teleport で移動したコンテンツにスコープ付きスタイルが適用されません → teleport-scoped-styles-limitationを参照してください

Suspense

• Suspense コンポーネントの非同期エラーを処理する必要があります → suspense-no-builtin-error-handlingを参照してください
• サーバーサイドレンダリングで Suspense を使用する → suspense-ssr-hydration-issuesを参照してください
• Suspense の配下では非同期コンポーネントの読み込み／エラー UI が無視されます → async-component-suspense-controlを参照してください

SSR

• サーバーとクライアントのレンダリング結果で HTML が異なります → ssr-hydration-mismatch-causesを参照してください
• 共有シングルトンストアによって、リクエスト間でユーザーの状態が漏洩します → state-ssr-cross-request-pollutionを参照してください
• ユニバーサルコードパスでブラウザー専用 API を使用すると、サーバーレンダリングがクラッシュします → ssr-platform-specific-apisを参照してください

パフォーマンス

• 親から不安定な props が渡されるため、リストの子要素が不要に再レンダリングされます → perf-props-stability-update-optimizationを参照してください
• 同等の値でも、算出オブジェクトによってエフェクトが再実行されます → perf-computed-object-stabilityを参照してください

SFC（単一ファイルコンポーネント）

• コンポーネントのスクリプトブロックから名前付きエクスポートを使用しようとしている → sfc-named-exports-forbiddenを参照してください
• 変更後にテンプレート内の変数が更新されません → sfc-script-setup-reactivityを参照してください
• 子コンポーネントの要素にスコープ付きスタイルが適用されません → sfc-scoped-css-child-component-stylingを参照してください
• 動的な v-html コンテンツにスコープ付きスタイルが適用されません → sfc-scoped-css-dynamic-contentを参照してください
• スロットコンテンツにスコープ付きスタイルが適用されません → sfc-scoped-css-slot-contentを参照してください
• 動的に生成すると Tailwind クラスが欠落します → tailwind-dynamic-class-generationを参照してください
• 名前の競合により、再帰コンポーネントがレンダリングされません → self-referencing-component-nameを参照してください

プラグイン

• グローバルプロパティが名前の競合を引き起こす理由をデバッグする → plugin-global-properties-sparingly を参照してください
• プラグインが動作しない、または inject が undefined を返す → plugin-install-before-mount を参照してください
• setup ベースのコンポーネントでプラグインのグローバルプロパティが利用できない → plugin-prefer-provide-inject-over-global-properties を参照してください
• プラグインの型拡張の誤りが ComponentCustomProperties の型付けを壊す → plugin-typescript-type-augmentation を参照してください

アプリの設定

• mount の呼び出し後にアプリ設定のメソッドが動作しない → configure-app-before-mount を参照してください
• mount() からアプリ設定をチェーンすると失敗する。mount がコンポーネントインスタンスを返すため → mount-return-value を参照してください
• require.context ベースのコンポーネント自動登録が Vite で失敗する → dynamic-component-registration-vite を参照してください