參考網站
參考網站
參考網站
參考網站

在使用 Vue 3 開發網站可能會面臨需要做 SEO 的情境，為了解決該情境問題，你可能會找到使用 Vite 做預渲染或其他方式，Nuxt 3 也是其中一個解決方案，且有更多強大的功能，目前 Nuxt 3 已經正式發布穩定版，就讓我們開始嘗鮮上手吧！

本篇會著重在 Nuxt 3 的特色與功能學習，所以你可能需具備些 Vue 3 基礎，我將從搭建 Nuxt 3 開發環境、頁面路由與佈局一直到使用 Nuxt 3 建立 SEO 所需的資訊做些筆記及介紹，讓你有個概念並嘗試用 Nuxt 3 來做 SSR 或 SSG，進而解決 Vue 3 SPA 不好做 SEO 的問題。

Nuxt 3 介紹

前言

採用 SSR + SPA，將第一個畫面透過 SSR 產生，其他就交給 CSR 來做處理，既能兼具 SEO 還能擁有 SPA 的使用者體驗，不是很完美嗎？沒有錯，但在沒有任何框架輔助之下，同一個頁面你可能就需要實作兩次程式碼，也就是前後端各一次的渲染邏輯，這也就是相應的代價。在介紹 Nuxt 3 之前就稍微提一下 Isomorphic JavaScript 與 Universal JavaScript。

Isomorphic JavaScript 與 Universal JavaScript

Isomorphic JavaScript

隨著 Node.js 的出現，讓客戶端瀏覽器之外的伺服器也能執行 JavaScript 程式碼，使得 JavaScript 成為一種同構語言 (Isomorphic Language)。Isomorphic JavaScript 即稱之為同樣的 JavaScript 程式碼可以在客戶端及伺服器端運行；也就是說同一份 Code 除了能在前端瀏覽器也能在後端執行。

然而 Isomorphic JavaScript 與 Universal JavaScript 的名詞存有一些爭議與差異，如今，Isomorphic JavaScript 多以稱相同的程式碼元件，可以在客戶端與伺服器端用來組裝或渲染出頁面的技術。

Universal JavaScript

Michael Jackson 的文章提到，Isomorphic 這個詞的含義「corresponding or similar in form and relations」為兩個實體不相同，但具有相似的操作或對應的關係，換句話說就是，兩個看起來不一樣的使用方法或語法，但最終的執行結果是一樣的，例如 jQuery 或 Zepto 操作 DOM 的語法長的不大一樣，但是最終也都是對應 JavaScript 的 document.querySelector 等方法。

所以說，為了描述相同的程式碼但能在不同環境中運行的名詞，就有了 Universal JavaScript 一詞，這個名字告訴人們 JavaScript 它不僅可以在服務器和瀏覽器上運行，還可以在本機設備和嵌入式架構上運行。

那麼 Isomorphic JavaScript 和 Universal JavaScript 與我們又有什麼關係呢？

有的，因為 Nuxt 3 正是一個 Isomorphic JavaScript 框架，Nuxt 3 是目前你使用 Vue 3 在開發網站時，會需要採用 SSR 技術或優化 SEO 問題所可以使用的解決方案。

Nuxt 3

Nuxt 3 官方在 2022/11/16 正式發布穩定版本 Nuxt 3.0 stable。

Nuxt 3 官網的標語 The Intuitive Web Framework，Nuxt 3 將讓你更直覺的體驗混合渲染等新功能，讓在使用 Vue 3 開發時變得更加簡單！

Nuxt 3 的新特性

從 Nuxt 3 官網的提供訊息所列，簡單說明一下 Nuxt 3 的新特性，共有下列 12 個：

• Lighter：更輕量，針對現在瀏覽器，伺服器部署與客戶端打包能減少最高 75 倍之多。
• Faster：更快速，通過 Nitro 提供支持的動態伺服器端程式碼拆分來優化冷啟動問題。
• Hybird：動態的靜態頁面生成和其他高級模式，現在這些都將成為可能。
• Suspense：在導航觸發的前後，皆可以在任何元件中取得數據資料。
• Composition API：使用 Composition API 和 Nuxt 3 的 Composables 實現真正的程式碼可重用性。
• Nuxt CLI：全新的零依賴體驗，幫助你輕鬆建立專案與模組整合。
• Nuxt Dev Tools：專屬開發除錯工具，提供更多的資訊與快速修復，讓工作更高效。
• Nuxt Kit：具備基於 TypeScript 和跨版本兼容性的全新模組開發。
• webpack 5：更快速的打包時間與打包出更小的體積，並且無需任何配置。
• Vite：使用 Vite 作為打包工具，體驗閃電般快速的 HMR。
• Vue 3：完全支持 Vue 3。
• TypeScript：使用 TypeScript 與 ESM 構建而成，無需額外的配置步驟。

Nitro

Nuxt 3 由一個全新的伺服器引擎 Nitro 提供支持，它具有以下幾個特點：

• 跨平台支持，支持 Node.js 與瀏覽器等。
• Serverless 支持。
• API 路由，使用 unjs/h3。
• 自動程式碼拆分 (code-splitting) 與異步加載 chunk (async-loaded chunks)。
• 混合渲染模式，供靜態 (static)與無伺服器 (serverless) 網站。
• 開發伺服器上的 HMR (hot module reloading)。

簡單來說，Nitro 已經是 Nuxt 3 包含的全新伺服器引擎，無需再進行配置。Nitro 除了支援 SPA、建立靜態的網站，甚至能在後端打 API 時直接調用相關函數，從而降低 API Request，整體來說是非常強大的伺服器引擎。

Nuxt 3 渲染模式

Nuxt 3 目前支援兩種渲染模式，Client-side Only Rendering 與 Universal Rendering。之後將會推出更先近的渲染模式，混合渲染 (Hybrid Rendering) 與邊緣渲染 (Edge-Side Rendering)。

• Client-side Only Rendering

Nuxt 3 設定為該模式，如同單純使用 Vue 3 建置出的 SPA，瀏覽器下載並載入完 Vue 程式碼後，渲染 HTML 的所有動作皆在客戶端執行，也就是客戶端渲染 CSR。

• Universal Rendering

Universal Rendering 是 Nuxt 3 預設的渲染模式，在這個模式之下，無論頁面是預先產生並緩存還是動態渲染，Nuxt 都會在伺服器環境中執行 Vue 程式碼，並渲染 HTML，也就是如同 SSR，伺服器會向瀏覽器返回一個完整呈現的 HTML 頁面。當瀏覽器完整呈現的頁面出現後，也會開始載入 Vue 程式碼，以因應後續的動態頁面與路由跳轉等，即轉換為 SPA 開始由客戶端進行渲染。也就是說 Nuxt 3 的 Universal Rendering 即是指 SSR + SPA。

• 混合渲染 (Hybrid Rendering)

我們在使用 Vue 開發 SPA 網站時，通常是會設置路由 (Route) 讓網頁能夠到達不同的頁面再來請求資料，此為 CSR。在使用 Nuxt 開發時能讓能網站擁有 SSR + SPA 的 Universal Rendering 渲染方式，除此之外，Nuxt 3 還提供了一種更先進的渲染模式——混合渲染 (Hybrid Rendering)，可以為每個路由設置不同的渲染與緩存的規則，讓部分頁面使用 CSR 在客戶端進行渲染，另一部分使用 SSR 在伺服器端進行渲染。

• 邊緣渲染 (Edge-Side Rendering)

Nitro 為 Nuxt 3 提供支持的全新伺服器端渲染引擎，它為 Node.js、Deno、Worker 等提供跨平台的支持，讓 Nuxt 可以在 CDN Edge Workers 進行渲染，故稱為邊緣渲染 (Edge-Side Rendering)，能有效分擔在伺服器端渲染時的資源負荷，將其提升到另一個層次，從而減少網路延遲及成本。

Nuxt 3 的建構工具

Nuxt 3 預設的建構工具如下：

• 預設使用 Vite 也可以切換成 webpack
• Rollup
• PostCSS
• esbuild

Nuxt 3 已經幫我們配置好一堆設定啦，真的是開箱即用，而且 Nuxt 也支援 TypeScript。如果說真的要調整配置，也可以再 nuxt.config 中進行調整，非常方便貼心。

使用 nuxi 建立第一個專案

線上玩玩看

如果你還在觀望或是從隔壁棚過來的，還不想安裝相關工具與環境，那麼可以點擊下面其一連結，在 StackBlitza 或 CodeSandbox 的線上編輯器環境稍微玩玩，直接線上體驗 Nuxt 3。

• Play on StackBlitz
• Play on CodeSandbox

開始建立第一個專案

先決條件

開始之前，依照 Nuxt 3 官網的起手式我們有幾個項目需要做一下檢查，我們這裡僅先注意一下 Node.js 的版本，建議使用目前最新 LTS 版本 v16.17.0 (包含 NPM v8.15.0)。

使用 nuxi 建立 Nuxt 3 專案

nuxi 全名為 Nuxt Command Line Interface，是由 Nuxt 提供開發的標準工具，Nuxt CLI 就像是 Vue CLI 可以建立 Vue 專案，我們當然也就可以使用 Nuxt CLI 來建立 Nuxt 的專案。

首先，打開終端機 (Terminal)，將目錄切換至自己習慣的工作區，接著輸入如下的 nuxi 提供指令並執行，來初始化建立一個 Nuxt 3 專案。在此，我們的專案名為 nuxt-app。

1

npx nuxi init nuxt-app

如下圖，npx 會詢問你是否安裝最新版本的套件 [email protected] 輸入 y 即可。

執行完指令後直到出現如下提示，代表專案已經初始建立成功，完成後可以發現目前目錄下多了一個名為 nuxt-app 的資料夾，這個資料夾也就是 Nuxt 3 專案的根目錄。

接下來，我們可以進入專案目錄 nuxt-app。

1

cd nuxt-app

在 nuxt-app 專案目錄下可以看到熟悉的 package.json，我們就可以開始安裝 Nuxt 3 專案的相關依賴套件。

1
2
3

npm install
# or
# yarn

Nuxt CLI 如同 Vue CLI 已經在建立專案時幫我們初始完成許多事情，再安裝完相關依賴套件後輸入下列指令，我們就可以在開發環境下啟動 Nuxt 了。

1
2
3

npm run dev -- -o
# or
# yarn run dev -- -o

如果沒有意外，可以看到 Nitro 幫我們啟動了 Nuxt 3 的服務。

根據提示，我們可以在瀏覽器輸入網址 http://localhost:3000/ 看看服務是否正常運作。

如果看到如下圖的歡迎畫面，恭喜你！我們已經成功建立第一個 Nuxt 3 專案囉！

現在你可以嘗試打開在專案目錄下的 app.vue 檔案之中，app.vue 是我們 Nuxt 專案的進入點，它的內容如下：

1
2
3
4
5

<template>
  <div>
    <NuxtWelcome />
  </div>
</template>

可以發現它與 Vue 3 的單一元件檔 (Single File Component, SFC) 相比，好像少了點什麼，怎麼有用了 <NuxtWelcome /> 卻沒看見在哪邊 import 的呢？

其實呢，<NuxtWelcome /> 這個元件就是我們前面瀏覽器看到的歡迎畫面，是 Nuxt 框架自帶的一個元件，而且 Nuxt 自動導入元件的更是其特色之一，後面的系列我們會再提到自動導入 (Auto Imports)。

在這裡直接移除 <NuxtWelcome /> 就可以了，我們將 app.vue 調整如下，並保存檔案。

1
2
3
4
5

<template>
  <div>
    <h1>2022 iThome 鐵人賽</h1>
  </div>
</template>

可以看見因為 Nuxt 預設 Vite 建構並支援 HMR (Hot Module Replacement)，我們可以在瀏覽器快速的看見修改後的結果。

至此，大家就可以先簡單的玩玩 Nuxt 3，接下來我將補充一些 nuxi 的指令與參數簡介。

Nuxt CLI 常用指令

以下將簡單介紹一些常用的指令，若您在專案目錄下記得使用 npx 來執行 nuxi。

另外在此提醒，下面所列的指令部分參數會進行省略，若有興趣翻翻完整的指令與參數說明，可以參考 Nuxt 3 官方文件。

nuxi init

1

npx nuxi init|create [dir]

這個 nuxi init 指令是用來初始化一個 Nuxt 專案，等同 nuxi create 指令，dir 你可以填字串作為專案與資料夾名稱，也可以填寫完整路徑來建立專案目錄。

nuxi dev

1

npx nuxi dev [--open, -o] [--port, -p]

當我們在本地端進行開發時，需要運行開發環境，當我們執行 npm run dev -- -o 時，依據 package.json 中的 scripts 所列，其實就是在執行 nuxi dev -o，其中的 -o 表示服務啟動後開啟瀏覽器。

如果啟動服務發現 Port 衝突，你也可以透過 -p 來將預設的監聽的 Port: 3000 調整為其他數值。

1
2
3

nuxi dev -p 3001
# 或
# npm run dev -- -o -p 3001

nuxi cleanup

1

npx nuxi clean|cleanup

nuxi cleanup 等同 nuxi clean 指令，用來刪除 Nuxt 自動產生的檔案和緩存包括：

• .nuxt
• .output
• node_modules/.vite
• node_modules/.cache

nuxi upgrade

1

npx nuxi upgrade [--force|-f]

這個指令可以用來將目前專案的 Nuxt 3 升級至最新的版本，如果有一些可能行為調整或不相容的情況，可以再依據實際情境搭配 -f 參數來強制更新。

如下圖，只要一行指令 npx nuxi upgrade 就可以將專案版本由 3.0.0-rc.9 升級至 3.0.0-rc.10，在 RC 階段或之後想定期升級版本來說非常好用，但也請記得升級前可以先看一下官方的 Changelog。

Nuxt 3 + TypeScript + ESLint + Prettier 環境建置

在我們使用完 Nuxt CLI 建立完專案後，其實就可以開始進行專案的開發，但是呢，相信不少人對於程式碼的排版都有自己的風格，不同人的 Coding Style 肯定也都不一樣，然而在團隊協作需要標準或為了整體一致且美觀下，Linter 就是你的好幫手，此外，TypeScript 在 Nuxt 3 已經有內建支援，我也建議及推薦使用 TypeScript，接下來分享我自己在使用 Nuxt 3 開發時的 Linter 環境配置，包含了 TypeScript、ESLint 與 Prettier。

TypeScript 類型檢查

Nuxt 3 已經有內建支援 TypeScript，一些 TypeScript 設定都可以在專案根目錄下配置 tsconfig.json，例如，在開發過程中針對 TypeScript 我會在開發環境下啟動類型檢查，可以參考以下進行配置。

Step 1. 安裝 VS Code 插件

首先，推薦大家安裝下列兩個 VS Code 插件：

• Vue Language Features (Volar)：寫 Vue 3 強力推薦必裝的插件，包含了上色、語法提示、編輯器快速分割等強大功能，而且也是 Nuxt 3 推薦的編輯器插件。
• TypeScript Vue Plugin (Volar)：Vue 的 TypeScript 插件。

Step 2. 安裝 Vue 類型檢查套件

1
2
3

npm install -D vue-tsc typescript
# or
# yarn add -D vue-tsc typescript

Step 3. 調整 nuxt.config.ts 設定

根據 nuxt3 官方文件說明，我們可以在 nuxt.config.ts 中，設置 typescript.typeCheck: true 來讓開發時期能執行類型檢查。

1
2
3
4
5

export default defineNuxtConfig({
  typescript: {
    typeCheck: true
  }
})

Step 4. 重新啟動開發環境服務

我們重新執行 npm run dev -- -o 來重啟開發環境的服務，這樣就配置完成囉！

看看效果

如果我們在 app.vue 寫了以下程式：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

<template>
  <div>
    <NuxtWelcome />
  </div>
</template>

<script lang="ts" setup>
const year: number = '2022'
const title: string = `${year} iThome 鐵人賽`
</script>

可以發現終端機 (Terminal) 就指出了一個錯誤的類型指派，並告知你有錯誤程式碼的位置。

ESLint 設置 Linter

ESLint 是一個 JavaScript Linter，它用來檢查 JavaScript Coding Style 的工具，主要能幫你分析並找到語法錯誤，也能用來統一風格，例如：縮排空白數、字串要用單引號或雙引號等，提醒你刪掉多餘程式碼或遵照最佳的實踐方式，確保程式碼能具有一定的水準。在團隊協作下 ESLint 更能讓大家撰寫程式碼時遵照規則，確保程式碼品質。ESLint 除了提供你可以使用大公司如 Google、Airbnb 等的規則配置來作為檢查基準，也可以客製自訂出自己喜好或團隊共識的規則來分析與提醒你校正語法。

Step 1. 安裝 ESLint 套件

現在我們至 Nuxt 專根目錄下，開始安裝 ESLint 相關套件，當然，你也可以挑自己喜歡的進行配置，不過在這裡選擇以 Nuxt 3 官方提供的 ESLint 設定來做標準配置，並添加支援 Vue 3 的 ESLint 設定。

1
2
3

npm install -D eslint @nuxtjs/eslint-config-typescript eslint-plugin-vue
# or
# yarn add -D eslint @nuxtjs/eslint-config-typescript eslint-plugin-vue

Step 2. 配置 ESLint 設定檔

安裝完所需套件後，接下來我們就可以來設定 ESLint，我們在專案根目錄下建立 .eslintrc.js 檔案，內容如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

module.exports = {
  env: {
    browser: true,
    es2021: true
  },
  extends: ['@nuxtjs/eslint-config-typescript', 'plugin:vue/vue3-recommended'],
  parserOptions: {
    ecmaVersion: 13,
    sourceType: 'module'
  },
  plugins: [],
  rules: {},
  overrides: [
    {
      files: [
        '**/pages/**/*.{js,ts,vue}',
        '**/layouts/**/*.{js,ts,vue}',
        '**/app.{js,ts,vue}',
        '**/error.{js,ts,vue}'
      ],
      rules: {
        'vue/multi-word-component-names': 'off'
      }
    }
  ]
}

在我們建立的 .eslintrc.js 檔案中 extends 可以是一個陣列，主要是來放置擴展 ESLint 的規則的配置，這裡稍微注意一下順序如下：

1. @nuxtjs/eslint-config-typescript：對應 @nuxtjs/eslint-config-typescript 套件，由 Nuxt 官方提供用於 Nuxt 的 ESLint 規則配置。如果你不是使用 TypeScript 可以使用 @nuxtjs/eslint-config。

2. plugin:vue/vue3-recommended：對應 eslint-plugin-vue 套件，由 Vue.js 官方提供的 ESLint 插件，包含了能配合 Vue SFC 語法及特性的規則，也可以參考官方文件，依據需求稍作調整。

將特定目錄下的檔案關閉 vue/multi-word-component-names 規則，以此來因應 nuxt 的開發避免提示錯誤。

因為目前 @nuxtjs/eslint-config-typescript 是基於 @nuxtjs/eslint-config 來擴展 TypeScript 的設定，而且 @nuxtjs/eslint-config 包含的是 Vue 2 的 ESLint 設定，所以我們需要再額外安裝 eslint-plugin-vue 來擴展 Vue 3 規則配置，並覆寫 vue/multi-word-component-names 規則。

用 ESLint 來嘗試檢查

首先，我們編輯 app.vue 檔案內容如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

<template>
  <div>
    <NuxtWelcome />
  </div>
</template>

<script lang="ts" setup>
const year: number = 2022
const title: string = `${year} iThome 鐵人賽`
</script>

接著我們執行下列指令來使用 eslint 檢查 app.vue 這個檔案。

1

npx eslint -- app.vue

可以看到下圖，ESLint 指出 app.vue 的問題，在第 9 行中的 title 這個變數已經宣告了卻沒有被使用。

這個錯誤訊息正是依據上面我們的 ESLint 配置所被檢視出來的，在 ESLint 規則定義好後，也有分成錯誤 (Error) 與警告 (Warning)，我們可以再依據 ESLint 給予的提示進行調整與修正。

我們嘗試修正一下 app.vue 這個檔案，在 template 中使用 title 這個變數。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

<template>
  <div>
    <h1>{{ title }}</h1>
  </div>
</template>

<script lang="ts" setup>
const year: number = 2022
const title: string = `${year} iThome 鐵人賽`
</script>

再一次執行 npx eslint -- app.vue，就會發現沒有錯誤訊息產生囉！

在 package.json 設置腳本

我們除了逐個檔案做檢查，也可以設置腳本來檢查整個專案目錄下的程式碼。

在 package.json 的 scripts 腳本中，我們可以新增一個指令 "lint": "eslint --ext .ts,.js,.vue ."，這樣一來我們就可以使用如下指令來檢查專案目錄下的所有包含 .ts、.js、.vue 副檔名的檔案。

1
2
3

npm run lint
# or
# yarn run lint

在 VS Code 中顯示 ESLint 錯誤或警告

推薦大家安裝 VS Code 的 ESLint 插件：

• ESLint：讓你在編輯器開發時就能有指令檢查，更可以做到全域或特定工作區開啟儲存或快捷鍵自動修正程式碼等設置。

安裝完畢後，建議重啟 VS Code 來重新載入相關設定。

現在，你會發現在 VS Code 中編輯程式的過程中，如果有 ESLint 檢查到的錯誤或建議，就會出現紅色或黃色的波浪底線，當滑鼠指標移動至波浪底線處，就會發現有個小視窗提示你錯誤或警告的原因是什麼。

在 VS Code 中自動修正 ESLint 錯誤或警告

在某些情況，ESLint 可以幫助你做自動修正程式碼，甚至在存擋時將錯誤部分直接進行修正。

手動快速修正

我們可以在編輯器將滑鼠指標移動至波浪底線點擊「快速修正 (Quick Fix)…」，你也可以使用編輯器建議的快捷鍵 Command + . (macOS)，此時就能選擇要修復或關閉略過錯誤原因；這裡我們選擇「Fix all auto-fixable problems」，來修復所有可能可以被自動修復的問題。

存擋自動修正

除了手動快速修正外，你也可以透過添加 VS Code 的設定檔，如專案目錄下新增 .vscode/settings.json：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

{
  "editor.formatOnSave": true,
  "prettier.semi": false,
  "files.trimTrailingWhitespace": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "eslint.format.enable": true,
  "eslint.validate": ["javascript", "javascriptreact", "html", "vue", "typescript", "typescriptreact"],
  "eslint.enable": false
}

當我們編輯完程式碼，並保存檔案或快捷鍵存擋 Command + S (macOS)，就會觸發 ESLint 自動修復囉。

Prettier 設置

Prettier 是程式碼格式化的工具，也可以與 ESLint 進行搭配，ESLint 與 Prettier 就能各司其職將 JaveScript 與 Vue 等檔案依照配置進行檢查與排版。

Step 1. 安裝 Prettier 套件

我們直接安裝 prettier、eslint-config-prettier 與 eslint-plugin-prettier 三個套件。

1
2
3

npm install -D prettier eslint-config-prettier eslint-plugin-prettier
# or
# yarn add -D prettier eslint-config-prettier eslint-plugin-prettier

Step 2. 配置 Prettier 設定檔案

我們在專案根目錄下建立 .prettierrc.js 檔案，內容如下，這些配置都可以自己設定來配合 ESLint，更多選項或說明可以參考 Prettier 官方說明文件。

1
2
3
4
5
6
7
8

module.exports = {
  printWidth: 120, // 每行文字數量達 100 字元就換到新的一行
  semi: false, // 每個語句的結尾不需要分號
  singleQuote: false, // 字串使用單引號，而不是雙引號
  trailingComma: "none", // 如 Object、Array 內的元素不需要尾隨逗號
  endOfLine: "auto",
  vueIndentScriptAndStyle: true
}

Step 3. 配置 ESLint 設定檔案

我們在安裝時多裝了兩個 ESLint 相關套件，分別為 eslint-config-prettier 及 eslint-plugin-prettier。

對此我們需要將其添加至 ESLint 的 .eslintrc.js 設定檔內，在 extends 添加字串 prettier 表示使用 eslint-config-prettier 擴充配置，主要用來防止 Prettier 排版與 ESLint 發生衝突，讓其可以用來禁用 ESLint 的格式化；接著在 plugins 中添加 prettier 字串表示使用 eslint-plugin-prettier 套件擴充，讓 ESLint 可以提示我們格式有錯誤的地方。

為了讓 Prettier 與 ESLint 有更好的搭配，在 rules 的參數中記得添加 'prettier/prettier': 'error' 讓 ESLint 可以提示 Prettier 的排版異常提示供我們做修正，至此 .eslintrc.js 設定檔應該會如下。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

module.exports = {
  env: {
    browser: true,
    es2021: true
  },
  extends: [
    '@nuxtjs/eslint-config-typescript',
    'plugin:vue/vue3-recommended',
    'prettier'
  ],
  parserOptions: {
    ecmaVersion: 13,
    sourceType: 'module'
  },
  plugins: ['prettier'],
  rules: {
    'prettier/prettier': 'error'
  },
  overrides: [
    {
      files: [
        '**/pages/**/*.{js,ts,vue}',
        '**/layouts/**/*.{js,ts,vue}',
        '**/app.{js,ts,vue}',
        '**/error.{js,ts,vue}'
      ],
      rules: {
        'vue/multi-word-component-names': 'off'
      }
    }
  ]
}

Step 4. 安裝 VS Code 的 Prettier 插件

• Prettier - Code formatter：提供我們做程式碼的格式化，最重要的是來協助我們自動載入 .prettierrc.js 配置。

安裝完畢後，建議重啟 VS Code 來重新載入相關設定。

我們完成了 TypeScript 與 Linter 的配置，雖然配置有些繁瑣，但寫程式的風格有個標準及規則依循，肯定能協助你寫出令人讚嘆的完美的程式碼。

使用 Tailwind CSS

為了後續範例程式在頁面呈現上能有比較好看的樣式，原先有想過使用 UI 框架或純寫 CSS，但是總覺得好像不夠潮，所以呢，我決定帶入近年滿熱門的 CSS 框架 Tailwind CSS，在本篇文章我就不再多花篇幅介紹 Tailwind 的語法及指令等，主要針對 Nuxt 3 如何導入 Tailwind CSS 至專案內使用。

其實有稍微糾結一下要不要使用 Master CSS，雖然最後決定先緩緩，但我認為它非常有淺力成為這類框架的霸主，大家有空也可以支持一下或玩玩這個由臺灣團隊開發的 CSS 框架哦！

Tailwind CSS 是近年滿熱門的 Utility-First CSS 框架，曾掀起一番論戰說 Class 不是讓你這樣用的之類的批評及缺點，但如果你深入暸解它後，確實不可否認它能為你帶來更好的生產效率等諸多優點。

接下來，我會分別介紹兩種導入 Tailwind CSS 方式，分別為 Nuxt Community 釋出的 Tailwind CSS 整合模組 及 Tailwind CSS 官方指引步驟，以下的 A 或 B 兩種導入方式，大家只要擇一就可以了。

使用 Nuxt Tailwind 模組

Step 1. 安裝相關套件

首先安裝 @nuxtjs/tailwindcss。

1
2
3

npm install -D @nuxtjs/tailwindcss
# or
# yarn add -D @nuxtjs/tailwindcss

Step 2. 添加模組至 nuxt.config.ts

打開 ./nuxt.config.ts 將 @nuxtjs/tailwindcss 模組添加至 modules 設定參數中，完成後看起來會像下面這樣。

1
2
3
4
5
6
7

// https://v3.nuxtjs.org/api/configuration/nuxt.config
export default defineNuxtConfig({
  modules: ['@nuxtjs/tailwindcss'],
  typescript: {
    typeCheck: true
  }
})

Step 3. 重啟 Nuxt 服務

重新啟動我們的 Nuxt 服務。

1
2
3

npm run dev -- -o
# or
# yarn run dev -- -o

使用 @nuxtjs/tailwindcss 只需要兩個步驟就完成了 Tailwind CSS 的配置，這個模組已經包含手動安裝時需要建立的 Tailwind CSS 指令 tailwindcss.css 需要的全域設定與 PostCSS 參數選項，同時也預設了 tailwind.config.js 的相關 content 目錄路徑，詳細可以參考 Nuxt Tailwind。

擴充或覆寫 @nuxtjs/tailwindcss 配置

如果你沒有特別需要擴充或覆寫設定可以跳過這一段。

專案內若使用 @nuxtjs/tailwindcss 模組，這兩個 tailwind.css 與 tailwind.config.js 檔案其實模組已經有預設，不需要手動建立，tailwind.css 對應模組內的 tailwind.css 可以參考專案檔案內容 tailwind.css，tailwind.config.js 則是透過模組動態新增配置。

倘若想要修改也可以透過建立設定檔案來新增或覆寫預設定，例如在專案下分別建立 tailwind.css 與 tailwind.config.js 兩個檔案：

• tailwind.css

專案目錄下若存在路徑檔名一致的 ./assets/css/tailwind.css 檔案，@nuxtjs/tailwindcss 就會以這個檔案取代模組內預設的 tailwind.css 檔案。

tailwind.css 預設內容如下：

1
2
3

@tailwind base;
@tailwind components;
@tailwind utilities;

如果有成功覆蓋配置，在重啟 Nuxt 3 服務時，Terminal 會提示下列字串，表示使用了自訂的 tailwind.css。

1

Using Tailwind CSS from ~/assets/css/tailwind.css

• tailwind.config.js

專案目錄下若存在 tailwind.config.js 檔案就會以新的配置拓展或覆寫 @nuxtjs/tailwindcss 預設的 tailwind.config。

例如，我們想拓展或覆寫 content 的配置：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    './components/**/*.{vue,js,ts}',
    './layouts/**/*.vue',
    './pages/**/*.vue',
    './composables/**/*.{js,ts}',
    './plugins/**/*.{js,ts}',
    './app.{js,ts,vue}'
  ],
  theme: {
    extend: {}
  },
  plugins: []
}

Tailwind CSS 官方指引步驟

如果你已經使用了 @nuxtjs/tailwindcss 進行配置，則可以跳過這一段。

Step 1. 安裝相關套件

首先進入我們的 Nuxt 專案目錄，並安裝 Tailwind CSS 會使用到的一些相關套件。

1
2
3

npm install -D tailwindcss postcss@latest postcss-custom-properties@latest autoprefixer@latest
# or
# yarn add -D tailwindcss postcss@latest postcss-custom-properties@latest autoprefixer@latest

Step 2. 建立 tailwind.config.js

安裝完套件後，可以執行下列指令進行初始化，完成後會在專案根目錄下產生一個名為 tailwind.config.js 的 Tailwind CSS 設定檔。

1

npx tailwindcss init

Step 3. 調整 tailwind.config.js

打開剛剛產生的設定檔 tailwind.config.js，在配置中的 content 陣列添加一些路徑，這些路徑皆是跟 Nuxt 有關的資料夾目錄與檔案，完成後檔案內容如下。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    './components/**/*.{vue,js,ts}',
    './layouts/**/*.vue',
    './pages/**/*.vue',
    './composables/**/*.{js,ts}',
    './plugins/**/*.{js,ts}',
    './app.{js,ts,vue}'
  ],
  theme: {
    extend: {}
  },
  plugins: []
}

Step 4. 建立 tailwind.css

接著我們在專案建立目錄 assets 與子目錄 css 用來放置 Tailwind CSS 的自定義指令，我們將其放置在 tailwind.css 供後續做使用，tailwind.css 的路徑應會是 ./assets/css/tailwind.css 檔案內容如下。

1
2
3

@tailwind base;
@tailwind components;
@tailwind utilities;

Step 5. 配置全域共用 CSS

上面我們建立好 tailwind.css 後，為了讓每個頁面都可以吃得到 Tailwind CSS，我們修改專案根目錄的 nuxt.config.ts 檔案，在 css 參數陣列內新增 tailwind.css 路徑，讓 Nuxt 可以配置全域共用的 CSS，並添加 postcss 選項及我們剛才安裝的套件作為插件，最後 nuxt.config.ts 檔案看起來如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

// https://v3.nuxtjs.org/api/configuration/nuxt.config
export default defineNuxtConfig({
  postcss: {
    plugins: {
      'postcss-import': {},
      'tailwindcss/nesting': {},
      tailwindcss: {},
      autoprefixer: {}
    }
  },
  css: ['@/assets/css/tailwind.css'],
  typescript: {
    typeCheck: true
  }
})

至此，我們專案目錄檔案如下結構。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

nuxt-app
├── .nuxt/
├── assets/
│   └── css/
│       └── tailwind.css      // 手動新增的檔案，用於設置 Tailwind CSS 指令並讓全部頁面引用
├── node_modules/
├── .eslintrc.js
├── .gitignore
├── .prettierrc.js
├── app.vue
├── nuxt.config.ts
├── package-lock.json
├── package.json
├── README.md
├── tailwind.config.js       // Tailwind 初始化指令產生的設定檔
└── tsconfig.json

Step 6. 重啟 Nuxt 服務

重新啟動我們的 Nuxt 服務。

1

npm run dev -- -o

開始感受 Tailwind CSS 的魅力

當我們配置完 Tailwind CSS 並重啟 Nuxt 服務後，我們編輯 app.vue 檔案內容，撰寫以下程式碼：

1
2
3
4
5
6
7
8

<template>
  <div class="bg-white py-24">
    <div class="flex flex-col items-center">
      <h1 class="text-6xl font-semibold text-blue-600">2022 iThome</h1>
      <p class="mt-4 text-9xl font-bold text-gray-900">鐵人賽</p>
    </div>
  </div>
</template>

重新瀏覽一次網頁，可以發現排版、顏色、字型都有出現我們設定的效果了。

自動排序 Tailwind CSS 的 Class

當我們在寫 Tailwind CSS 時終究會碰到類型過多，第一眼不確定是否包含某個 class，或者對於順序上有強烈統一的要求，那麼這個 Prettier 的插件，prettier-plugin-tailwindcss 插件是 Tailwind 推出的，目的在於可以使用官方推薦的 class 順序，來實現自動排序 class 來做到統一程式碼風格。

Tailwind x Prettier

Step 1. 安裝插件

1
2
3

npm install -D prettier-plugin-tailwindcss
# or
# yarn add -D prettier-plugin-tailwindcss

如果你不是照著前面的步驟建置專案，請記得確認已經有安裝 prettier 套件。

Step 2. 配置設定檔

開啟 .prettierrc.js 檔案，添加 'prettier-plugin-tailwindcss' 至 plugins 陣列中：

1
2
3
4
5
6
7
8
9

module.exports = {
  plugins: [
    'prettier-plugin-tailwindcss'
  ],
  printWidth: 100,          // 每行文字數量達 100 字元就換到新的一行
  semi: false,              // 每個語句的結尾不需要分號
  singleQuote: false,        // 字串使用單引號，而不是雙引號
  trailingComma: 'none'     // 如 Object、Array 內的元素不需要尾隨逗號
}

Step 3. 自動修正效果

你可以在編輯器內移至錯誤波浪底線使用「快速修復 (Quick Fix)…」功能，或設置 "editor.codeActionsOnSave" 中 "source.fixAll.eslint": true 來達到保存後自動修正 prettier 引發的 ESLint 錯誤。

小結

相較於 Tailwind CSS 官方指引的安裝方式，使用 Nuxt Community 幫我們整理好的 @nuxtjs/tailwindcss 模組，可以省去繁瑣的設定步驟，也解決了一些目前 Nuxt 3 專案中，導入 Tailwind CSS 使用 HMR 可能無法自動編譯並重新套用等問題。

使用 Pug

pug 為 html 模板語言，可支援撰寫 JS 邏輯。寫法上，省略了 HTML 的開、閉合標籤，能夠大大的提升工程師開發速度，看上去也更為簡潔。

在本篇文章我依舊不再多花篇幅介紹 pug 的語法，主要針對 Nuxt 3 如何導入 pug 至專案內使用。

為了之後開發能少打一點 Code，這邊加入 pug 到專案。

安裝 @vite-plugin-pug

1
2
3

npm install -D vite-plugin-pug
# or
# yarn add -D vite-plugin-pug

直接開始體驗 Pug

直接將原先的 app.vue 改用 pug 語法來撰寫：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

<template lang="pug">
div
  .bg-white.py-24
  .flex-col.items-center.flex
    h1.text-6xl.font-semibold.text-blue-600 2022 iThome
    p.mt-4.text-9xl.font-bold.text-gray-900 鐵人賽
</template>

<script lang="ts" setup>
const year: string = "2022"
</script>

這邊推薦一款 VS Code 的套件 - html2pug，將 HTML 反白後點選 VS Code 上方的 View > Command Palette…，尋找並執行 "> html2pug: Transform"，即可將反白的 HTML 自動轉換成 pug 語法。

不用管 HTML 的結尾符號，寫起來整個就是舒服阿~~~

目錄結構與自動載入 (Auto Imports)

隨著整個專案的開發，目錄與元件勢必也會越來越多，如同 Vue 3 的專案可能會有專門放置元件目錄 components 等，在 Vue 3 我們可能不太需要去在意目錄的名稱，但在 Nuxt 3 的專案下，有一些目錄與名稱其實有一些基本的規定與名稱，只要照著 Nuxt 3 約定好的方式進行開發，就能更好利用 Nuxt 3 幫你完成許多貼心的功能。

Nuxt 3 的目錄結構

當我們 Nuxt CLI 建立第一個 Nuxt 3 專案並第一次啟動開發伺服器後，專案目錄結構會長得像這樣：

如果你是跟著這個系列安裝了 TypeScript、Linter、Tailwind CSS 及 Pug 等套件，那麼專案目錄結構會長得像這樣：

雖然我們能依照需求建立檔案及目錄，但 Nuxt 3 在目錄的結構與命名其實有一定的規則與模式，以下針對 Nuxt 3 來講述一下目錄的結構與遵循的方式。

Nuxt 3 預設的目錄結構

Nuxt 3 框架希望我們可以專注在開發而不是在配置，所以在預設的情況專案的目錄架構已經有一個不錯的結構可以遵循。

依據官方文件，一個完整的 Nuxt 3 專案，它的目錄結構如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

nuxt-app/
├── .nuxt/
├── .output/
├── assets/
├── components/
├── composables/
├── content/
├── layouts/
├── middleware/
├── node_modules/
├── pages/
├── plugins/
├── public/
└── server/
    ├── api/
    ├── routes/
    └── middleware/
├── .gitignore
├── .nuxtignore
├── app.config.ts
├── app.vue
├── nuxt.config.ts
├── package.json
└── tsconfig.json

.nuxt 目錄

開發環境下由 Nuxt 產生出 Vue 的網站，.nuxt 目錄是自動產生的，你不應該任意的調整裡面檔案。

.output 目錄

當你的網站準備部署至正式環境時，每次編譯建構專案時，皆會自動重新產生這個目錄，你不應該任意的調整裡面檔案。

assets 目錄

顧名思義，這是靜態資源檔案所放置的位置，目錄內通常包含以下類型的檔案：

• CSS 樣式檔案 (CSS、SASS 等…)
• 字型
• 圖片

這些靜態資源，最終在專案編譯建構時，由 Vite 或 webpack 進行編譯打包。

components 目錄

放置 Vue 元件的地方，Nuxt 會自動載入這個目錄中的任何元件。

composables 目錄

組合式函數放置的目錄，簡單來說可以把常用或通用的功能寫成一個共用的函數或 JS 檔案，放置在這個目錄視為組合式函數，Nuxt 也會自動載入這些組合式函數，讓需要使用的頁面或元件可以直接做使用。

content 目錄

透過使用 Nuxt Content，我們可以在這個目錄下建立 .md、.yml、.csv 和 .json 檔案，Nuxt Content 會讀取並解析這些文件並進行渲染，用來建立基於文件的內容管理系統(Content Management System，簡稱：CMS)。

layouts 目錄

用於放置通用或可能重複使用到的佈局模板，提供程式碼的可重複使用性。

middleware 目錄

Nuxt 3 提供了路由中間件的概念，用於導航到下一個頁面之前執行一些程式碼如權限驗證…等。

node_modules 目錄

通常有使用 Node.js 的套件管理，例如 NPM，對此目錄應該有一些印象，使用 Nuxt 3 及專案所需要的相依套件都會存放在這個目錄。

pages 目錄

這個目錄主要是用來配置我們的頁面，你也可以只使用 app.vue 來完成你的網站，但如果建立了 pages 這個目錄，Nuxt 3 會自動整合 vue-router，並會依據目錄及檔案結構規則來自動產生出對應路由，也是 Nuxt3 產生路由的方式。

plugins 目錄

Nuxt 會自動載入這個目錄檔案，作為插件使用，在檔案名稱可以使用後綴 .server 或 .client，例如，plugin.server.ts 或 plugin.client.ts 來決定只讓伺服器端或客戶端載入這個插件。

server 目錄

用於建立任何後端的邏輯如後端 API，這個目錄下還包含了 api、server 和 middleware 來區分功能，不具有自動載入，但支援 HMR。

.gitignore 檔案

在使用 Git 版本控制時，可以設置一些不需要或忽略關注變動的檔案及目錄。

.nuxtignore 檔案

可以設置讓 Nuxt 編譯建構時，忽略一些不需要或欲忽略的檔案。

app.config.ts 檔案

提供服務運行時暴露給客戶端使用的設定，因此，請不要在 app.config.ts 檔案中添加任何機密資訊。

app.vue 檔案

Nuxt 3 網站的入口點元件。

nuxt.config.ts 檔案

用於配置 Nuxt 專案的設定檔。

package.json 檔案

這個檔案裡面定義了專案資訊、腳本、相依套件及版本號，通常有使用 Node.js 套件管理工具建置的專案都會包含此檔案。

tsconfig.json 檔案

Nuxt 3 會在 .nuxt 目錄下自動產生一個 tsconfig.json 檔案，其中已經包含了一些解析別名等預設配置；你可以透過專案目錄下的 tsconfig.json 來配置擴展或覆蓋 Nuxt 3 預設的 TypeScript 設定檔。

自訂目錄名稱

前面簡介了 Nuxt 3 的預設目錄結構與用途，在目錄名稱上 Nuxt 3 也提供了可以調整目錄名稱的方式，只要在 nuxt.config.ts 修改對應的參數，就可以自訂目錄的名稱。不過呢，也並不是所有的目錄都能修改，目前官方提供的 dir 參數共有以下四個目錄參數選項供修改：

• layouts
• middleware
• pages
• public

例如我想將 pages 目錄名稱調整為 views 就可以新增下列 dir 設定添加至 nuxt.config.ts，就可以將 pages 目錄功能及規則調整為 views 目錄來實現。

1
2
3
4
5

export default defineNuxtConfig({
  dir: {
    pages: 'views',
  }
}

自動載入 (Auto Imports)

在介紹目錄結構時有提到，某些目錄下的檔案是具有自動載入 (Auto Imports)的功能，意思就是說，當我們在這些特定的目錄 components、composables、layouts、plugins 添加檔案時，Nuxt 3 會自動載入這些元件或函數。

Nuxt 3 的自動載入具體有以下三種：

• Nuxt 常用元件與函數
• Vue 3 的 API
• 基於目錄的自動載入

Nuxt 常用元件與函數的自動載入

Nuxt 會自動載入一些元件或組合式函數，用以讓開發時可以在全部頁面或定義組件和插件可以使用。

Nuxt 自動載入的元件就好比 app.vue 程式碼內，一開始在 template 就有的 <NuxtWelcome /> 歡迎頁面元件，其他還包含了 <NuxtPage>、<NuxtLayout> 和 <NuxtLink> 等，詳細可以參考官方文件。

例如，下面程式碼中的 useAsyncData 與 $fetch 就是 Nuxt 自動載入的組合式函數，在各個頁面或元件都能做使用。

1
2
3

<script setup>
const { data, refresh, pending } = await useAsyncData('/api/hello', () => $fetch('/api/hello'))
</script>

Vue 3 API 的自動載入

例如，Vue 3 中會使用到的 ref、computed 等這類的 helpers 或 lifecycle hooks，在 Nuxt 3 也都將會自動的載入，不需要在 import。

1
2
3
4
5

<script setup>
// 不需要在 import ref 或 computed
const count = ref(1)
const double = computed(() => count.value * 2)
</script>

基於目錄的自動載入

如前面所提及的，Nuxt 會自動載入定義在特定目錄的檔案，例如：

• components: 相對於 Vue 的組件。
• composables: 相對於 Vue 的組合式函數。

建立一個自動導入的元件

我們建立一個 ./components/IronManWelcome.vue 檔案：

components/IronManWelcome.vue

1
2
3
4
5
6
7
8

<template>
  <div class="bg-white py-24">
    <div class="flex flex-col items-center">
      <h1 class="text-6xl font-semibold text-sky-400">2022 iThome</h1>
      <p class="mt-4 text-9xl font-bold text-gray-600">鐵人賽</p>
    </div>
  </div>
</template>

在 app.vue 檔案中，新增 <IronManWelcome /> 元件。

app.vue

1
2
3
4
5

<template>
  <div>
    <IronManWelcome />
  </div>
</template>

現在，瀏覽器可以看見我們添加的元件效果。

可以發現，我們不需要添加 import IronManWelcome from './components/IronManWelcome' 就可以直接在 template 直接使用 <IronManWelcome /> 元件，這就是 Nuxt 3 基於目錄的自動載入功能。

關閉自動載入

如果想關閉 Nuxt 的自動載入元件或函數的功能，可以修改專案目錄下的 nuxt.config.ts 檔案，將 imports.autoImport 設定為 false。

nuxt.config.ts

1
2
3
4
5

export default defineNuxtConfig({
  imports: {
    autoImport: false
  }
})

顯式載入 (Explicit Imports)

Explicit (顯式、明確的)，當我們需要手動載入，就可以用 #import 這個 Nuxt 釋出的別名，來個別載入那些具有自動載入的元件或函數。

1
2
3
4
5
6

<script setup>
import { ref, computed } from '#imports'

const count = ref(1)
const double = computed(() => count.value * 2)
</script>

Nuxt 3 的專案目錄與結構已經有一個規定可以遵守，Nuxt 3 規劃的目錄及檔案架構，讓我們可以不用再煩惱該如何配置，只需要專注開發，當你熟悉這些目錄檔案規則與自動載入的特性，肯定能更快上手 Nuxt 3。

頁面 (Pages) 與路由 (Routing)

在 Vue 中，我們會使用到 Vue Router 來實現切換頁面或路由的需求，而在 Nuxt 3 中，預設是沒有使用路由相關套件，直至建立了 pages 目錄，Nuxt 將會自動載入 Vue Router 來管理路由，並且具有一定的規則需要遵循，以下將介紹頁面目錄與路由之間的關係。

基於檔案的路由 (File-based Routing)

在 Nuxt 3 專案的 pages 目錄下，當我們建立了一個頁面檔案，就會以該檔案建立出相對應的路由，Nuxt 3 基於檔案的路由，也使用了程式碼拆分將每個頁面需要的程式碼梳理出來，並以動態載入的方式載入最小所需要的程式碼。因為是以目錄結構與檔案命名方式來約定，也稱之為約定式路由。

建立第一個頁面

Nuxt 3 的 pages 目錄，是用來建立頁面並放置的目錄，當專案下有存在 pages 目錄，Nuxt 將會自動載入 Vue Router 來實現路由效果，目錄下的檔案通常是 Vue 的元件，也允許具有 .vue、.js、.jsx、.ts 或 .tsx 副檔名的檔案。

當我們建立 ./pages/index.vue，檔案內容如下，則表示路由 / 對應到這個頁面檔案，我們只需要建立檔案，路由的配置將會由 Nuxt 3 自動產生。

pages/index.vue

1
2
3
4
5
6
7

<template>
  <div class="bg-white py-24">
    <div class="flex flex-col items-center">
      <h1 class="text-6xl font-semibold text-gray-800">這裡是首頁</h1>
    </div>
  </div>
</template>

若你還記得 Vue Router 中的 <router-view />，這是路由需要的進入點，同樣的在 Nuxt 3 我們需要使用 <NuxtPage /> 來顯示我們建立的路由頁面，這裡非常重要，否則路由及頁面將無法正確運作。

修改 ./app.vue，檔案內容如下：

app.vue

1
2
3
4
5

<template>
  <div>
    <NuxtPage />
  </div>
</template>

接著我們在瀏覽器瀏覽 / 路由，如 http://localhost:3000/，就可以看到我們在 ./pages/index.vue 頁面內寫的標題文字「這是首頁」囉！

多個路由頁面

在實務上，通常一個網站會有多個頁面，並分別對應到不同的路由，接下來我們嘗試建立 About 與 Contact 兩個頁面。

建立多個路由頁面

建立 ./pages/about.vue，內容如下：

pages/about.vue

1
2
3
4
5
6
7
8

<template>
  <div class="bg-white py-24">
    <div class="flex flex-col items-center">
      <h1 class="text-6xl font-semibold text-yellow-400">大家好！我是 Ryan</h1>
      <p class="my-8 text-3xl text-gray-600">這裡是 /about</p>
    </div>
  </div>
</template>

建立 ./pages/contact.vue，內容如下：

pages/contact.vue

1
2
3
4
5
6
7
8

<template>
  <div class="bg-white py-24">
    <div class="flex flex-col items-center">
      <h1 class="text-6xl font-semibold text-rose-400">如果沒事不要找我 xDDD</h1>
      <p class="my-8 text-3xl text-gray-600">這裡是 /contact</p>
    </div>
  </div>
</template>

接著我們在瀏覽器分別瀏覽 /about 或 /contact，就可以看到我們路由效果囉！

可以發現所建立的檔案名稱，最終就會自動對應產生出 /about 及 /contact 路由。

自動產生的路由

如果你有興趣想看看 Nuxt 自動產生出來的路由配置長什麼樣子，可以使用 npm run build 或 npx nuxt build 來建構出 .output 目錄，並打開 .output/server/chunks/app/server.mjs，搜尋 const _routes = 或剛剛建立的檔案名稱 about.vue，就可以找到下面這一段程式碼：

這段程式碼與 Vue 中的路由配置非常相像，其實這就是 Nuxt 3 檢測到 pages 目錄，自動幫我們載入 Vue Router 與依據 pages 目錄下的檔案結構，自動產生出所需的路由配置。

建立路由連結

在 Vue Router 我們可以使用 <router-link> 來建立路由連結，以此來導航至其他頁面，而在 Nuxt 3 的路由中，則是使用 <NuxtLink> 來建立路由連結來進行頁面的跳轉，我們嘗試在首頁新增幾個路由連結來進行頁面導航。

調整 ./pages/index.vue，內容如下：

pages/index.vue

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

<template>
  <div class="bg-white py-24">
    <div class="flex flex-col items-center">
      <h1 class="text-6xl font-semibold text-gray-800">這裡是首頁</h1>
      <div class="my-4 flex space-x-4">
        <NuxtLink to="/about">前往 About</NuxtLink>
        <NuxtLink to="/contact">前往 Contact</NuxtLink>
      </div>
    </div>
  </div>
</template>

接著我們在瀏覽器瀏覽首頁，點擊「前往 About」或「前往 Contact」就可以看見路由導航效果囉！

使用 <NuxtLink> 時，可以就把它想像為 <router-link> 的替代品，像 to 這個 Pros 控制路由位置的用法基本上一樣，其他更多的 Pros 用法及說明可以參考官網的文件。

如果想要使用像 Vue Router 提供的 router.push 方法於 Vue 中直接呼叫來導航至其他頁面，在 Nuxt 中你可以使用 navigateTo，參數可以參考官方文件。

約定式路由中的 index.vue

在開頭有提到，Nuxt 3 提供了一個基於檔案的路由，從上述例子你或許能發現，基本上檔案名稱就是對應著路由名稱，但 index.vue 比較特別，它所對應的是路由 /。

index.[ext] 這個效果和特性，其實是與 Node.js 底層核心有關，在此就不贅述。

舉例來說，我可以在 pages 下建立一個 docs.vue 表示對應路由 /docs，也可以將檔案放置在 docs 目錄下並重新命名為 index.vue 即 ./pages/docs/index.vue，這樣也可以透過 /docs 瀏覽到相同的頁面。

所以當 index.vue 存在於 pages 目錄下，已經位於網站頁面的第一層，所以我們瀏覽 http://localhost:3000/ 就可以做出首頁的效果。

帶參數的動態路由匹配

在實務上，我們可能需要將路徑作為參數傳遞給同一個元件，例如，我們有一個 users 頁面元件，在 /users/ryan 或 /users/jennifer 路徑，都能匹配到同一個 users 元件，並將 ryan 或 jennifer 當作參數傳遞給 users 頁面元件使用，那麼我們就需要動態路由來做到這件事。

在 Vue 3 使用 Vue Router 我們可能會寫出如下路由配置：

1
2
3
4
5

{
  name: "users",
  path: "/users/:id",
  component: "./pages/users.vue",
}

這樣我們就能達到進入 /users/ryan 路由將 ryan 當作 id 參數傳入 users 元件中，路徑參數用冒號 : 表示，這個被匹配的參數 (params)，會在元件中可以使用 useRoute() 與 route.params.id 取得。

在 Nuxt 3 中，我們要實現這個效果，需要將檔案名稱添加中括號 []，其中放入欲設定的參數名稱，譬如下面的目錄結構與檔案名稱。

1
2
3

./pages/
└── users/
    └── [id].vue

建立 ./pages/users/[id].vue 檔案，內容如下：

pages/users/[id].vue

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

<template>
  <div class="bg-white py-24">
    <div class="flex flex-col items-center">
      <h1 class="text-3xl text-gray-600">這裡是 Users 動態路由頁面</h1>
      <p class="my-8 text-3xl text-gray-600">
        匹配到的 Id: <span class="text-5xl font-semibold text-blue-600">{{ id }}</span>
      </p>
    </div>
  </div>
</template>

<script setup>
const route = useRoute()
const { id } = route.params
</script>

我們在 script 就可以從 route.params 拿到我們所設定的參數名稱 id，並將其在 template 中渲染出來。瀏覽 http://localhost:3000/users/ryan ，看看效果，Nuxt 3 就能匹配到使用者的 id 參數 ryan，並傳入 users 頁面元件。

你也可以在 template 直接使用 {{ $route.params.id }} 來渲染出 id 參數。

匹配所有層級的路由

如果你需要匹配某個頁面下的所有層級的路由，你可以在參數前面加上 ... ，例如，[...slug].vue，這將匹配該路徑下的所有路由。

建立 ./catch-all/[…slug].vue 檔案：

1
2
3

./pages/
└── catch-all/
    └── [...slug].vue

./catch-all/[…slug].vue 檔案內容如下：

catch-all/[…slug].vue

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

<template>
  <div class="bg-white py-24">
    <div class="flex flex-col items-center">
      <h1 class="text-4xl text-gray-800">這是 catch-all/... 下的頁面</h1>
      <p class="mt-8 text-3xl text-gray-600">匹配到的 Params:</p>
      <p class="my-4 text-5xl font-semibold text-violet-500">{{ $route.params.slug }}</p>
      <span class="text-xl text-gray-400">每個陣列元素對應一個層級</span>
    </div>
  </div>
</template>

我們可以輸入 /catch-all/hello 及 /catch-all/hello/world，路由的參數 slug 就會是一個陣列，陣列的每個元素對應每一個層級。

建立 404 Not Found 頁面

Nuxt 3 提供一個配置來處理 404 Not Found 的頁面，當我們建立 ./pages/[…slug].vue 頁面， Nuxt 3 所有未匹配的路由，將會交由這個頁面元件做處理，並同時使用 setResponseStatus(404) 函數設定 404 HTTP Status Code。

pages/[…slug].vue

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

<template>
  <div class="bg-white py-24">
    <div class="flex flex-col items-center">
      <h1 class="text-8xl font-semibold text-red-500">404</h1>
      <p class="my-8 text-3xl text-gray-800">Not Found</p>
      <p class="my-8 text-xl text-gray-800">真的是找不到這個頁面啦 >///<</p>
    </div>
  </div>
</template>

<script setup>
setResponseStatus(404)
</script>

/omg 這個是不存在的頁面，未匹配的路由就會交由 ./pages/[…slug].vue 頁面來處理。

建立多層的目錄結構

如果理解了動態路由的中括號 [] 用法，那我們就可以建立更複雜的頁面目錄結構：

1
2
3
4
5
6
7
8

./pages/
└── posts/
    ├── [postId]/
    │   ├── comments/
    │   │   └── [commentId].vue
    │   └── index.vue
    ├── index.vue
    └── top-[number].vue

這四個 Vue 頁面的參考程式碼如下：

pages/posts/index.vue

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

<template>
  <div class="bg-white py-24">
    <div class="flex flex-col items-center">
      <h1 class="text-4xl text-gray-600">這是 Posts 首頁</h1>
      <div class="my-4 flex space-x-4">
        <NuxtLink to="/posts/8"> 前往指定的文章 </NuxtLink>
        <NuxtLink to="/posts/8/comments/1">前往指定的文章留言</NuxtLink>
        <NuxtLink to="/posts/top-3">前往 Top 3</NuxtLink>
        <NuxtLink to="/posts/top-10">前往 Top 10</NuxtLink>
      </div>
    </div>
  </div>
</template>

pages/posts/top-[number].vue

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

<template>
  <div class="bg-white py-24">
    <div class="flex flex-col items-center">
      <h1 class="text-3xl text-gray-600">這是 posts/top-[number] 的頁面</h1>
      <p class="my-8 text-3xl text-gray-600">
        匹配到的 Top Number: <span class="text-5xl font-semibold text-rose-500">{{ number }}</span>
      </p>
    </div>
  </div>
</template>

<script setup>
const route = useRoute()
const { number } = route.params
</script>

pages/posts/[postId]/index.vue

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

<template>
  <div class="bg-white py-24">
    <div class="flex flex-col items-center">
      <h1 class="text-3xl text-gray-600">這是 posts/[postId] 的頁面</h1>
      <p class="my-8 text-3xl text-gray-600">
        匹配到的 Post Id: <span class="text-5xl font-semibold text-blue-600">{{ postId }}</span>
      </p>
    </div>
  </div>
</template>

<script setup>
const route = useRoute()
const { postId } = route.params
</script>

pages/posts/[postId]/comments/[commentId].vue

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

<template>
  <div class="bg-white py-24">
    <div class="flex flex-col items-center">
      <h1 class="text-3xl text-gray-600">這是 posts/[postId]/comments/[commentId] 的頁面</h1>
      <p class="my-8 text-3xl text-gray-600">
        匹配到的 Post Id: <span class="text-5xl font-semibold text-blue-600">{{ postId }}</span>
      </p>
      <p class="my-8 text-3xl text-gray-600">
        匹配到的 Comment Id:
        <span class="text-5xl font-semibold text-purple-400">{{ commentId }}</span>
      </p>
    </div>
  </div>
</template>

<script setup>
const route = useRoute()
const { postId, commentId } = route.params
</script>

來看看實際路由及匹配效果。

為了方便理解，整理了以下表格，來表示頁面結構及期望匹配的模式與參數：

./pages/posts/index.vue：

./pages/posts/top-[number].vue：

./pages/posts/[postId]/index.vue：

./pages/posts/[postId]/comment/[commentId].vue：

到這裡應該對於如何使用檔案名稱與目錄結構，來製作動態路由與匹配參數有一些概念了。

巢狀路由 (Nested Routes)

巢狀路由 (Nested Routes) 或稱嵌套路由，顧名思義，當我們想要在一個頁面鑲嵌另一個頁面時，就需要巢狀路由來幫助我們。

例如，我們想要在 docs 頁面元件中顯示 doc-1 或 doc-2 頁面元件，並在切換 doc-1 或 doc-2 頁面時，只是在 docs 下的嵌套頁面進行切換。

1
2
3
4
5
6
7
8

/docs/doc-1                           /docs/doc-2
+------------------+                  +-----------------+
| docs             |                  | docs            |
| +--------------+ |                  | +-------------+ |
| | doc-1        | |  +------------>  | | doc-2       | |
| |              | |                  | |             | |
| +--------------+ |                  | +-------------+ |
+------------------+                  +-----------------+

在 Vue 3 使用 Vue Router 實作上述巢狀路由時，即 docs 頁面要能顯示 doc-1，我們在路由配置可能就會寫 path: '/docs' 與 children，並在 children 加入 path: '/doc-1'，其中 docs 頁面包含 <router-view />，最終瀏覽路由路徑 /docs/doc-1 就可以看到嵌套頁面的效果。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

{
  path: "/docs",
  component: () => import("./pages/docs.vue")
  children: [
    {
      path: "doc-1",
      component: () => import("./pages/docs/doc-1.vue")
    }
  ]
}

而在 Nuxt 3 頁面的約定式路由機制下，我們即是透過目錄結構與頁面元件實做出嵌套路由的效果。

舉例來說，當我們建立了下面的目錄頁面結構：

這裡需要注意，一定要有 docs.vue 與 docs 同名的目錄

1
2
3
4
5

./pages/
├── docs/
│   ├── doc-1.vue
│   └── doc-2.vue
└── docs.vue

頁面元件的參考程式碼如下：

pages/docs.vue

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

<template>
  <div class="bg-white">
    <div class="my-6 flex flex-col items-center">
      <h1 class="text-3xl font-semibold text-gray-800">這裡是 Docs</h1>
      <div class="my-4 flex space-x-4">
        <NuxtLink to="/docs/doc-1">前往 Doc 1</NuxtLink>
        <NuxtLink to="/docs/doc-2">前往 Doc 2</NuxtLink>
      </div>
    </div>
    <div class="border-b-2 border-gray-100" />
    <div class="flex flex-col items-center">
      <NuxtPage />
    </div>
  </div>
</template>

pages/doc-1.vue

1
2
3
4
5

<template>
  <div class="flex flex-col items-center">
    <p class="my-8 text-3xl text-blue-500">這是我的第一份文件</p>
  </div>
</template>

pages/doc-2.vue

1
2
3
4
5

<template>
  <div class="flex flex-col items-center">
    <p class="my-8 text-3xl text-green-500">這是我的第二份文件</p>
  </div>
</template>

Nuxt 3 在自動生成路由時，實際上幫我們做出了類似這樣子的路由結構：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

{
  name: "docs",
  path: "/docs",
  component: "./pages/docs.vue",
  children: [
    {
      name: "docs-first-doc",
      path: "doc-1",
      component: "./pages/docs/doc-1.vue",
    }
  ]
}

一定要記得在 docs 頁面加上 <NuxtPage />，來作為顯示巢狀頁面的容器，接著分別瀏覽 /docs、/docs/doc-1 與 /docs/doc-2，可以發現在兩個頁面中上方的皆有顯示標題「這裡是 Docs」，該文字是由 docs.vue 元件提供的標題文字，而頁面下方則是 doc-1 與 doc-2 子頁面顯示的地方，以此就可以實現巢狀路由效果囉！

透過目錄檔案的結構與名稱及中括號 [] 我們就可以完成多數路由的情境，確實方便很多，也足以應付大部分實務上的需求，如果真的需要手動建立路由規則可以在參考官方文檔或等待釋出更好解決方案。

布局模板 (Layouts)

Nuxt 3 提供了一個布局模板 (Layouts) 的功能，可以讓你定義好布局模板後，在整個 Nuxt 中使用，舉例來說就很適合如上方有導覽列，下方是網頁主體內容的這種排版方式，將其構建成一個布局模板後，我們就可以重複使用這種布局方式。

布局模板通常放置在 ./layouts 目錄之下，也具有異步自動導入的效果，當新增好布局檔案後，我們就可以在 app.vue 中，添加 <NuxtLayout /> 元件來表示使用布局模板，也可以通過 name 設定不同的模板名稱。

建立一個預設的布局模板

布局模板在 Nuxt 3 中有約定一個名稱為 default.vue 作為預設的模板，如果在頁面元件中未特別指定要使用哪個模板或 <NuxtLayout /> 沒有設定 name 屬性，那麼都將會使用 default 作為預設的布局。

Step 1. 建立預設布局模板

新增 ./layouts/default.vue 檔案內容如下：

layouts/default.vue

1
2
3
4
5
6

<template>
  <div class="bg-sky-100 py-2">
    <p class="px-6 py-4 text-2xl text-gray-700">這是預設的布局，全部頁面都會使用到</p>
    <slot />
  </div>
</template>

在布局模板中，通常會包含一個 <slot /> 插槽，這個未命名的插槽 (slot) 即為預設插槽，這將會是採用這個布局模板的頁面元件，顯示的內容容器位置。

Step 2. 添加 元件

調整 app.vue 檔案，內容如下，我們添加 <NuxtLayout> 作為布局模板顯示的位置，name 屬性預設是 default，不過我們還是寫上 name="default" 避免誤會，這個 name 屬性值對應的即是布局模板的名稱。

下圖可以看見，我們在 app.vue 所寫的文字「這裡是最外層 app.vue」，會是在最外層，而緊接著的 <NuxtLayout name="default"></NuxtLayout>，就是布局頁面 default.vue。

布局模板中的插槽

如果你有注意到，default.vue 檔案內程式碼內，有一個插槽 <slot />，這裡就會是 <NuxtLayout> 內的元素所顯示的位置。

例如，我們在 app.vue 稍作調整：

app.vue

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

<template>
  <div class="m-4 bg-white">
    <p class="pb-4 text-2xl text-slate-600">這裡是最外層 app.vue</p>
    <NuxtLayout name="default">
      <p class="px-6 pt-4 text-xl text-slate-800">
        被 NuxtLayout 包裹的元件將會放置到 Layout 的 slot 中
      </p>
    </NuxtLayout>
  </div>
</template>

被 <NuxtLayout name="default"> 包裹的元素，就會在布局模板中的插槽 <slot /> 顯示。

在布局模板中建立多個插槽

當然，你也可以在布局模板中添加多個插槽，並給予名稱，這樣就可以將內容安排到特定的位置。

Step 1. 建立兩個具名的插槽 (Slot)，分別為 header 與 footer

如果插槽沒有給予 name 屬性，預設為 default。

layouts/default.vue

1
2
3
4
5
6
7
8

<template>
  <div class="bg-sky-100 py-2">
    <p class="px-6 py-4 text-2xl text-gray-700">這是預設的布局，全部頁面都會使用到</p>
    <slot name="header" />
    <slot />
    <slot name="footer" />
  </div>
</template>

Step 2. 將不同內容，顯示於指定的插槽位置。

app.vue

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

<template>
  <div class="m-4 bg-white">
    <p class="pb-4 text-2xl text-slate-600">這裡是最外層 app.vue</p>
    <NuxtLayout name="default">
      <template #header>
        <p class="px-6 pt-4 text-xl text-green-500">這段會放置在 header 插槽</p>
      </template>
      <template #default>
        <p class="px-6 pt-4 text-xl text-cyan-500">
          被 NuxtLayout 包裹的元件將會放置到 Layout 的預設 slot 中
        </p>
      </template>
      <template #footer>
        <p class="px-6 pt-4 text-xl text-blue-500">這段會放置在 footer 插槽</p>
      </template>
    </NuxtLayout>
  </div>
</template>

下圖可以看見，我們就可以依此來安排各個元件，於布局模板插槽的所在位置。

布局模板與路由頁面

當你熟悉了插槽配置，你也可以在其中添加 <NuxtPage /> 與建立 pages 下的頁面元件，以達到不同的路由頁面，使用相同的布局方式。

如果布局模板結合了路由頁面，整體網站就會如下的巢狀顯示方式，網站的入口點 app.vue 放置布局模板，模板內的內容則使用路由的 <NuxtPage />，最後各個路由的頁面就會在 <NuxtPage /> 容器中顯示。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

+---------------------------+
| app.vue                   |
| +-----------------------+ |
| | layout                | |
| | +-------------------+ | |
| | | page              | | |
| | |                   | | |
| | |                   | | |
| | +-------------------+ | |
| +-----------------------+ |
+---------------------------+

建立布局模板與路由頁面

Step 1. 調整 app.vue 入口點

將 app.vue 調整為以下內容：

app.vue

1
2
3
4
5
6
7
8

<template>
  <div class="m-4 bg-white">
    <p class="pb-4 text-2xl text-slate-600">這裡是最外層 app.vue</p>
    <NuxtLayout>
      <NuxtPage />
    </NuxtLayout>
  </div>
</template>

Step 2. 建立路由頁面

建立 ./pages/index.vue，內容如下：

pages/index.vue

1
2
3
4
5
6
7
8

<template>
  <div class="m-6 bg-slate-50 py-24">
    <div class="flex flex-col items-center">
      <h1 class="text-6xl font-semibold text-sky-400">2022 iThome</h1>
      <p class="mt-4 text-9xl font-bold text-gray-600">鐵人賽</p>
    </div>
  </div>
</template>

這樣我們就可以來讓路由頁面共用相同的布局模板。

多個路由頁面共用預設布局模板

承上，我們建立好預設的布局模板，讓它負責顯示路由的頁面。

Step 1. 新增路由頁面

新增 ./pages/about.vue，內容如下：

pages/about.vue

1
2
3
4
5
6
7
8

<template>
  <div class="mx-6 mb-4 bg-slate-50 py-24">
    <div class="flex flex-col items-center">
      <h1 class="text-6xl font-semibold text-yellow-400">大家好！我是 Ryan</h1>
      <p class="my-8 text-3xl text-gray-600">這裡是 /about</p>
    </div>
  </div>
</template>

新增 ./pages/contact.vue，內容如下：

pages/contact.vue

1
2
3
4
5
6
7
8

<template>
  <div class="mx-6 mb-4 bg-slate-50 py-24">
    <div class="flex flex-col items-center">
      <h1 class="text-6xl font-semibold text-rose-400">如果沒事不要找我 xDDD</h1>
      <p class="my-8 text-3xl text-gray-600">這裡是 /contact</p>
    </div>
  </div>
</template>

Step 2. 新增路由連結

調整 ./pages/index.vue，內容如下：

pages/index.vue

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

<template>
  <div class="mx-6 mb-4 bg-white py-24">
    <div class="flex flex-col items-center">
      <h1 class="text-6xl font-semibold text-gray-800">這裡是首頁</h1>
      <div class="my-4 flex space-x-4">
        <NuxtLink to="/about">前往 About</NuxtLink>
        <NuxtLink to="/contact">前往 Contact</NuxtLink>
      </div>
    </div>
  </div>
</template>

可以發現，現在首頁 /、/about 與 /contact 都套用上了預設布局。

建立多個布局模板

你也可以建立多個布局模板，再依據不同的情境，使用不同的布局模板。

Step 1. 建立新的布局模板

新增 ./layouts/custom.vue，內容如下：

layouts/custom.vue

1
2
3
4
5
6
7
8

<template>
  <div class="bg-rose-100 py-2">
    <p class="px-6 py-4 text-2xl text-gray-700">
      使用 <span class="font-bold text-rose-500">Custom</span> 布局
    </p>
    <slot />
  </div>
</template>

Step 2. 新增一個路由頁面

新增 ./pages/custom.vue，內容如下：

pages/custom.vue

1
2
3
4
5
6
7
8

<template>
  <div class="m-6 bg-slate-50 py-24">
    <div class="flex flex-col items-center">
      <h1 class="text-6xl font-semibold text-sky-400">2022 iThome</h1>
      <p class="mt-4 text-9xl font-bold text-gray-600">鐵人賽</p>
    </div>
  </div>
</template>

Step 3. 使用指定布局模板

在 ./pages/custom.vue 中的 script 使用 definePageMeta 方法：

1
2
3
4
5

<script setup>
definePageMeta({
  layout: 'custom'
})
</script>

definePageMeta 方法，提供我們可以設定特定的布局模板，layout 參數值所對應的名稱，即為 ./layouts 目錄下的布局模板。

注意，布局模板的命名被規範使用 Kebab Case 命名法，若檔案名稱為 customLayout.vue，它將會以 custom-layout 作為 name 屬性傳遞給

更進階的指定布局模板

我們能使用 layout: false 來禁止使用預設的布局模板，並在 template 添加 <NuxtLayout name="custom"> 來使用 custom 布局模板。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

<template>
  <NuxtLayout name="custom">
    <div class="mx-6 mb-4 bg-white py-24">
      <div class="flex flex-col items-center">
        <h1 class="text-6xl font-semibold text-sky-400">2022 iThome</h1>
        <p class="mt-4 text-9xl font-bold text-gray-600">鐵人賽</p>
      </div>
    </div>
  </NuxtLayout>
</template>

<script setup>
definePageMeta({
  layout: false
})
</script>

當布局模板可以在 template 中設定使用，我們就能結合插槽甚至動態的調整 name 屬性，做出更多樣靈活的布局效果。

上圖的參考程式碼：

layouts/custom.vue

1
2
3
4
5
6
7
8
9

<template>
  <div class="bg-rose-100 py-2">
    <p class="px-6 py-4 text-2xl text-gray-700">
      使用 <span class="font-bold text-rose-500">Custom</span> 布局
    </p>
    <slot />
    <slot name="footer" />
  </div>
</template>

pages/custom.vue

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

<template>
  <NuxtLayout name="custom">
    <template #default>
      <div class="mx-6 mb-4 bg-white py-24">
        <div class="flex flex-col items-center">
          <h1 class="text-6xl font-semibold text-sky-400">2022 iThome</h1>
          <p class="mt-4 text-9xl font-bold text-gray-600">鐵人賽</p>
        </div>
      </div>
    </template>
    <template #footer>
      <div class="flex flex-col items-center">
        <p class="mt-4 text-xl text-slate-600">感謝您閱讀 Nuxe 3 學習筆記～</p>
      </div>
    </template>
  </NuxtLayout>
</template>

<script setup>
definePageMeta({
  layout: false
})
</script>

當你使用 definePageMeta 方法，禁止使用預設的布局模板後，你也能使用 setPageLayout 方法來動態改變布局。

例如：

1
2
3
4
5

<script setup>
const = enableCustomLayout () => {
  setPageLayout('custom')
}
</script>

當你看過了這篇內容後，你會發現 Nuxt 3 所提供的布局模板非常的好用，布局模板規劃好後，爾後頁面所使用到的相同布局，只需要更改同一個布局模板，如果再結合元件化技巧，更是讓你的程式碼兼具重複使用性與維護性。

元件 (Components)

在建立 Vue 的網站開發過程中，我們可能會自己封裝元件 (Component) 讓程式碼可以被重複使用，也方便開發者維護，這些一個個的元件，可以透過全域註冊 (Global Registration) 讓整個 Vue 應用程式中都可以使用這個元件，也可以透過區域註冊 (Local Registration) 於特定的元件再載入使用。接下來我們將介紹 Nuxt 3 使用元件時應該遵循的規範及特色。

元件自動載入

在 Vue 中，雖然區域註冊使得元件間的依賴關係更加明確也對於 Tree shaking 更加友好，但我們在使用元件時，就得在需要的地方個別載入及註冊。而 Nuxt 3 提供在 components 目錄下專門放至這些元件，並具有自動載入及延遲載入等功能特色。

建立與使用元件

新增 ./components/IronManWelcome.vue，內容如下：

components/IronManWelcome.vue

1
2
3
4
5
6
7
8

<template>
  <div class="bg-white py-24">
    <div class="flex flex-col items-center">
      <h1 class="text-6xl font-semibold text-sky-400">2022 iThome</h1>
      <p class="mt-4 text-9xl font-bold text-gray-600">鐵人賽</p>
    </div>
  </div>
</template>

調整 ./app.vue，內容如下：

app.vue

1
2
3
4
5

<template>
  <div>
    <IronManWelcome />
  </div>
</template>

當我們建立了 ./components/IronManWelcome.vue 檔案後，Nuxt 會自動載入 ./components 目錄中的任何元件，在使用時的元件名稱也對應著檔案名稱，所以我們只需直接添加 <IronManWelcome /> 就可以直些使用這個元件。

元件名稱

Nuxt 所自動載入 ./components 目錄下的元件，在使用時的元件名稱也對應著檔案名稱，而當你在巢狀的目錄結構下的元件，元件的名稱將會基於目錄的路徑與檔案名稱，並刪除重複的字段。

舉例來說，如果 ./components 目錄結構如下：

1
2
3
4

components/
└── base/
    └── apply/
        └── Button.vue

./components/base/apply/Button.vue 元件的名稱就會是由目錄與檔案名稱組合出的 <BaseApplyButton>。

為了開發上能更清楚辨別，建議將檔案名稱設置與使用元件時的名稱相同，所以我們重新命名 ./components/base/apply/ 下的 Button.vue 為 BaseApplyButton.vue。

1
2
3
4

components/
└── base/
    └── apply/
        └── BaseApplyButton.vue

你也不用擔心元件名稱會不會變成 <BaseApplyBaseApplyButton> 看起來有點醜醜的，因為 Nuxt 會幫我們刪除重複的字段，所以在使用時元件名稱為 <BaseApplyButton>。

元件名稱的命名規則

Vue 在註冊元件時，可以使用大駝峰式命名法 (Pascal Case) 或烤肉串命名法 (Kebab Case) 來為元件命名，並在 template 也可以自由使用兩種命名方式作為使用元件的標籤。

例如，以 <base-apply-button> 來表示使用 ./components/base/apply/BaseApplyButton.vue 元件。

抑或建立 ./components/base/apply/base-apply-button.vue 元件，使用時以 <BaseApplyButton> 表示。

兩種方式 Nuxt 都支援，可以根據自己的習慣做選擇，而我個人是以大駝峰式命名法 (Pascal Case) 為主，以此區別為自己建立的元件。

動態元件 (Dynamic Components)

如果想要使用像 Vue 中的 <component :is="someComputedComponent"> 來動態的切換不同的元件，則需要使用 Vue 提供的 resolveComponentVue 方法來進行輔助。

例如：

1
2
3
4
5
6
7
8

<template>
  <component :is="show ? DynamicComponent : 'div'" />
</template>

<script setup>
const show = ref(false)
const DynamicComponent = resolveComponent('BaseApplyButton')
</script>

建立動態元件

Step 1. 建立元件

新增 ./components/base/apply/BaseApplyButton.vue，內容如下：

components/base/apply/BaseApplyButton.vue

1
2
3
4
5
6
7
8

<template>
  <button
    type="submit"
    class="mt-6 bg-blue-600 py-3 px-8 text-xl font-medium text-white hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2"
  >
    立即報名
  </button>
</template>

新增 ./components/round/apply/RoundApplyButton.vue，內容如下：

components/round/apply/RoundApplyButton.vue

1
2
3
4
5
6
7
8

<template>
  <button
    type="submit"
    class="mt-6 rounded-full bg-blue-600 py-3 px-8 text-xl font-medium text-white hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2"
  >
    立即報名
  </button>
</template>

Step 2. 使用 resolveComponent()

調整 ./app.vue，內容如下：

app.vue

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

<template>
  <div class="flex flex-col items-center">
    <div class="mt-8 flex items-center">
      <input
        id="show-button"
        v-model="useRound"
        name="show-button"
        type="checkbox"
        class="h-5 w-5"
      />
      <label for="show-button" class="ml-2 block text-base text-slate-800">使用圓角按鈕</label>
    </div>
    <component :is="useRound ? RoundButton : BaseButton" />
  </div>
</template>

<script setup>
const useRound = ref(false)
const BaseButton = resolveComponent('BaseApplyButton')
const RoundButton = resolveComponent('RoundApplyButton')
</script>

呈現效果：

動態載入 (Dynamic Imports)

動態載入 (Dynamic Imports) 元件也稱之為延遲載入 (lazy-loading)，如果頁面中不需要立刻使用或顯示某個元件，透過動態載入的方式可以延遲元件載入的時間點，有助於優化 JavaScript 首次載入時的檔案大小。

使用的方式也非常簡單，只需要在使用元件時，加上前綴 Lazy 就可以有延遲載入的效果。

建立一個動態載入的按鈕

Step 1. 建立按鈕元件

新增 ./components/base/apply/BaseApplyButton.vue，內容如下：

components/base/apply/BaseApplyButton.vue

1
2
3
4
5
6
7
8

<template>
  <button
    type="submit"
    class="mt-6 rounded-sm bg-blue-600 py-3 px-8 text-xl font-medium text-white hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2"
  >
    立即報名
  </button>
</template>

Step 2. 添加 Lazy 前綴

調整 ./app.vue，內容如下：

app.vue

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

<template>
  <div class="flex flex-col items-center">
    <div class="mt-8 flex items-center">
      <input id="show-button" v-model="show" name="show-button" type="checkbox" class="h-5 w-5" />
      <label for="show-button" class="ml-2 block text-base text-slate-800">顯示報名按鈕</label>
    </div>
    <LazyBaseApplyButton v-if="show" />
  </div>
</template>

<script setup>
const show = ref(false)
</script>

看看延遲載入的效果：

在頁面上有一個核取方塊，使用者勾選時才顯示按鈕，我們透過瀏覽器的開發者工具觀察網路 (Network) 的使用情況，可以發現只有首次勾選後才請求了 BaseApplyButton.vue 按鈕元件 JS。當這個按鈕元件被設置為 Lazy 動態載入時，頁面首次載入其實不會包含這個按鈕的程式碼，而是等待需要這個元件時才去請求下載，以此達到延遲載入的效果，同時也降低首次進入網頁時需要下載的 JavaScript 程式碼大小。

控制伺服器端或客戶端渲染元件

<ClientOnly> 元件

Nuxt 3 提供了一個 <ClientOnly> 元件，可以控制被包裹的元件僅在客戶端進行渲染。

例如，我們建立 ./components/IronManWelcome.vue 檔案，內容如下：

components/IronManWelcome.vue

1
2
3
4
5
6
7
8

<template>
  <div class="bg-white py-24">
    <div class="flex flex-col items-center">
      <h1 class="text-6xl font-semibold text-sky-400">2022 iThome</h1>
      <p class="mt-4 text-9xl font-bold text-gray-600">鐵人賽</p>
    </div>
  </div>
</template>

使用 <ClientOnly> 元件包裹 <IronManWelcome>。

調整 ./app.vue 中，內容如下：

app.vue

1
2
3
4
5
6
7

<template>
  <div>
    <ClientOnly>
      <IronManWelcome />
    </ClientOnly>
  </div>
</template>

這樣就可以將 <IronManWelcome> 元件設定為僅在客戶端進行渲染，首次請求頁面時將不會包含這個元件的 HTML。

<ClientOnly> 元件中提供了一個名為 fallback 的插槽 (Slot)，可以用作於在伺服器渲染的預設內容，等到客戶端載入完成才接手渲染被包裹的 <IronManWelcome> 元件。

調整 ./app.vue 中，內容如下：

app.vue