v4
進階架構
CoreLogic

路由中間件

中間件就像是大樓的警衛。在使用者真正進入某個頁面之前，中間件會先攔截請求，檢查是否有「通行證」，或者將其引導至正確的方向。

核心概念

中間件在路由切換 (Route Change) 時觸發。它可以在客戶端 (Client-side Navigation) 或伺服器端 (SSR) 執行。

Navigation Flow
User
Guard
Middleware
Page

中間件類型

Middleware Structure
  • middleware/
    • auth.tsNamed
    • analytics.global.tsGlobal
  • pages/
    • dashboard.vueInline

具名中間件 (Named)

最常用的類型。定義在 middleware/ 目錄中，透過 definePageMeta 在特定頁面引用。

全域中間件 (Global)

檔名加上 .global 後綴。會自動應用於每一個路由切換，適合 Analytics 或全站權限檢查。

內聯中間件 (Inline)

直接寫在頁面內。適用於只在該頁面使用的簡單邏輯，不建議用於複雜業務。

實戰：權限驗證

這是最常見的使用場景。我們建立一個 auth 中間件來保護後台頁面。

1

建立中間件檔案

app/middleware/auth.ts
// app/middleware/auth.ts
export default defineNuxtRouteMiddleware((to, from) => {
  const user = useUser() // 假設你有這個 Composable

  // 如果未登入，重導向到登入頁
  if (!user.value.isLoggedIn) {
    return navigateTo('/login')
  }
})
2

在頁面中使用

app/pages/dashboard.vue
<script setup>
definePageMeta({
  middleware: ['auth']
})
</script>

<template>
  <h1>Dashboard (Protected)</h1>
</template>

實戰演練：權限攔截

試著切換下方的「登入狀態」，並嘗試訪問受保護的 Dashboard 頁面。觀察中間件如何攔截並重導向。

Current Path:/

Navigation Menu

Middleware Logic:
  • If accessing /dashboard without login → Redirect to /login
  • If accessing /login while logged in → Redirect to /dashboard
Middleware Logs
Waiting for navigation...

控制導航行為

中間件的回傳值決定了使用者的去向。

navigateTo(path)

重導向到指定路徑。這是最常用的回傳值。
例如：未登入轉跳登入頁。

abortNavigation()

終止導航，通常會顯示 404 或錯誤頁面。
例如：權限不足或資源不存在。

return (void)

如果不回傳任何值（或回傳 undefined），則表示「通過檢查」，繼續前往目標頁面。