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 を参照
• ウォッチャーが予期せずティックごとに 1 回しか実行されない → 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 を参照
• スクリプトセットアップ内で親から子の 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 を参照してください
• コンポーネントが未宣言のイベントを emit して警告が発生する → declare-emits-for-documentation を参照してください
• defineEmits を関数内または条件分岐内で使用している → defineEmits-must-be-top-level を参照してください
• defineEmits に型引数と実行時引数の両方が指定されている → defineEmits-no-runtime-and-type-mixed を参照してください
• ネイティブイベントリスナーがクリックに反応しない → native-event-collision-with-emits を参照してください
• クリック時にコンポーネントイベントが二重に発火する → 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 を参照してください
• ループ内の子コンポーネントに未定義のデータが表示される → v-for-component-props を参照してください
• ソートまたは逆順にした後で配列の順序が変わる → v-for-computed-reverse-sort を参照してください
• リスト項目が予期せず消えたり、状態が入れ替わったりする → v-for-key-attribute を参照してください
• 範囲の反復処理でオフバイワンエラーが発生する → v-for-range-starts-at-one を参照してください
• テンプレート要素で v-show または v-else が動作しない → v-show-template-limitation を参照してください

テンプレート参照

• 要素が条件付きで非表示になると ref が null になる → template-ref-null-with-v-if を参照してください
• ループ内で ref 配列のインデックスがデータ配列と一致しない → template-ref-v-for-order を参照してください
• テンプレート ref の名前をリファクタリングすると、コード内で気づかないまま動作しなくなる → 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を参照してください

コンポーザブル

• セットアップコンテキスト外または非同期にコンポーザブルを呼び出しています → 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 を参照してください
• 親コンポーネントの ref から公開されたプロパティにアクセスできない → 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

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

非同期コンポーネント

• defineAsyncComponent の遅延読み込みでルートコンポーネントの設定を誤る → async-component-vue-router を参照してください
• コンポーネントの読み込み時にネットワーク障害やタイムアウトが発生する → async-component-error-handling を参照してください
• コンポーネントの再アクティブ化後にテンプレート ref が 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 ルートで子コンポーネントが2回マウントされる → keepalive-router-nested-double-mountを参照
• KeepAlive と Transition アニメーションを組み合わせるとメモリが増加する → keepalive-transition-memory-leakを参照

Transitions

• JavaScript のトランジションフックが done コールバックなしで停止する → 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

• Teleport のターゲット要素が DOM に見つからない → 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を参照してください