できない.dev

Vue「Failed to resolve component」の原因と直し方

Failed to resolve component は、コンポーネントを登録すれば消える。
<script setup> なら import だけで登録され、Options API は components に書く。
名前のずれでも出る。

公開: 更新:

症状できない
node bad.mjs
…
[Vue warn]: Failed to resolve component: MyButton
If this is a native custom element, make sure to exclude it from component resolution via compilerOptions.isCustomElement.
  at <App>
[Vue warn]: Component <Anonymous> is missing template or render function.

2026-09-18 に node:20(Node.js 20.20.2 / npm 10.8.2) で実際に打って取った出力。検証環境の詳細

要約

[Vue warn]: Failed to resolve component: MyButton は、テンプレートに書いたコンポーネントを Vue が見つけられないときの警告である。
原因はほぼ「登録漏れ」か「名前のずれ」のどちらかである。
<script setup> を使っていれば import するだけで自動的にローカル登録されるので、まずはそこを確認する。

実行例

登録し忘れたコンポーネントは警告が出たあと空ノードとして描画され、出力は <div><!----></div> で止まる。
components オプションによる局所登録と app.component() による全体登録は、どちらも同じ <button>OK</button> を出力する。

$ node bad.mjs
[Vue warn]: Failed to resolve component: MyButton
If this is a native custom element, make sure to exclude it from component resolution via compilerOptions.isCustomElement. 
  at <App>
[Vue warn]: Component <Anonymous> is missing template or render function. 
  at <Anonymous> 
  at <App>
出力: <div><!----></div>
$ node solve_local.mjs
出力: <div><button>OK</button></div>
$ node solve_global.mjs
出力: <div><button>OK</button></div>
$ echo $?
0

— 2026-09-18 時点の出力

検証環境Node.js 20.20.2 / npm 10.8.2 / Python 3.11.2 / 2026-09-18 検証(ほか 1 件)
検証日
実行環境
node:20 Debian GNU/Linux 12 (bookworm)
バージョン
  • Node.js 20.20.2
  • npm 10.8.2
  • Python 3.11.2
  • Git 2.39.5

この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。 再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。

解決策

1. <script setup> なら import だけでよい

<script setup>
import MyButton from './MyButton.vue'
</script>
 
<template>
  <MyButton />
</template>

コンポーネントの登録(新しいタブで開く) のとおり、<script setup> 内で import したコンポーネントは自動でローカル登録される。

2. Options API は components に登録する

<script>
import MyButton from './MyButton.vue'
 
export default {
  components: { MyButton },
}
</script>

3. 全体で使うならグローバル登録

import { createApp } from 'vue'
import App from './App.vue'
import MyButton from './components/MyButton.vue'
 
const app = createApp(App)
app.component('MyButton', MyButton) // mount より前に登録
app.mount('#app')

グローバル登録は便利な一方、未使用でもビルドに含まれ tree-shaking されにくいので、使う箇所が限られるならローカル登録を優先する。

4. 動的コンポーネントは定義を渡す

<script setup>
import Foo from './Foo.vue'
import { shallowRef } from 'vue'
 
const current = shallowRef(Foo) // 文字列 'Foo' ではなく定義を渡す
</script>
 
<template>
  <component :is="current" />
</template>

文字列名で切り替えたい場合は、名前からコンポーネントへのマップを自前で用意するか、対象をグローバル登録しておく。

よくある原因

  1. components への登録が漏れている。
    <script setup> を使わない Options API では、import しただけでは使えず、components への登録が必要になる。
  2. 名前がずれている。
    <MyButton /> と書いたのに登録名が Mybutton になっている、といったタイポである。
    Vue は PascalCase と kebab-case を相互に解決するが、綴り自体が違うと解決できない。
  3. グローバル登録の順序が誤っている。
    app.component() を、コンポーネントの使用後やマウント後に呼んでいる。
  4. 動的コンポーネントに渡す名前が誤っている。
    <component :is="name"> の name に、未登録の文字列を渡している。