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 を参照
• プロキシ化されると third-party インスタンスが破損する → reactivity-markraw-for-non-reactive を参照
• ウォッチャーが予期せずにティックごとに 1 回だけ発火 → reactivity-same-tick-batching を参照

Computed

• Computed ゲッターが予期せず変異やリクエストをトリガー → computed-no-side-effects を参照
• Computed 値を変異させると変更が消える → computed-return-value-readonly を参照
• 条件付きロジック後に Computed 値が更新されない → computed-conditional-dependencies を参照
• 配列のソート・リバースが元の状態を破損 → computed-array-mutation を参照
• Computed プロパティへのパラメータ渡しが失敗 → 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 を参照
• Deep ウォッチャーが同一の old/new 値を報告 → watch-deep-same-object-reference を参照
• watchEffect がテンプレート ref の更新前に実行 → watcheffect-flush-post-for-refs を参照

コンポーネント

• 子コンポーネントが「コンポーネント見つかりません」エラーをスロー → 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 を参照
• コンポーネントが未宣言イベントを emit して警告が出る → 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 を参照
• 範囲イテレーション で off-by-one エラーが発生 → v-for-range-starts-at-one を参照
• v-show または v-else がテンプレート要素で機能しない → v-show-template-limitation を参照

テンプレート Ref

• 要素が条件付きで非表示の場合、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 を参照
• Number 入力がゼロの代わりに空の文字列を返す → 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 を参照
• Inject された値がプロバイダー変更時に更新されない → provide-inject-reactivity-not-automatic を参照
• 複数のコンポーネントが同じデフォルト オブジェクトを共有 → provide-inject-default-value-factory を参照

Attrs

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

Composable

• Composable が setup コンテキスト外または非同期で呼び出されている → composable-call-location-restrictions を参照
• Composable リアクティブ依存性が入力変更時に更新されない → composable-tovalue-inside-watcheffect を参照
• Composable が外部状態を予期せず変異 → composable-avoid-hidden-side-effects を参照
• Composable の戻り値の分割代入がリアクティビティを破損 → composable-naming-return-pattern を参照

Composition API

• 非同期操作後のライフサイクル フックが静かに失敗 → composition-api-script-setup-async-context を参照
• 親コンポーネント ref が expose されたプロパティにアクセスできない → 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

• 変更可能な props デフォルトがコンポーネント インスタンス間で状態をリーク → ts-withdefaults-mutable-factory-function を参照
• reactive() ジェネリック型が ref アンラップの不一致を引き起こす → ts-reactive-no-generic-argument を参照
• テンプレート ref がマウント前または v-if アンマウント後に null アクセス エラーをスロー → ts-template-ref-null-handling を参照
• オプション boolean props が undefined ではなく false として動作 → ts-defineprops-boolean-default-false を参照
• インポートされた defineProps 型が解決不可またはを複雑な型参照で失敗 → ts-defineprops-imported-types-limitations を参照
• 型なし DOM イベント ハンドラーが strict 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 を参照

Render 関数

• 状態変更後の Render 関数出力が静的なまま → 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 render 関数パターンが 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 を参照

トランジション

• 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 を参照
• Computed オブジェクトが同等値にもかかわらず エフェクト を再トリガー → perf-computed-object-stability を参照

SFC (Single File Components)

• コンポーネント script ブロック から名前付きエクスポートを使用しようとする → 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() からアプリ config をチェーン化すると失敗 (mount がコンポーネント インスタンスを返すため) → mount-return-value を参照
• require.context ベースのコンポーネント 自動登録が Vite で失敗 → dynamic-component-registration-vite を参照