1. 結論（この記事で得られること）

この記事では、Nuxt3のmiddleware実装をNuxt2と比較しながら、実務で安全に移行・実装する方法をお伝えします。

具体的に得られること：

Nuxt2とNuxt3のmiddleware実装の違いとその理由
型安全性を活かしたNuxt3らしい実装パターン
既存コードの移行チェックリスト
AIを活用した問題切り分けと効率的なデバッグ手法
実務で起こる失敗パターンとその対処法

私も初めてNuxt3のmiddlewareに触れたとき、「context」が消えて「え、「redirect」どうやるの？」と10分ぐらい固まった経験があります。この記事を読めば、そういう時間を節約できます。

2. 前提（環境・読者層）

想定環境：

Nuxt 3.x（3.10以降推奨）
TypeScript有効
Node.js 18以上

想定読者：

Nuxt2からの移行を検討している方
Nuxt3で認証・権限制御を実装する方
middleware周りでハマって困っている方

この記事で扱わないこと：

Nuxt2の基本的な使い方
Vue3の基礎文法

3. Before：よくあるつまずきポイント

3-1. Nuxt2のmiddleware（従来の書き方）

Nuxt2では「context」オブジェクトに全てが詰まっていました。

// middleware/auth.js (Nuxt2)
export default function ({ store, redirect, route }) {
  if (!store.state.user.loggedIn) {
    return redirect('/login?redirect=' + route.path)
  }
}

// nuxt.config.js (Nuxt2)
export default {
  router: {
    middleware: ['auth']
  }
}

Nuxt2の特徴：

「context」から必要なものを分割代入
「redirect」はcontext内の関数
グローバル指定は「nuxt.config.js」

3-2. Nuxt3で同じコードを書くと起こる問題

// ❌ これはNuxt3で動かない
export default function ({ store, redirect, route }) {
  // Error: context is undefined
}

よくあるエラーメッセージ：

「navigateTo is not defined」
「useRouter is not a function in middleware」
「Cannot read properties of undefined (reading 'path')」

私が最初にハマったのは「グローバルmiddlewareの指定場所が分からない」でした。「nuxt.config.ts」を探し回ったんですが、実はファイル名規約で解決する仕様になっていたんです。

3-3. なぜ変わったのか（設計思想の違い）

Nuxt3では以下の思想で再設計されています：

コンテキスト
　Nuxt2: 巨大なcontextオブジェクト
　Nuxt3: Composables (useRouter等)

型安全性
　Nuxt2: 弱い（JSベース）
　Nuxt3: 強い（TS first）

実行順序
　Nuxt2: 曖昧
　Nuxt3: 明確（ファイル名・定義順）

SSR/CSR
　Nuxt2: 混在して分かりづらい
　Nuxt3: 明示的に分離可能

この変更は「巨大なcontextに何でも詰め込む設計からの脱却」です。実際、レビューでNuxt2のmiddlewareを見ると「これ何に依存してるか分からん」ってなりがちでした。

4. After：基本的な解決パターン

4-1. Nuxt3の基本構文

// middleware/auth.ts (Nuxt3)
export default defineNuxtRouteMiddleware((to, from) => {
  const user = useState('user')
 
  if (!user.value?.loggedIn) {
    return navigateTo({
      path: '/login',
      query: { redirect: to.path }
    })
  }
})

重要な変更点：

「defineNuxtRouteMiddleware」でラップ
引数は「(to, from)」 - Vue Routerと同じ
「navigateTo」はグローバルに利用可能
「useState」で状態を取得

4-2. グローバルmiddlewareの指定方法

// middleware/auth.global.ts
// ↑ ファイル名に `.global.ts` をつけるだけ
export default defineNuxtRouteMiddleware((to, from) => {
  // 全ページで実行される
})

4-3. ページ単位での指定

<!-- pages/dashboard.vue -->
<script setup lang="ts">
definePageMeta({
  middleware: ['auth', 'role-check']
})
</script>

4-4. 条件分岐とリダイレクト

// middleware/role-check.ts
export default defineNuxtRouteMiddleware((to, from) => {
  const user = useState<User>('user')
 
  // 特定のパスでのみ実行
  if (to.path.startsWith('/admin')) {
    if (user.value?.role !== 'admin') {
      return navigateTo('/forbidden')
    }
  }
 
  // 何も返さなければ通過
})

ポイント：

「return」しなければ次に進む
「navigateTo」の戻り値をそのまま「return」
型推論が効くのでtypo防止になる