Nuxt 3 で server/api の変更がホットリロードされない問題の原因と対処法まとめ

Nuxt 3 の開発中に「server/api 内のファイルを変更してもホットリロードされない」「値が更新されず、ずっと古いレスポンスが返ってくる」という問題に遭遇することがあります。フロント側の HMR は効くのに、API だけ反応しない…。この現象にはいくつかの典型的な原因があります。

本記事では、Nuxt 3（Nitro）の API HMR が効かない理由と、必ずチェックすべきポイントを体系的にまとめます。

目次

Nuxt 3 のサーバーが変更を検知しない主な原因

Nitro の内部キャッシュが効いている

Nitro は開発中でも一部の処理をキャッシュする仕様があり、特定の状況では API の反映が遅れることがあります。特に eventHandler などを返す単純なファイルは、変更を検知しにくくなるケースがあります。

ファイルの階層が誤っている

server/api 配下の API ルートは 必ず正しい階層構造で配置する必要があります。
正しい例:

server/
  api/
    users.get.ts
    posts/
      index.get.ts

誤った例:

api/        ←ルート直下に置いても無視される
server/apis ←ディレクトリ名が違うと拾われない
server/api2 ←命名が異なると当然動かない

ディレクトリ名や拡張子の typo が原因になっているケースは驚くほど多いです。

ミドルウェアと API を混同している

server/middleware は API ではありません。
以下は HMR 対象ですが、役割が異なります。

  • server/api → API エンドポイント
  • server/middleware → サーバーサイドミドルウェア

API を middleware に入れてしまうと、意図した挙動になりません。

dev サーバーの監視対象外になっている

HMR は dev server の **watcher（監視対象）**に入っていないと動きません。

下記のようなケースでは監視されません。

  • server/api を symlink で外部ディレクトリに置いている
  • monorepo で packages/backend のような外部パスを参照している
  • Docker や VM でファイル監視が無効になっている

特に monorepo・ワークスペース構成では、Nuxt 3 に追加設定が必要です。

.ts と .js を混在させている

拡張子の混在でビルドがうまくいかず、古いビルド成果物を参照することがあります。

推奨:

  • Nuxt 3 では .ts に統一する
  • 変更後は一度 nuxi dev を再起動する

SSR キャッシュが思わぬ形で残っている

node_modules/.cache 配下や Nitro のサーバーキャッシュが原因で、変更が反映されないケースがあります。

対応:

rm -rf .nuxt
rm -rf node_modules/.cache
npm run dev

再起動だけで直るケースも多いです。

正しい server/api のディレクトリ構成

Nuxt 3 の API は、以下のルールで自動ルーティングされます。

基本構造

server/
  api/
    hello.get.ts
    users/
      index.get.ts
      [id].get.ts
  • ファイル名に HTTP メソッド（.get.ts など）を含める
  • ディレクトリ階層は URL 構造に対応
  • eventHandler を必ず返す

API の正しい書き方

export default eventHandler(() => {
  return { message: 'Hello API' }
})

誤った例（HMR が効かない原因になりやすい）:

export default { message: 'Hello' } // eventHandler が必要

開発中に API が更新されないときのチェックリスト

1. ディレクトリ名と場所を確認する

  • server/api になっているか？
  • 小文字になっているか？
  • api2 や apis になっていないか？

2. ファイル名のメソッドが適切か？

  • xxx.get.ts
  • xxx.post.ts

3. ファイル監視が動いているか？

  • symlink を使っていないか？
  • コンテナ・VM の場合ファイル監視が動いているか？

4. Nitro のキャッシュを削除

rm -rf .nuxt
npm run dev

5. eventHandler を返しているか？

これがないと API として扱われません。

6. dev server を再起動したか？

HMR では反映されず、再起動が必要なケースがあります。

それでも解決しない場合の対処

nitro:dev のログを確認する

Nitro は起動時に API ルートの一覧をログに表示します。

そこに 該当 API が載っていなければ認識されていません。

server/ 配下に index.ts を置いていないか？

独自の Nitro 設定を追加していると、Nuxt の自動ルーティングが無効化されることがあります。

monorepo なら nuxt.config.ts で watch 追加

export default defineNuxtConfig({
  nitro: {
    watch: ['./server', '../shared']
  }
})

Nuxt の監視対象に入れる必要があります。

まとめ

Nuxt 3 の server/api がホットリロードされない問題は、以下が主な原因です。

  • ディレクトリ名や配置の問題
  • Nitro のキャッシュ
  • symlink や monorepo による監視漏れ
  • イベントハンドラ未使用
  • dev server の仕様

まずは「ディレクトリ構造」「eventHandler」「監視の有無」を中心にチェックし、必要であれば .nuxt やキャッシュの削除を試してください。

必要であれば、この内容を基に チェックリスト版 や 企業向けのナレッジベース用ドキュメント も作成できます。

タイトルとURLをコピーしました