Typescript on Wayne's blog | 偉恩的部落格 | 技術博客

【Typescript】5.0 版本發布

Tue, 18 Apr 2023 00:00:00 +0000

此版本帶來了許多新功能，同時旨在使 TypeScript 更小、更簡單、更快。我們已經實施了新的裝飾器標準，添加了更好地支持 Node 和 bundlers 中的 ESM 項目的功能，為庫作者提供了控制泛型推理的新方法，擴展了我們的 JSDoc 功能，簡化了配置，並進行了許多其他改進。

如果您已經熟悉 TypeScript，也不用擔心！5.0 不是破壞性版本，你所知道的一切仍然適用。雖然 TypeScript 5.0 包括正確性更改和一些不常用選項的棄用，但我們相信大多數開發人員都會有與以前版本類似的升級體驗。

要開始使用 TypeScript 5.0，您可以通過 NuGet 獲取它，或者使用 npm 和下面的命令：

1

npm install -D typescript

你也可以按照指示在 Visual Studio Code 中使用新版本的 TypeScript 的說明進行操作。

以下 TypeScript 5.0 中新功能的快速列表！

裝飾器
const 泛型參數
extends 支持多個配置文件
所有的枚舉都是聯合枚舉
--moduleResolution 配置新增 bundler 支持
自定義解析標誌
--verbatimModuleSyntax
支持 export type *
JSDoc 支持 @satisfies
JSDoc 支持 @overload
運行 tsc --build 可以傳入的新指令
編輯器中不區分大小寫的導入排序
switch/case 語法補足
速度、內存和包大小優化
重大更改和棄用
下一步是什麼？

自 Beta 和 RC 以來有什麼新功能？

自 beta 版發布以來，TypeScript 5.0 有幾個顯著的變化。

自 TypeScript 5.0 Beta 以來，一個新區別是 TypeScript 允許將裝飾器放置在 export 和 export default 之前或之後。這一變化反映了 TC39（ECMAScript/JavaScript 的標準機構）內部的討論和共識。

另一個是新的 bundler 模塊解析選項只能在 --module 選項設置為 esnext 時使用。這樣做是為了確保在輸入文件中寫入的 import 語句不會在捆綁器解析它們之前轉換為 require 調用，無論捆綁器或加載器是否遵從 TypeScript 的 module 選項。我們還在這些發布說明中提供了一些上下文，建議大多數庫作者堅持使用 node16 or nodenext。

雖然 TypeScript 5.0 Beta 附帶了此功能，但我們沒有記錄我們在編輯器場景中支持不區分大小寫的導入排序的工作。這部分是因為用於自定義的 UX 仍在討論中，但默認情況下，TypeScript 現在應該可以更好地與您的其他工具一起使用。

自我們的 RC 以來，我們最顯著的變化是 TypeScript 5.0 現在在 package.json 中指定了 Node.js 的最低版本為 12.20。我們還發布了一篇關於 TypeScript 5.0 向 modules 遷移的文章，並提供了鏈接。

自 TypeScript 5.0 Beta 和 RC 發布以來，速度基準和包大小增量的具體數字也進行了調整，儘管噪音一直是運行過程中的一個因素。為了清晰起見，還對一些基準的名稱進行了調整，包大小的改進也被移至單獨的圖表中。

裝飾器

裝飾器是即將推出的 ECMAScript 功能，它允許我們以可重用的方式自定義類及其成員。

讓我們思考以下代碼：

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


class Person {
 name: string;
 constructor(name: string) {
 this.name = name;
 }
 ​
 greet() {
 console.log(`Hello, my name is ${this.name}.`);
 }
}

const p = new Person("Ron");
p.greet();

greet 這裡很簡單，但讓我們想像它更複雜——也許它執行一些異步邏輯，它是遞歸的，它有副作用…等等。不管你想像的是哪種場景，假設你拋出了一些 console.log 調用來幫助調試 greet。

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


class Person {
 name: string;
 constructor(name: string) {
 this.name = name;
 }

 greet() {
 console.log("LOG: Entering method.");
 console.log(`Hello, my name is ${this.name}.`);
 console.log("LOG: Exiting method.")
 }
}

這種模式相當普遍。如果有一種方法我們可以為每種方法做到這一點，那就太好了！

這就是裝飾器的用武之地。我們可以編寫一個 loggedMethod 的函數，如下所示：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


function loggedMethod(originalMethod: any, _context: any) {

 function replacementMethod(this: any, ...args: any[]) {
 console.log("LOG: Entering method.")
 const result = originalMethod.call(this, ...args);
 console.log("LOG: Exiting method.")
 return result;
 }

 return replacementMethod;
}

輸出 “Entering…”
this 將其所有參數傳遞給原始方法
輸出 “Exiting…” 日誌
返回原始方法返回的任何內容

現在我們可以使用 loggedMethod 來裝飾方法 greet：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


class Person {
 name: string;
 constructor(name: string) {
 this.name = name;
 }

 @loggedMethod
 greet() {
 console.log(`Hello, my name is ${this.name}.`);
 }
}

1
2
3
4
5


// Output:
//
// LOG: Entering method.
// Hello, my name is Ron.
// LOG: Exiting method.

我們只是在 greet 上面使用了 loggedMethod 作為裝飾器，注意我們把它寫成了 @loggedMethod。當我們這樣做時，它會被 target 方法和 context 對象調用。因為 loggedMethod 返回了一個新函數，該函數替換了 greet。

我們還沒有提到 loggedMethod 用第二個參數定義的。它被稱為 “上下文對象"，它有一些關於如何聲明修飾方法的有用信息，比如它是 #private 成員還是靜態成員，或者方法的名稱是什麼。讓我們重寫 loggedMethod 以利用它並打印出被裝飾的方法的名稱。

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


function loggedMethod(originalMethod: any, context: ClassMethodDecoratorContext) {
 const methodName = String(context.name);

 function replacementMethod(this: any, ...args: any[]) {
 console.log(`LOG: Entering method '${methodName}'.`)
 const result = originalMethod.call(this, ...args);
 console.log(`LOG: Exiting method '${methodName}'.`)
 return result;
 }

 return replacementMethod;
}

我們現在使用 context 參數，它是 loggedMethod 中第一個具有比 any 和 any[] 更嚴格的參數類型。

TypeScript 提供了一個名為 ClassMethodDecoratorContext 的類型，他對方法裝飾器所接收的上下文對象進行建模。

除了元數據之外，方法的上下文對象還有一個有用的函數，稱為 addInitializer。這是一種掛鉤到構造函數開頭的方法（如果我們使用 static，則掛鉤到類本身的初始化）。

例如：在 JavaScript 中，通常會編寫類似以下模式的內容：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


class Person {
 name: string;
 constructor(name: string) {
 this.name = name;
 this.greet = this.greet.bind(this);
 }

 greet() {
 console.log(`Hello, my name is ${this.name}.`);
 }
}

或者，greet 可以聲明為初始化為箭頭函數的屬性。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


class Person {
 name: string;
 constructor(name: string) {
 this.name = name;
 this.greet = this.greet.bind(this);
 }

 greet = () => {
 console.log(`Hello, my name is ${this.name}.`);
 }
}

編寫此代碼是為了確保在 greet 作為獨立函數調用或作為回調傳遞 this 時不會重新綁定。

1
2
3
4


const greet = new Person("Ron").greet;

// We don't want this to fail!
greet();

我們可以編寫一個裝飾器，使用 addInitializer 在構造函數中調用 bind。

1
2
3
4
5
6
7
8
9


function bound(originalMethod: any, context: ClassMethodDecoratorContext) {
 const methodName = context.name;
 if (context.private) {
 throw new Error(`'bound' cannot decorate private properties like ${methodName as string}.`);
 }
 context.addInitializer(function () {
 this[methodName] = this[methodName].bind(this);
 });
}

bound 不返回任何東西——所以當它裝飾一個方法時，它會保留原來的方法。相反，它將在任何其他字段初始化之前添加邏輯。

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


class Person {
 name: string;
 constructor(name: string) {
 this.name = name;
 }

 @bound
 @loggedMethod
 greet() {
 console.log(`Hello, my name is ${this.name}.`);
 }
}

const p = new Person("Ron");
const greet = p.greet;

// Works!
greet();

請注意，我們堆疊了兩個裝飾器：@bound 和 @loggedMethod。這些裝飾以**相反的順序**運行。即 @loggedMethod 裝飾原始方法 greet，@bound 裝飾 @loggedMethod 的結果。在此示例中，這並不重要，但如果您的裝飾器有副作用或期望特定順序，則可能會發生這種情況。

同樣值得注意的是：根據你喜歡代碼風格，可以將這些裝飾器放在同一行。

1
2
3


@bound @loggedMethod greet() {
 console.log(`Hello, my name is ${this.name}.`);
}

可能不太明顯的是，我們甚至可以創建返回裝飾器函數的函數。這使得定制最終的裝飾器成為可能。如果我們願意，我們可以讓 loggedMethod 返回一個裝飾器並自定義它記錄消息的方式。

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


function loggedMethod(headMessage = "LOG:") {
 return function actualDecorator(originalMethod: any, context: ClassMethodDecoratorContext) {
 const methodName = String(context.name);

 function replacementMethod(this: any, ...args: any[]) {
 console.log(`${headMessage} Entering method '${methodName}'.`)
 const result = originalMethod.call(this, ...args);
 console.log(`${headMessage} Exiting method '${methodName}'.`)
 return result;
 }

 return replacementMethod;
 }
}

如果我們這樣做，我們必須在使用 loggedMethod 作為裝飾器之前調用它。然後我們可以傳入任何字符串作為輸出到控制台的日誌的前綴。

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


class Person {
 name: string;
 constructor(name: string) {
 this.name = name;
 }

 @loggedMethod("")
 greet() {
 console.log(`Hello, my name is ${this.name}.`);
 }
}

const p = new Person("Ron");
p.greet();

// Output:
//
// Entering method 'greet'.
// Hello, my name is Ron.
// Exiting method 'greet'.

裝飾器不僅僅可以用在方法上！它們可用於屬性/字段、getter、setter 和自動訪問器。甚至類本身也可以為子類化和註冊之類的事情進行裝飾。

要深入了解有關裝飾器的更多信息，您可以閱讀 Axel Rauschmayer 的詳盡摘要。

有關涉及的更改的更多信息，您可以查看原始 pull request。

與實驗性遺留裝飾器的差異

如果您已經使用 TypeScript 一段時間，您可能會意識到它多年來一直支持”實驗性“裝飾器。雖然這些實驗性裝飾器非常有用，但它們模擬了一個更舊版本的裝飾器提案，並且始終需要一個名為 --experimentalDecorators。任何在沒有此標誌的情況下嘗試在 TypeScript 中使用裝飾器都會提示錯誤消息。

--experimentalDecorators 在可預見的未來將繼續存在；然而，如果沒有這個標誌，裝飾器現在將成為所有新代碼的有效語法。在之外 --experimentalDecorators，它們將以不同方式進行類型檢查和釋放。類型檢查規則和emit 完全不同，雖然可以編寫裝飾器來支持舊的和新的裝飾器行為，但任何現有的裝飾器函數都不太可能這樣做。

這個新的裝飾器提案與 --emitDecoratorMetadata 不兼容，它不允許裝飾參數。未來的 ECMAScript 提案可能會幫助彌合這一差距。

最後一點：除了允許將裝飾器放在 export 關鍵字之前，裝飾器提案現在還提供了在 export 或 export default 之後放置裝飾器的選項。唯一的例外是不允許混合使用這兩種樣式。

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


// allowed
@register export default class Foo {
 // ...
}

// also allowed
export default @register class Bar {
 // ...
}

// error - before *and* after is not allowed
@before export @after class Bar {
 // ...
}

編寫類型良好的裝飾器

上面的 loggedMethod 和 bound 裝飾器示例有意簡單化並省略了很多關於類型的細節。

鍵入裝飾器可能相當複雜。例如，上面的類型正確的版本 loggedMethod 可能看起來像這樣：

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


function loggedMethod<This, Args extends any[], Return>(
 target: (this: This, ...args: Args) => Return,
 context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>
) {
 const methodName = String(context.name);

 function replacementMethod(this: This, ...args: Args): Return {
 console.log(`LOG: Entering method '${methodName}'.`)
 const result = target.call(this, ...args);
 console.log(`LOG: Exiting method '${methodName}'.`)
 return result;
 }

 return replacementMethod;
}

我們必須使用類型參數 This、Args 和 Return 分別定義 this 的類型、參數和原始方法的返回類型。

裝飾器函數定義的具體複雜程度取決於您要保證的內容。請記住，您的裝飾器將被使用的次數多於它們被編寫的次數，因此類型良好的版本通常更可取——但顯然需要與可讀性進行權衡，因此請盡量保持簡單。

將來會提供更多關於編寫裝飾器的文檔，但這篇文章應該有大量關於裝飾器機制的細節。

const 泛型參數

在推斷對象的類型時，TypeScript 通常會選擇一種通用的類型。例如，在本例中，names 的推斷類型是 string[]：

1
2
3
4
5
6
7


type HasNames = { readonly names: string[] };
function getNamesExactly<T extends HasNames>(arg: T): T["names"] {
 return arg.names;
}

// Inferred type: string[]
const names = getNamesExactly({ names: ["Alice", "Bob", "Eve"]});

通常這樣做的目的是使突變成為可能。

但是，根據 getNamesExactly 的具體功能和用途，通常需要更具體的類型。

到目前為止，API 作者通常不得不在某些地方添加 as const 以實現所需的推理：

1
2
3
4
5
6
7
8
9


// The type we wanted:
// readonly ["Alice", "Bob", "Eve"]
// The type we got:
// string[]
const names1 = getNamesExactly({ names: ["Alice", "Bob", "Eve"]});

// Correctly gets what we wanted:
// readonly ["Alice", "Bob", "Eve"]
const names2 = getNamesExactly({ names: ["Alice", "Bob", "Eve"]} as const);

這可能很麻煩且容易忘記。在 TypeScript 5.0 中，您現在可以將 const 修飾符添加到類型參數聲明中，以使 const-like 推理成為默認值：

1
2
3
4
5
6
7
8
9


type HasNames = { names: readonly string[] };
function getNamesExactly<const T extends HasNames>(arg: T): T["names"] {
// ^^^^^
 return arg.names;
}

// Inferred type: readonly ["Alice", "Bob", "Eve"]
// Note: Didn't need to write 'as const' here
const names = getNamesExactly({ names: ["Alice", "Bob", "Eve"] });

請注意，const 修飾符不拒絕可變值，也不需要不可變約束。使用可變類型約束可能會產生令人驚訝的結果。例如：

1
2
3
4


declare function fnBad<const T extends string[]>(args: T): void;

// 'T' is still 'string[]' since 'readonly ["a", "b", "c"]' is not assignable to 'string[]'
fnBad(["a", "b" ,"c"]);

在這裡，推斷的候選項 T 是 readonly ["a", "b", "c"]，並且 readonly 不能在需要可變數組的地方使用數組。在這種情況下，推理回退到約束條件，數組被視為 string[]，並且調用仍然成功進行。

此函數的更好定義應該使用 readonly string[]：

1
2
3
4


declare function fnGood<const T extends readonly string[]>(args: T): void;

// T is readonly ["a", "b", "c"]
fnGood(["a", "b" ,"c"]);

同樣，請記住修飾符 const 僅影響在調用中編寫的對象、數組和原始表達式的推斷，因此不會（或不能）修改的參數不會看到 as const 任何行為變化：

1
2
3
4
5


declare function fnGood<const T extends readonly string[]>(args: T): void;
const arr = ["a", "b" ,"c"];

// 'T' is still 'string[]'-- the 'const' modifier has no effect here
fnGood(arr);

有關更多詳細信息，請參閱拉取請求和（第一個和第二個）激勵問題。

extends 支持多個配置文件

tsconfig.json 管理多個項目時，擁有一個其他文件可以擴展的"基本"配置文件會很有幫助。這就是為什麼 TypeScript 支持 extends 在 compilerOptions。

1
2
3
4
5
6
7
8


// packages/front-end/src/tsconfig.json
{
 "extends": "../../../tsconfig.base.json",
 "compilerOptions": {
 "outDir": "../lib",
 // ...
 }
}

但是，在某些情況下，您可能希望從多個配置文件進行擴展。例如：假設使用發送到 npm 的 TypeScript 基本配置文件。如果您希望所有項目也使用 npm 包中的選項 @tsconfig/strictest，那麼有一個簡單的解決方案：擴展 tsconfig.base.json 自 @tsconfig/strictest：

1
2
3
4
5
6
7


// tsconfig.base.json
{
 "extends": "@tsconfig/strictest/tsconfig.json",
 "compilerOptions": {
 // ...
 }
}

這在一定程度上起作用。如果您有任何項目不想使用 @tsconfig/strictest，他們必須手動禁用這些選項，或者創建一個短度的 tsconfig.base.json 版本，該版本不擴展 @tsconfig/strictest。

為了在此處提供更多靈活性，Typescript 5.0 現在允許該 extends 字段採用多個條目。例如，在這個配置文件中：

1
2
3
4
5
6


{
 "extends": ["a", "b", "c"],
 "compilerOptions": {
 // ...
 }
}

寫這個有點像 c 直接擴展，其中 c extends b 和 b extends a。如果任何字段"衝突”，則後一個條目獲勝。

所以在下面的例子中，和 strictNullChecks 都 noImplicitAny 在最終的 tsconfig.json。

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


// tsconfig1.json
{
 "compilerOptions": {
 "strictNullChecks": true
 }
}

// tsconfig2.json
{
 "compilerOptions": {
 "noImplicitAny": true
 }
}

// tsconfig.json
{
 "extends": ["./tsconfig1.json", "./tsconfig2.json"],
 "files": ["./index.ts"]
}

再舉一個例子，我們可以用下面的方式重寫我們原來的例子。

1
2
3
4
5
6
7
8


// packages/front-end/src/tsconfig.json
{
 "extends": ["@tsconfig/strictest/tsconfig.json", "../../../tsconfig.base.json"],
 "compilerOptions": {
 "outDir": "../lib",
 // ...
 }
}

有關更多詳細信息，請閱讀有關原始拉取請求的更多信息。

所有枚舉都是聯合枚舉

當 TypeScript 最初引入枚舉時，它們只不過是一組具有相同類型的數字常量。

1
2
3
4


enum E {
 Foo = 10,
 Bar = 20,
}

E.Foo 和 E.Bar 的唯一特別之處在於它們可以賦值給除 E 類型之外的任何類型。除此之外，他們幾乎只是 numbers。

1
2
3
4


function takeValue(e: E) {}

takeValue(E.Foo); // works
takeValue(123); // error!

直到 TypeScript 2.0 引入了枚舉文字類型，枚舉才變得更加特殊。枚舉文字類型為每個枚舉成員提供了自己的類型，並將枚舉本身變成了每個成員類型的聯合。它們還允許我們僅引用枚舉類型的一個子集，並縮小這些類型的範圍。

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


// Color is like a union of Red | Orange | Yellow | Green | Blue | Violet
enum Color {
 Red, Orange, Yellow, Green, Blue, /* Indigo */, Violet
}

// Each enum member has its own type that we can refer to!
type PrimaryColor = Color.Red | Color.Green | Color.Blue;

function isPrimaryColor(c: Color): c is PrimaryColor {
 // Narrowing literal types can catch bugs.
 // TypeScript will error here because
 // we'll end up comparing 'Color.Red' to 'Color.Green'.
 // We meant to use ||, but accidentally wrote &&.
 return c === Color.Red && c === Color.Green && c === Color.Blue;
}

為每個枚舉成員賦予其自己的類型的一個問題是，這些類型在某些部分與成員的實際值相關聯。在某些情況下，無法計算該值——例如，枚舉成員可以通過函數調用進行初始化。

1
2
3


enum E {
 Blah = Math.random()
}

每當 TypeScript 遇到這些問題時，它都會悄悄退出並使用舊的枚舉策略。這意味著放棄聯合和文字類型的所有優勢。

TypeScript 5.0 通過為每個計算成員創建唯一類型，設法將所有枚舉變成聯合枚舉。這意味著現在可以縮小所有枚舉的範圍，並將其成員也作為類型引用。

有關此更改的更多詳細信息，您可以閱讀GitHub 上的詳細信息。

`--moduleResolution` 新增 bundler 支持

TypeScript 4.7 在 --module 和 --moduleResolution 設置中引入了 node16 和 nodenext 選項。這些選項的目的是更好地模擬 Node.js 中 ECMAScript 模塊的精確查找規則；然而這種模式有很多限制，其他工具並沒有真正強制執行。

例如，在 Node.js 的 ECMAScript 模塊中，任何相對導入都需要包含文件副檔名。

1
2
3
4


// entry.mjs
import * as utils from "./utils"; // wrong - we need to include the file extension.

import * as utils from "./utils.mjs"; // works

在 Node.js 和瀏覽器中這樣做有一定的原因，它使文件查找更快，並且更適合原始文件服務器。但是對於許多使用捆綁器等工具的開發人員來說，node16/nodenext 設置很麻煩，因為捆綁器沒有這些限制中的大部分。在某些方面，node 解析模式對任何使用捆綁器的人來說都更好。

但在某些方面，原有的 node 解決模式已經落伍了。大多數現代捆綁器在 Node.js 中使用 ECMAScript 模塊和 CommonJS 查找規則的融合。例如：無擴展名的導入就像在 CommonJS 中一樣工作得很好，但是在查看包的 export 條件時，他們會更喜歡 ECMAScript 文件中的 import 條件。

為了模擬打包器的工作方式，TypeScript 現在引入了一種新策略：--moduleResolution bundler。

1
2
3
4
5
6


{
 "compilerOptions": {
 "target": "esnext",
 "moduleResolution": "bundler"
 }
}

如果您正在使用像 Vite、esbuild、swc、Webpack、Parcel 和其他實施混合查找策略的現代捆綁器，那麼新選項 bundler 應該非常適合您。

另一方面，如果您正在編寫一個打算在 npm 上發布的庫，則使用該 bundler 選項可以隱藏兼容性問題，這些問題可能會出現在您不使用捆綁器的用戶身上。因此，在這些情況下，使用 node16 或 nodenext 解決方案可能是更好的途徑。

要了解更多信息 --moduleResolution bundler，請查看拉取請求。

自定義解析標誌

JavaScript 工具現在可以模擬"混合"解析規則，就像 bundler 我們上面描述的模式一樣。由於工具的支持可能略有不同，TypeScript 5.0 提供了啟用或禁用一些功能的方法，這些功能可能適用於您的配置，也可能不適用於您的配置。

allowImportingTsExtensions

--allowImportingTsExtensions 允許使用特定於 TypeScript 的擴展名（如 .ts、.mts或 .tsx）。

此標誌僅在 --noEmit 或 --emitDeclarationOnly 啟用時才被允許，因為這些導入路徑在運行時無法在 JavaScript 輸出文件中解析。這裡的期望是您的解析器（例如您的捆綁器、運行時或其他一些工具）將使這些 .ts 文件之間的導入工作。

resolvePackageJsonExports

--resolvePackageJsonExports 強制 TypeScript 解析 package.json 的 exports 字段，如果曾經從 node_modules 中的讀取過 json 文件。

當配置項 --modulerresolve 為 node16、nodenext 和 bundler 時，該選項默認為 true。

resolvePackageJsonImports

--resolvePackageJsonImports 強制 TypeScript 在從其祖先目錄包含 package.json 的文件執行以 # 開頭的查找時查詢 package.json 文件的導入字段。

當配置項 --modulerresolve 為 node16、nodenext 和 bundler 時，該選項默認為 true。

allowArbitraryExtensions

在 TypeScript 5.0 中，當導入路徑不是已知 JavaScript 或 TypeScript 文件擴展名的擴展名結尾時，編譯器將以 {file basename}.d.{extension}.ts。例如，如果您在捆綁項目中使用 CSS 加載器，您可能希望為這些樣式表編寫（或生成）聲明文件：

app.css

1
2
3


.cookie-banner {
 display: none;
}

app.d.css.ts

1
2
3
4


declare const css: {
 cookieBanner: string;
};
export default css;

App.tsx

1
2
3


import styles from "./app.css";

styles.cookieBanner; // string

默認情況下，此導入會引發錯誤，讓您知道 TypeScript 不理解此文件類型，並且您的運行時可能不支持導入它。但是如果您已配置運行時或捆綁程序來處理它，則可以使用新的 --allowArbitraryExtensions 編譯器選項來抑制錯誤。

請注意，從歷史上看，通過添加名為 app.css.d.ts 的聲明文件而不是 app.d.css.ts，通常可以達到類似的效果——然而，這只是通過 Node 對 CommonJS 的 require 解析規則起作用。嚴格來說，前者被解釋為一個名為 app.css.js 的 JavaScript 文件的聲明文件。因為相對文件導入需要在 Node 的 ESM 支持中包含擴展名，所以 TypeScript 會在我們的示例中 --moduleResolution node16 或在 nodenext 下的ESM 文件中出錯。

有關更多信息，請閱讀此功能的提案及其相應的拉取請求。

customConditions

--customConditions 接收一個附加條件列表，當 TypeScript 從 package.json 的 exports 或 imports 字段解析時，這些條件將添加到解析器默認使用的任何現有條件中。

例如：當在 tsconfig.json 中設置此字段時：

1
2
3
4
5
6
7


{
 "compilerOptions": {
 "target": "es2022",
 "moduleResolution": "bundler",
 "customConditions": ["my-condition"]
 }
}

任何時候在 package.json 中引用 exports 或 imports 字段時，TypeScript 都會考慮調用 my-condition 的條件。

因此，當從具有以下內容的包中導入時 package.json：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


{
 // ...
 "exports": {
 ".": {
 "my-condition": "./foo.mjs",
 "node": "./bar.mjs",
 "import": "./baz.mjs",
 "require": "./biz.mjs"
 }
 }
}

TypeScript 將嘗試查找與 foo.mjs 對應的文件。

該字段僅在 --moduleResolution 的 node16、nodenext 和 bundler 選項下有效。

`--verbatimModuleSyntax`

默認情況下，TypeScript 會做一些叫做 import elision 的事情。基本上，如果你寫類似：

1
2
3
4
5


import { Car } from "./car";

export function drive(car: Car) {
 // ...
}

TypeScript 檢測到您只對類型使用導入，所以輸出結果會將此導入代碼刪除。您的輸出 JavaScript 可能看起來像這樣：

1
2
3


export function drive(car) {
 // ...
}

大多數時候這很好，因為如果 Car 不是從 ./car 導出的值，我們將收到運行時錯誤。

但它確實為某些邊緣情況增加了一層複雜性。例如：請注意沒有像這樣的語句 import "./car";，導入被完全刪除。這實際上對有無副作用的模塊產生影響。

TypeScript 針對 JavaScript 的 emit 策略還有另外幾層複雜性，導入省略並不總是由導入的使用方式驅動，它通常還會參考值的聲明方式。所以並不總是很清楚是否像下面這樣的代碼：

1

export { Car } from "./car";

應該保留或丟棄。如果 Car 用 class 之類的東西聲明，那麼它可以保存在生成的 JavaScript 文件中。但如果 Car 僅聲明為 type 別名或 interface，則 JavaScript 文件 Car 根本不應導出。

雖然 TypeScript 可能能夠根據來自跨文件的信息做出這些發出決定，但並非每個編譯器都可以。

imports 和 exports 的修飾符 type 對這些情況有點幫助。我們可以明確指出導入或導出是否僅用於類型分析，並且可以通過使用修飾符將其完全刪除到 JavaScript 文件中 type。

1
2
3
4
5
6


// This statement can be dropped entirely in JS output
import type * as car from "./car";

// The named import/export 'Car' can be dropped in JS output
import { type Car } from "./car";
export { type Car } from "./car";

type 修飾符本身並不是很有用，默認情況下，模塊省略仍然會刪除導入，並且沒有什麼強制您區分 type 普通導入和導出。所以 TypeScript 有標誌 --importsNotUsedAsValues 來確保你使用 type 修飾符，--preserveValueImports 以防止某些模塊省略行為，並 --isolatedModules 確保你的 TypeScript 代碼適用於不同的編譯器。不幸的是，很難理解這 3 個標誌的細節，並且仍然存在一些具有意外行為的邊緣情況。

--verbatimModuleSyntax TypeScript 5.0 引入了一個名為簡化情況的新選項。規則要簡單得多：任何沒有 type 修飾符的導入或導出都會被保留。任何使用 type 修飾符的東西都會被完全丟棄。

1
2
3
4
5
6
7
8


// Erased away entirely.
import type { A } from "a";

// Rewritten to 'import { b } from "bcd";'
import { b, type c, type d } from "bcd";

// Rewritten to 'import {} from "xyz";'
import { type xyz } from "xyz";

有了這個新選項，所見即所得。

不過當涉及到模塊互操作時，這確實有一些影響。在此標誌下，當您的設置或文件擴展名暗示不同的模塊系統時，ECMAScript imports 和 exports 不會被重寫為 require 調用。相反，你會得到一個錯誤。如果您需要發出使用 require 和 module.exports 的代碼，則必須使用早於 ES2015 的 TypeScript 模塊語法：

輸入 TypeScript	輸出 JavaScript
import foo = require(“foo”);	const foo = require(“foo”);
function foo() {} function bar() {} function baz() {} export = { foo, bar, baz };	function foo() {} function bar() {} function baz() {} module.exports = { foo, bar, baz };

雖然這是一個限制，但它確實有助於使一些問題更加明顯。例如，忘記在 package.json 中設置 type 字段是很常見的。--module node16。因此，開發人員會在沒有意識到的情況下開始編寫 CommonJS 模塊而不是 ES 模塊，從而提供令人驚訝的查找規則和 JavaScript 輸出。這個新標誌確保您有意使用您正在使用的文件類型，因為語法是有意不同的。

因為 --verbatimModuleSyntax 提供了比 --importsNotUsedAsValues 和 --preserveValueImports 更一致的故事，所以這兩個現有的標誌已被棄用。

有關更多詳細信息，請閱讀原始拉取請求及其提案問題。

支持 `export type *`

當 TypeScript 3.8 引入純類型導入時，新語法不允許用於 export * from "module" 或 export * as ns from "module" 重新導出。TypeScript 5.0 添加了對這兩種形式的支持：

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


// models/vehicles.ts
export class Spaceship {
 // ...
}

// models/index.ts
export type * as vehicles from "./vehicles";

// main.ts
import { vehicles } from "./models";

function takeASpaceship(s: vehicles.Spaceship) {
 // ok - `vehicles` only used in a type position
}

function makeASpaceship() {
 return new vehicles.Spaceship();
 // ^^^^^^^^
 // 'vehicles' cannot be used as a value because it was exported using 'export type'.
}

您可以在此處閱讀有關實施的更多信息。

JSDoc 支持 `@satisfies`

TypeScript 4.9 引入了 satisfies 運算符。它確保表達式的類型兼容，而不影響類型本身。例如，讓我們看下面的代碼：

 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


interface CompilerOptions {
 strict?: boolean;
 outDir?: string;
 // ...
}

interface ConfigSettings {
 compilerOptions?: CompilerOptions;
 extends?: string | string[];
 // ...
}

let myConfigSettings = {
 compilerOptions: {
 strict: true,
 outDir: "../lib",
 // ...
 },

 extends: [
 "@tsconfig/strictest/tsconfig.json",
 "../../../tsconfig.base.json"
 ],

} satisfies ConfigSettings;

在這裡，TypeScript 知道它 myConfigSettings.extends 是用數組聲明的，因為在 satisfies 驗證我們對象的類型時，它並沒有直接將其更改為 ConfigSettings 並丟失信息。所以如果我們想映射過來 extends，那很好。

1
2
3


declare function resolveConfig(configPath: string): CompilerOptions;

let inheritedConfigs = myConfigSettings.extends.map(resolveConfig);

這對 TypeScript 用戶很有幫助，但是很多人使用 TypeScript 來使用 JSDoc 註釋對他們的 JavaScript 代碼進行類型檢查。這就是為什麼 TypeScript 5.0 支持一個名為 JSDoc 的新標籤，@satisfies 它做的事情完全一樣。

/** @satisfies */ 可以捕獲類型不匹配：

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


// @ts-check

/**
 * @typedef CompilerOptions
 * @prop {boolean} [strict]
 * @prop {string} [outDir]
 */

/**
 * @satisfies {CompilerOptions}
 */
let myCompilerOptions = {
 outdir: "../lib",
 // ~~~~~~ oops! we meant outDir
};

但它會保留我們表達式的原始類型，允許我們稍後在代碼中更精確地使用我們的值。

 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


// @ts-check

/**
 * @typedef CompilerOptions
 * @prop {boolean} [strict]
 * @prop {string} [outDir]
 */

/**
 * @typedef ConfigSettings
 * @prop {CompilerOptions} [compilerOptions]
 * @prop {string | string[]} [extends]
 */


/**
 * @satisfies {ConfigSettings}
 */
let myConfigSettings = {
 compilerOptions: {
 strict: true,
 outDir: "../lib",
 },
 extends: [
 "@tsconfig/strictest/tsconfig.json",
 "../../../tsconfig.base.json"
 ],
};

let inheritedConfigs = myConfigSettings.extends.map(resolveConfig);

/** @satisfies */ 也可以在任何帶括號的表達式上內聯使用。我們可以 myConfigSettings 這樣寫：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


let myConfigSettings = /** @satisfies {ConfigSettings} */ ({
 compilerOptions: {
 strict: true,
 outDir: "../lib",
 },
 extends: [
 "@tsconfig/strictest/tsconfig.json",
 "../../../tsconfig.base.json"
 ],
});

為什麼？當您更深入地了解其他一些代碼（例如函數調用）時，它通常更有意義。

1
2
3


compileCode(/** @satisfies {ConfigSettings} */ ({
 // ...
}));

此功能由 Oleksandr Tarasiuk提供！

JSDoc 支持 `@overload`

在 TypeScript 中，您可以為函數指定重載。重載為我們提供了一種方式，可以用不同的參數調用一個函數，並可能返回不同的結果。他們可以限制調用者實際使用我們函數的方式，並優化他們將返回的結果。

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


// Our overloads:
function printValue(str: string): void;
function printValue(num: number, maxFractionDigits?: number): void;

// Our implementation:
function printValue(value: string | number, maximumFractionDigits?: number) {
 if (typeof value === "number") {
 const formatter = Intl.NumberFormat("en-US", {
 maximumFractionDigits,
 });
 value = formatter.format(value);
 }

 console.log(value);
}

在這裡，我們說過 printValue 將 string 或 number 作為其第一個參數。如果它需要一個 number，它可以使用第二個參數來確定我們可以打印多少個小數位。

TypeScript 5.0 現在允許 JSDoc 使用新標籤聲明重載 @overload。每個帶有標記的 JSDoc 註釋都 @overload 被視為以下函數聲明的不同重載。

 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


// @ts-check

/**
 * @overload
 * @param {string} value
 * @return {void}
 */

/**
 * @overload
 * @param {number} value
 * @param {number} [maximumFractionDigits]
 * @return {void}
 */

/**
 * @param {string | number} value
 * @param {number} [maximumFractionDigits]
 */
function printValue(value, maximumFractionDigits) {
 if (typeof value === "number") {
 const formatter = Intl.NumberFormat("en-US", {
 maximumFractionDigits,
 });
 value = formatter.format(value);
 }

 console.log(value);
}

現在，無論我們是在 TypeScript 還是 JavaScript 文件中編寫，TypeScript 都可以讓我們知道我們是否錯誤地調用了我們的函數。

1
2
3
4
5
6


// all allowed
printValue("hello!");
printValue(123.45);
printValue(123.45, 2);

printValue("hello!", 123); // error!

這個新標籤的實現要歸功於 Tomasz Lenarcik。

在tsc `--build` 時可以傳入的新指令

TypeScript 現在允許在 --build 模式下傳遞以下指令：

--declaration
--emitDeclarationOnly
--declarationMap
--sourceMap
--inlineSourceMap

這使得自定義構建的某些部分變得更加容易，您可能有不同的開發和生產構建。

例如，庫的開發構建可能不需要生成聲明文件，但生產構建需要。項目可以將聲明發射配置為默認關閉，只需使用：

1

tsc --build -p ./my-project-dir

一旦在內循環中完成迭代，“生產"構建就可以傳遞指令 --declaration：

1

tsc --build -p ./my-project-dir --declaration

有關此更改的更多信息，請參見此處。

編輯器中不區分大小寫的導入排序

在 Visual Studio 和 VS Code 等編輯器中，TypeScript 支持組織和排序導入和導出的體驗。但是，對於列表何時"排序”，通常會有不同的解釋。

例如，下面的導入列表是否排序？

1
2
3
4
5


import {
 Toggle,
 freeze,
 toBoolean,
} from "./utils";

答案可能令人驚訝地是"視情況而定"。如果我們不關心區分大小寫，那麼這個列表顯然沒有排序。這封信 f 出現在 t 和之前 T。

但在大多數編程語言中，排序默認是比較字符串的字節值。JavaScript 比較字符串的方式意味著 "Toggle" 總是在前面 "freeze"，因為根據 ASCII 字符編碼，大寫字母在小寫字母之前。所以從這個角度來看，導入列表是排序的。

TypeScript 之前考慮對導入列表進行排序，因為它正在進行基本的區分大小寫的排序。對於喜歡不區分大小寫排序的開發人員，或者使用像 ESLint 這樣默認需要不區分大小寫排序的工具的開發人員來說，這可能是一個令人沮喪的地方。

TypeScript 現在默認檢測區分大小寫。這意味著 TypeScript 和 ESLint 等工具通常不會就如何最好地對導入進行排序而相互"爭吵"。

我們的團隊也一直在試驗進一步的排序策略，您可以在此處閱讀有關內容。這些選項最終可能由編輯器配置。目前，它們仍然不穩定且處於試驗階段，您現在可以通過使用 typescript.unstableJSON 選項中的條目在VS Code 中選擇加入它們。以下是您可以嘗試的所有選項（設置為默認值）：

 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
33
34
35
36
37
38
39
40
41
42
43


{
 "typescript.unstable": {
 // Should sorting be case-sensitive? Can be:
 // - true
 // - false
 // - "auto" (auto-detect)
 "organizeImportsIgnoreCase": "auto",

 // Should sorting be "ordinal" and use code points or consider Unicode rules? Can be:
 // - "ordinal"
 // - "unicode"
 "organizeImportsCollation": "ordinal",

 // Under `"organizeImportsCollation": "unicode"`,
 // what is the current locale? Can be:
 // - [any other locale code]
 // - "auto" (use the editor's locale)
 "organizeImportsLocale": "en",

 // Under `"organizeImportsCollation": "unicode"`,
 // should upper-case letters or lower-case letters come first? Can be:
 // - false (locale-specific)
 // - "upper"
 // - "lower"
 "organizeImportsCaseFirst": false,

 // Under `"organizeImportsCollation": "unicode"`,
 // do runs of numbers get compared numerically (i.e. "a1" < "a2" < "a100")? Can be:
 // - true
 // - false
 "organizeImportsNumericCollation": true,

 // Under `"organizeImportsCollation": "unicode"`,
 // do letters with accent marks/diacritics get sorted distinctly
 // from their "base" letter (i.e. is é different from e)? Can be
 // - true
 // - false
 "organizeImportsAccentCollation": true
 },
 "javascript.unstable": {
 // same options valid here...
 },
}

您可以閱讀有關自動檢測和指定不區分大小寫的原始工作的更多詳細信息，然後是更廣泛的選項集。

switch/case 語法補足

在編寫 switch 語句時，TypeScript 現在會檢測被檢查的值何時具有文字類型。如果是這樣，它將提供一個完成每個未發現的腳手架 case。

您可以在 GitHub 上查看實施細節。

速度、內存和包大小優化

TypeScript 5.0 在我們的代碼結構、數據結構和算法實現中包含許多強大的變化。這些都意味著你的整個體驗應該更快，不僅僅是運行 TypeScript，甚至安裝它。

以下是我們相對於 TypeScript 4.9 在速度和大小方面取得的一些有趣的勝利。

設想	時間或大小相對於 TS 4.9
material-ui 構建時間	90%
TypeScript 編譯器啟動時間	89%
編劇建造時間	88%
TypeScript Compiler 自建時間	87%
Outlook Web 構建時間	82%
VS 代碼構建時間	80%
打字稿 npm 包大小	59%

如何？有一些顯著的改進，我們希望在未來提供更多細節。但我們不會讓您等待那篇博文。

首先，我們最近將 TypeScript 從命名空間遷移到模塊，使我們能夠利用現代構建工具來執行範圍提升等優化。使用此工具、重新審視我們的打包策略並刪除一些已棄用的代碼，已將 TypeScript 4.9 的 63.8 MB 包大小減少了約 26.4 MB。它還通過直接函數調用為我們帶來了顯著的加速。我們在這裡整理了一份關於我們遷移到模塊的詳細文章。

TypeScript 還為編譯器中的內部對像類型增加了更多的統一性，並且還精簡了存儲在其中一些對像類型上的數據。這減少了多態操作，同時平衡了因使我們的對象形狀更統一而增加的內存使用量。

在將信息序列化為字符串時，我們還執行了一些緩存。類型顯示可能作為錯誤報告、聲明發出、代碼完成等的一部分發生，最終可能會相當昂貴。TypeScript 現在緩存了一些常用的機制以在這些操作中重用。

我們做出的另一個改進解析器的顯著變化是利用 var 偶爾迴避使用 let 和 const 跨閉包的成本。這提高了我們的一些解析性能。

總的來說，我們預計大多數代碼庫應該會看到 TypeScript 5.0 的速度提升，並且始終能夠重現 10% 到 20% 之間的勝利。當然，這將取決於硬件和代碼庫特性，但我們鼓勵您今天就在您的代碼庫上嘗試一下！

有關詳細信息，請參閱我們的一些顯著優化：

重大更改和棄用

運行時要求

TypeScript 現在以 ECMAScript 2018 為目標。TypeScript 包還設置了最低預期引擎 12.20。對於 Node 用戶，這意味著 TypeScript 5.0 的最低版本要求至少為 Node.js 12.20 及更高版本。

`lib.d.ts`變化

更改 DOM 類型的生成方式可能會對現有代碼產生影響。值得注意的是，某些屬性已從 number 數字文字類型轉換為數字文字類型，並且用於剪切、複製和粘貼事件處理的屬性和方法已跨界面移動。

API 重大變更

在 TypeScript 5.0 中，我們轉向了模塊，刪除了一些不必要的接口，並進行了一些正確性改進。有關更改內容的更多詳細信息，請參閱我們的 API 重大更改頁面。

關係運算符中禁止的隱式強制轉換

如果您編寫的代碼可能會導致隱式的字符串到數字強制轉換，則 TypeScript 中的某些操作會警告您：

1
2
3


function func(ns: number | string) {
 return ns * 4; // Error, possible implicit coercion
}

在 5.0 中，這也將應用於關係運算符 >、<、<= 和 >=：

1
2
3


function func(ns: number | string) {
 return ns > 4; // Now also an error
}

如果需要，要允許這樣做，您可以顯式地將操作數強制為 number using +：

1
2
3


function func(ns: number | string) {
 return +ns > 4; // OK
}

此正確性改進由 Mateusz Burzyński 提供。

枚舉大修

enum 自從它的第一個版本以來，TypeScript 就一直存在一些關於 s 的奇怪之處。在 5.0 中，我們正在清理其中的一些問題，並減少理解 enum 您可以聲明的各種 s 所需的概念數。

作為其中的一部分，您可能會看到兩個主要的新錯誤。首先是將域外文字分配給類型 enum 現在會像人們預期的那樣出錯：

1
2
3
4
5
6
7
8


enum SomeEvenDigit {
 Zero = 0,
 Two = 2,
 Four = 4
}

// Now correctly an error
let m: SomeEvenDigit = 1;

另一個是用混合數字和間接字符串枚舉引用聲明值的枚舉會錯誤地創建一個全數字 enum：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


enum Letters {
 A = "a"
}
enum Numbers {
 one = 1,
 two = Letters.A
}

// Now correctly an error
const t: number = Numbers.two;

您可以在相關更改中查看更多詳細信息。

對構造函數中的參數裝飾器進行更準確的類型檢查 `--experimentalDecorators`

TypeScript 5.0 使 --experimentalDecorators。這一點變得明顯的一個地方是在構造函數參數上使用裝飾器時。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


export declare const inject:
 (entity: any) =>
 (target: object, key: string | symbol, index?: number) => void;

export class Foo {}

export class C {
 constructor(@inject(Foo) private x: any) {
 }
}

此調用將失敗，因為 key 需要一個 string | symbol，但構造函數參數收到一個鍵 undefined。key 正確的解決方法是更改 within 的類型 inject。如果您使用的是無法升級的庫，一個合理的解決方法是包裝 inject 一個類型更安全的裝飾器函數，並在 key。

更多詳情，請參閱本期。

棄用和默認更改

在 TypeScript 5.0 中，我們棄用了以下設置和設置值：

--target: ES3
--out
--noImplicitUseStrict
--keyofStringsOnly
--suppressExcessPropertyErrors
--suppressImplicitAnyIndexErrors
--noStrictGenericChecks
--charset
--importsNotUsedAsValues
--preserveValueImports
prepend 在項目參考中

在 TypeScript 5.5 之前，這些配置將繼續被允許，屆時它們將被完全刪除，但是，如果您正在使用這些設置，您將收到警告。在 TypeScript 5.0 以及未來版本 5.1、5.2、5.3 和 5.4 中，您可以指定 "ignoreDeprecations": "5.0" 屏蔽這些警告提示。我們還將很快發布一個4.9 補丁，以允許指定 ignoreDeprecations 以允許更平滑的升級。除了棄用之外，我們還更改了一些設置以更好地改進 TypeScript 中的跨平台行為。

--newLine，它控制 JavaScript 文件中發出的行尾，如果未指定，過去常常根據當前操作系統進行推斷。我們認為構建應該盡可能具有確定性，並且 Windows 記事本現在支持換行符行結尾，因此新的默認設置是 LF。舊的特定於操作系統的推理行為不再可用。

--forceConsistentCasingInFileNames，這確保了項目中對同一文件名的所有引用都在大小寫中達成一致，現在默認為 true。這有助於捕獲在不區分大小寫的文件系統上編寫的代碼的差異問題。

您可以留下反饋並查看有關 5.0 棄用跟踪問題的更多信息。

下一步是什麼？

不要操之過急，TypeScript 5.1 已經在開發中了，我們所有的計劃都已經在 GitHub 上了。如果你躍躍欲試，我們鼓勵你嘗試 TypeScript 的每日構建版本或針對 VS Code 的 JavaScript 和 TypeScript Nightly 擴展！

當然，如果您選擇只享受 TypeScript 的新穩定版，我們也不會感到受傷。我們希望 TypeScript 5.0 讓每個人的編碼更快、更有趣。

Happy Hacking！

by Daniel Rosenwasser 和 TypeScript 團隊

【Petite-Vue】大小只有 ~6KB 的 mini Vue！

Fri, 10 Mar 2023 00:00:00 +0000

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

Vue 可以作為獨立的腳本文件使用，無需構建步驟！如果你有一個非前後端分離的歷史項目，並且它已經渲染了大部分的 HTML，或者你的前端邏輯並不復雜，不需要構建步驟，Vue 也提供了另一個適用於此類無構建步驟場景的替代版 Petite-Vue，主要為漸進式增強已有的 HTML 作了特別的優化。功能更加精簡，十分輕量。

Petite-Vue 的特點

相對 Vue3 而言，Petite-Vue 有如下特點：

提供精簡版的與 Vue3 語法和表現一致的模板語言
僅由渲染模塊和響應式系統模塊組成
渲染模塊沒有採用虛擬 DOM，而是採用在線解析渲染的方式
響應式系統模塊對外暴露 reactive 接口提供構建全局狀態管理器的能力
代碼庫體積在 gzip 壓縮後 ~6KB，十分適合與項目已有的 LayUI、MiniUI 等 UI 庫搭配使用

什麼是 Petite-Vue？

根據官方解釋，Petite-Vue 是專門為非前後端分離的歷史項目提供和 Vue 相近的響應式開發模式。與完整的 Vue 相比最大的特點是，面對數據的變化 Petite-Vue 採取直接操作 DOM 的方式重新渲染。

具體的使用方式請參考 GitHub，在這裡我想展示兩個示例：

代碼庫結構介紹

examples 各種使用示例
scripts 打包發布腳本
tests 測試用例
src
- directives v-if 等內置指令的實現
- app.ts createApp 函數
- block.ts 塊對象
- context.ts 上下文對象
- eval.ts 提供 v-if="count === 1" 等表達式運算功能
- scheduler.ts 調度器
- utils.ts 工具函數
- walk.ts 模板解析

若想構建自己的版本只需在控制台執行 npm run build 即可。

範例(一) - 在線渲染

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


<style>
 [v-cloak] {
 display: none;
 }
</style>
<div v-scope="App"></div>

<script type="module">
 import { createApp } from 'https://unpkg.com/petite-vue?module'

 createApp({
 App: {
 $template: `
 <span v-cloak v-if="status === 'offline'"> OFFLINE </span>
 <span v-else> ONLINE </span>
 `,
 }
 status: 'online'
 }).mount('[v-scope]')
</script>

上述代碼最終輸出結果為 <div><span> ONLINE </span></div>，但渲染過程是直接在 DOM Tree 上進行(分為如下4個步驟)，當瀏覽器資源緊張時整個渲染過程將會被用戶一覽無餘：

生成模板

1
2
3
4


<div>
 <span v-cloak v-if="status === 'offline'"> OFFLINE </span>
 <span v-else> ONLINE </span>
</div>

移除 v-cloak 屬性

1
2
3
4


<div>
 <span v-if="status === 'offline'"> OFFLINE </span>
 <span v-else> ONLINE </span>
</div>

解析 v-if 和 v-else 指令

1
2
3


<div>
 <span v-if="status === 'offline'"> OFFLINE </span>
</div>

1
2


<div>
</div>

最終渲染

1
2
3


<div>
 <span> ONLINE </span>
</div>

那麼用戶很有可能會看到閃屏現象：ONLINE ➡️ OFFLINE ONLINE ➡️ OFFLINE ➡️ EMPTY ➡️ ONLINE

範例(二) - 組件化

 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
33


<div v-scope="App"></div>

<script type="module">
 import { createApp } from 'https://unpkg.com/petite-vue?module'

 const App = {
 $template: `
 <div v-scope="Counter(1)"></div>
 <div v-scope="Message()"></div>
 `
 }

 const Counter = initialCount => ({
 $template: `
 <span></span>
 <button @click="handleAdd">ADD</button>
 `,
 count: initialCount || 0
 handleAdd() {
 this.count += 1
 }
 })

 const Message = () => {
 $template: `<div></div>`
 }

 createApp({
 App,
 Counter,
 Message,
 }).mount('[v-scope]')
</script>

Petite-Vue 雖然沒有提供明確的組件構建方式，但通過 v-scope 屬性我們依然可以採取組件化構建我們的頁面。

但上述例子有明顯的問題採取全局組件註冊機制，如例子中即使 Message 組件不需要還是能引用 Counter 組件，假如註冊的不是 Counter 組件的構造函數，那麼 Counter 的狀態將會被意外修改。

1
2
3


createApp({
 Counter: Counter()
})

快速上手

自動初始化

Petite-Vue 無需構建流程即可使用。只需從 CDN 加載它：

1
2
3
4
5
6
7


<script src="https://unpkg.com/petite-vue" defer init></script>

<!-- 頁面任意位置 -->
<div v-scope="{ count: 0 }">
 {{ count }}
 <button @click="count++">inc</button>
</div>

用 v-scope 標記頁面上應由 Petite-Vue 控制的區域，同時也是聲明 data 與 methods。
該 defer 屬性使腳本在 HTML 內容被解析後執行。
該 init 屬性告訴 Petite-Vue 自動查找和初始化頁面上的所有包含 v-scope 的元素。

這裡的 init 其實也就是 PetiteVue.createApp().mount() 的簡潔寫法；

閱讀源碼可知：

const s = document.currentScript;

如果 ( s && s . hasAttribute ( ‘init ’ )) {

createApp().mount();

}

如果不想自動初始化，那麼移除 init 屬性，且在 script 標籤中，增加 PetiteVue.createApp().mount()。

手動初始化

如果您不想要自動初始化，請刪除該 init 屬性並將腳本移動到 <body> 末尾：

1
2
3
4


<script src="https://unpkg.com/petite-vue"></script>
<script>
 PetiteVue.createApp().mount()
</script>

或者，使用 ES 模塊構建：

1
2
3
4


<script type="module">
 import { createApp } from 'https://unpkg.com/petite-vue?module'
 createApp().mount()
</script>

重點：在開發時期，CDN 地址可以是 https://unpkg.com/petite-vue 這樣簡短的，但對於生產使用時，應該要使用完整解析的 CDN URL。
如：https://unpkg.com/petite-vue@0.4.1/dist/petite-vue.iife.js 或者 https://unpkg.com/petite-vue@0.4.1/dist/petite-vue.es.js (ES 模塊引用時)，避免解析和重定向文本之外，還有避免版本不同導致項目出現意外情況。

使用終端命令可以快速簡單下載代碼到本地：

1

curl unpkg.com/petite-vue@0.4.1/dist/petite-vue.iife.js --output petite-vue@0.4.1-iife.js

根作用域 (Root Scope) / 作用域 (Scope)

這裡的作用域和我們編寫 JavaScript 時說的作用域是一致的，作用是限定函數和變量的可用範圍，減少命名衝突。具有如下特點：

作用域之間存在父子關係和兄弟關係，整體構成一顆作用域樹。
子作用域的變量或屬性可覆蓋祖先作用域同名變量或屬性的訪問性。
若對僅祖先作用域存在的變量或屬性賦值，將賦值給祖先作用域的變量或屬性。

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


// 全局作用域
var globalVariable = 'hello'
var message1 = 'there'
var message2 = 'bye'

(() => {
 // 局部作用域 A
 let message1 = '局部作用域A'
 message2 = 'see you'
 console.log(globalVariable, message1, message2)
})()
// 輸出：hello 局部作用域 A see you

(() => {
 // 局部作用域 B
 console.log(globalVariable, message1, message2)
})()
// 輸出：hello there see you

createApp()，它接收一個數據對像作為根範圍中的變量，供模版中使用。

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


<script type="module">
 import { createApp } from 'https://unpkg.com/petite-vue?module';

 createApp({
 count: 0,
 // getters
 get plusOne() {
 return this.count + 1;
 },
 increment() {
 this.count++;
 },
 }).mount();
</script>

<!-- v-scope value can be omitted -->
<div v-scope>
 <p>{{ count }}</p>
 <p>{{ plusOne }}</p>
 <button @click="increment">increment</button>
</div>

這樣在模版中就可以使用 count 變量、increment 方法了。

掛載元素 (Mount)

mount() 沒有傳入掛載元素時，Petite-Vue 作用於整個頁面，但當傳入掛載元素時，那麼僅作用於掛載元素及其內的元素。

這也意味著，我們可以在同一頁面掛載多個 Petite-Vue 應用，每一個應用都有其獨立的根變量範圍。

1
2
3
4
5
6
7


createApp({
 // root scope for app one
}).mount('#app1');

createApp({
 // root scope for app two
}).mount('#app2');

生命週期

在 Petite-Vue 中，可以監聽每一個元素的掛載和卸載事件。

在 v0.4.0 開始，綁定生命週期事件需要加上 @vue: 前綴。

1
2
3
4
5
6
7
8
9


<!-- v0.4.0 以下 -->
<div v-if="show" @mounted="console.log('mounted on: ', $el)" @unmounted="console.log('unmounted: ', $el)">
 some node
</div>

<!-- v0.4.0 以上 -->
<div v-if="show" @vue:mounted="console.log('mounted on: ', $el)" @vue:unmounted="console.log('unmounted: ', $el)">
 some node
</div>

v-effect

用 v-effect 執行響應式內聯語句：

1
2
3
4


<div v-scope="{ count: 0 }">
 <div v-effect="$el.textContent = count"></div>
 <button @click="count++">++</button>
</div>

effect 響應式的追蹤其依賴，並在依賴更改時重新執行，因此每當更改 count 時它都會重新運行。

組件 (Component)

組件的概念在 Petite-Vue 中有所不同，因為它更加簡單。

組件有兩種方式來創建，分別是純數據的函數組件和帶有模板的函數組件。

使用組件，是需要在元素中用 v-scope 來調用函數。

純數據的函數組件

 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


<script type="module">
 import { createApp } from 'https://unpkg.com/petite-vue?module'

 function Counter(props) {
 return {
 count: props.initialCount,
 inc() {
 this.count++
 },
 mounted() {
 console.log(`I'm mounted!`)
 }
 }
 }

 createApp({
 Counter
 }).mount()
</script>

<div v-scope="Counter({ initialCount: 1 })" @vue:mounted="mounted">
 <p>{{ count }}</p>
 <button @click="inc">increment</button>
</div>

<div v-scope="Counter({ initialCount: 2 })">
 <p>{{ count }}</p>
 <button @click="inc">increment</button>
</div>

帶有模板的函數組件

如果還需要模板的話，相比函數組件是多了一個字段來聲明模板：$template，該字段的值可以是一個模板字符串，也可以是 <template> 元素的 ID 選擇器。(推薦用 template 元素)。

 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


<script type="module">
 import { createApp } from 'https://unpkg.com/petite-vue?module';

 function Counter(props) {
 return {
 $template: '#counter-template',
 // $template: `
 // My count is {{count}}
 // <button @click="inc">+aaa+</button>
 // `,
 count: props.initialCount,
 inc() {
 this.count++;
 },
 };
 }

 createApp({
 Counter,
 }).mount();
</script>

<template id="counter-template">
 My count is {{ count }}
 <button @click="inc">++</button>
</template>

<!-- reuse it -->
<div v-scope="Counter({ initialCount: 1 })"></div>
<div v-scope="Counter({ initialCount: 2 })"></div>

全局狀態管理

沒錯，即便是簡單的 mini Vue，也可以有全局狀態管理。這裡使用的是 vue3 的 reactive API，來實現全局狀態管理。

 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


<script type="module">
 import { createApp, reactive } from 'https://unpkg.com/petite-vue?module'

 const store = reactive({
 count: 0,
 inc() {
 this.count++
 }
 })

 // manipulate it here
 store.inc()

 createApp({
 // share it with app scopes
 store
 }).mount()
</script>

<div v-scope="{ localCount: 0 }">
 <p>Global {{ store.count }}</p>
 <button @click="store.inc">increment</button>

 <p>Local {{ localCount }}</p>
 <button @click="localCount++">increment</button>
</div>

指令 (Directive)

內建指令

v-model
v-if / v-else / v-else-if
v-for
v-show
v-on(别名：@)
v-bind(别名：:)
v-html / v-text / v-pre
v-once
v-cloak (可用來配合 CSS 做未渲染時隱藏)

自定義指令

Petite-Vue 的自定義指令與 vue 有些不同，那麼怎麼註冊一個指令？

指令聲明：一個函數，const myDirective = (ctx) => {};
- ctx 是一個對象，裡面有 el、arg、get、effect 等屬性，具體可以參考文檔或者閱讀源碼
- 函數 return，是在指令卸載時候會觸發。
註冊指令：createApp().directive('dir-name', dirFn).mount()

v-html 指令的實現：

1
2
3
4
5
6


const html = ({ el, get, effect }) => {
 // effect 每次 get() 更改後就會執行
 effect(() => {
 el.innerHTML = get();
 });
};

自定義指令範例：

 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


const myDirective = (ctx) => {
 // the element the directive is on
 ctx.el
 // the raw value expression
 // e.g. v-my-dir="x" then this would be "x"
 ctx.exp
 // v-my-dir:foo -> "foo"
 ctx.arg
 // v-my-dir.mod -> { mod: true }
 ctx.modifiers
 // evaluate the expression and get its value
 ctx.get()
 // evaluate arbitrary expression in current scope
 ctx.get(`${ctx.exp} + 10`)

 // run reactive effect
 ctx.effect(() => {
 // this will re-run every time the get() value changes
 console.log(ctx.get())
 })

 return () => {
 // cleanup if the element is unmounted
 }
}

// register the directive
createApp().directive('my-dir', myDirective).mount()

自定義模板

這個可以通過給 createApp 的配置項增加屬性 $delimiters: ['${', '}'] 來實現，通常在服務器端模板語言一起使用時比較有用。

Petite-Vue vs Vue

Petite-Vue 僅有的特性：

v-scope
v-effect
@vue:mounted、@vue:unmounted 事件

不同的功能：

在表達式中，$el 指向指令綁定到的當前元素（而不是組件根元素）
createApp() 接受全局狀態而不是組件
組件被簡化為函數返回對象
自定義指令有不同的語法

共用的特性：

共有的特性
`{{ }}`
v-bind
v-on
v-model
v-if / v-else / v-else-if
v-for
v-show
v-html
v-text
v-pre
v-once
v-cloak
reactive()
nextTick()
Template refs

Petite-Vue 不支持的特性：

一些特性因為它們在漸進增強的背景下具有相對較低的使用頻率而被丟棄。

如果你需要這些特性，你可能應該只使用標準的 Vue：

ref()、computed() 等組合式API
Render functions ( Petite-Vue 沒有 Virtual DOM)
Reactivity 響應式數據類型(Map、Set、…等，為了體積更小而刪除)
Transition、KeepAlive、Teleport、Suspense
v-for 的深解構
v-on="object" 對象語法
v-is 動態組件
v-bind:style 自動前綴

總結

總結來說，Petite-Vue 這個項目，挺適合「用不到 Vue、React 等這些偏大的前端框架的簡單頁面」，或是「既有的非前後端分離的歷史項目」來做使用的，有著 Vue 的開發體驗，也能不增加項目的複雜度，簡直是一個完美的體驗！

【Typescript】tsconfig.json 的設定與資料型別介紹筆記

Tue, 07 Mar 2023 00:00:00 +0000

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

本篇來簡單說明一下 typescript 的 tsconfig.json，並記錄一下 typescript 各個資料型別。

TypeScript 是什麼？

❓這個應該是大家都有犯的錯誤，下面這張圖你看到錯誤了嗎？

.
.
.

🅰️：就是寫錯字，record 少了個 s，有時候即使報 error 了，你還找不到。

JavaScript 就是一個自由的靈魂，你永遠不知道你接了什麼物件，寫的時候很爽，debug 的時候黑人問號。

✅ 而下面這張就引用了 TypeScript 的 interface 來定義物件的型別，讓你在開發的時候就可以馬上知道錯誤，減少了很多 debug 的時間。

tsconfig.json

tsconfig.json 是 typescript 編譯設定的文件。

在目錄下執行以下指令，產生 tsconfig.json：

1

tsc --init

tsconfig.json 的預設

一開始我們拿到的 tsconfig 檔，裡面的預設就有這些：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


{
 "compilerOptions": {
 "target": "es5", // 指定編譯生成的JS版本
 "module": "commonjs", // 指定生成哪種模組
 "strict": true, // 啟用所有嚴格類型檢查選項
 "esModuleInterop": true, // 兼容模組導入的方式
 "skipLibCheck": true, // 不會檢查引入的函式庫檔案
 "forceConsistentCasingInFileNames": true // 確保檔案的大小寫一致
 }
}

tsconfig.json 還有哪些設定？

除了預設 compilerOptions 的設定外，還有：

compileOnSave：在最上層設定 compileOnSave 屬性，可以讓 IDE 編輯器在儲存檔案的時候根據 tsconfig.json 重新產生編譯檔案。
compilerOptions：所有的編譯設定都會寫在 compilerOptions 裡，我們一開始取得的預設設定就在 compilerOptions。
include：指定編譯需要編譯的文件或目錄。
exclude：指定編譯器需要排除的文件或文件夾。如默認排除 node_modules 文件夾。
- include 及 exclude 最常見的萬用字元包括：
- *：表示匹配0至多個字元(不包含分隔符號)
- ?：匹配一個相符字元(不包含分隔符號)
- **/：表示匹配所有子資料夾
extends：引入其他配置檔案，繼承配置。default 包含當前目錄和子目錄下所有 TypeScript 文件。
files： files 的值為包含相對或絕對文件路徑的 list，表示需要編譯的文件。default 包含當前目錄和子目錄下所有 TypeScript 文件。若指定 files，則只會編譯指定的檔案。
references：指定要引用的專案。有時候為了方便將前端項目和後端 node 項目放在同一個目錄下開發，兩個項目依賴同一個配置文件和通用文件。
typeAcquisition：設置自動引入函式庫相關定義文件。包含 3 個子屬性：
- enable：布林類型，是否開啟自動引入庫類型定義文件(.d.ts)，默認為 false；
- include：數組類型，允許自動引入的函式庫名，如：[“jquery”, “lodash”]；
- exculde：數組類型，排除的函式庫名；

概括

 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
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79


{
 "compileOnSave": false, // 編輯器在儲存檔案的時候根據 tsconfig.json 重新產生編譯檔案
 "compilerOptions": {
 /* 基本選項 */
 "target": "es5", // 指定編譯生成的 JS 版本: 'ES3' (default), 'ES5', 'ES6'/'ES2015', 'ES2016', 'ES2017', or 'ESNEXT'
 "module": "commonjs", // 指定生成哪種模組: 'commonjs', 'amd', 'system', 'umd' or 'es2015'
 "lib": [], // 編譯需要引入的特定函式庫檔案
 "allowJs": true, // 允許編譯 javascript 文件
 "checkJs": true, // 報告 javascript 文件中的錯誤
 "jsx": "preserve", // 指定 jsx 代碼的生成: 'preserve', 'react-native', or 'react'
 "declaration": true, // 生成相應的 '.d.ts' 文件
 "declarationMap": true, // 生成宣告檔案的 sourceMap
 "sourceMap": true, // 生成相應的 '.map' 文件
 "outFile": "./", // 將輸出文件合併為一個文件
 "outDir": "./", // 指定輸出目錄
 "rootDir": "./", // 檔案應該要被放置的位置
 "composite": true, // 是否編譯構建引用項目
 "tsBuildInfoFile": "./", // 指定文件存儲增量編譯信息，默認為 tsconfig.tsbuildinfo
 "removeComments": true, // 刪除編譯後的所有的註釋
 "noEmit": true, // 不產生輸出檔案
 "importHelpers": true, // 從 tslib 導入輔助工具函數
 "isolatedModules": true, // 將每個文件做為單獨的 module(與 'ts.transpileModule' 類似)

 /* 嚴格的類型檢查選項 */
 "strict": true, // 啟用所有嚴格類型檢查選項
 "noImplicitAny": true, // 在表達式和聲明上有隱含的 any 類型時報錯
 "strictNullChecks": true, // 啟用嚴格的 null 檢查
 "strictFunctionTypes": true, // 啟用檢查 function 型別
 "strictBindCallApply": true, // 啟用對 bind、call、apply 更嚴格的型別檢查
 "strictPropertyInitialization": true, // 啟用 class 實例屬性的賦值檢查
 "noImplicitThis": true, // 當 this 表達式值為 any 類型的時候，生成一個錯誤
 "alwaysStrict": true, // 以嚴格模式檢查每個 module，並在每個文件裡加入 'use strict'

 /* 額外的檢查 */
 "noUnusedLocals": true, // 有未使用的變數時，拋出錯誤
 "noUnusedParameters": true, // 有未使用的參數時，拋出錯誤
 "noImplicitReturns": true, // 並不是所有 function 裡的代碼都有返回值時，拋出錯誤
 "noFallthroughCasesInSwitch": true, // 報告 switch 語句的 fallthrough 錯誤。 (即不允許 switch 的 case 語句貫穿)
 "noUncheckedIndexedAccess": true, // 檢查 index signature 屬性是否是 undefined

 /* 模組選項 */
 "moduleResolution": "node", // 選擇模組解析策略： 'node' (Node.js) or 'classic' (TypeScript pre-1.6)
 "baseUrl": "./", // 用於解析非相對模組名稱的基目錄
 "paths": {}, // 模組名到基於 baseUrl 的路徑映射的列表
 "rootDirs": [], // 根文件夾列表，其組合內容表示項目運行時的結構內容
 "typeRoots": [], // 包含類型聲明的文件列表
 "types": [], // 需要包含的類型聲明文件名列表
 "allowSyntheticDefaultImports": true, // 允許從沒有設置默認導出的模組中默認導入

 /* Source Map Options */
 "sourceRoot": "./", // 指定調試器應該找到 TypeScript 文件而不是源文件的位置
 "mapRoot": "./", // 指定調試器應該找到映射文件而不是生成文件的位置
 "inlineSourceMap": true, // 生成單個 soucemaps 文件，而不是將 sourcemaps 生成不同的文件
 "inlineSources": true, // 將代碼與 sourcemaps 生成到一個文件中，要求同時設置了 --inlineSourceMap 或 --sourceMap 屬性

 /* 其他選項 */
 "experimentalDecorators": true, // 啟用裝飾器
 "emitDecoratorMetadata": true, // 為裝飾器提供元數據的支持

 /* 進階選項 */
 "skipLibCheck": true, // 不會檢查引入的函式庫檔案
 "forceConsistentCasingInFileNames": true // 確保檔案的大小寫一致
 },
 "files":[
 "hello.ts" // 若指定 files，則只會編譯指定的 hello.ts 檔案
 ],
 "exclude": [ // 指定編譯器需要排除的文件或文件夾
 "node_modules"
 ],
 "extends": "./tsconfig.base.json", // 把基礎配置抽離成 tsconfig.base.json 檔案，然後引入
 "references": [ // 指定依賴的程式路徑
 { "path": "./common" }
 ],
 "typeAcquisition": { // 自動引入函式庫相關定義文件(.d.ts)。
 "enable": false,
 "exclude": ["jquery"],
 "include": ["jest"]
 }
}

TypeScript 資料型別整理表

先總結一些資料型別，接著再來詳細介紹各個型別。

Type	型別分類	說明
string	primitive	字串型別
number	primitive	數值型別
boolean	primitive	布林型別
null	primitive	空值型別，亦可賦值給所有型別(嚴謹模式則無法)
undefined	primitive	undefined 型別，亦可賦值給所有型別(嚴謹模式則無法)
object	object	物件型別
array	object	可使用「型別 + 方括號」或陣列泛型來表示陣列
function	object	一個函式有輸入和輸出，可以針對參數(輸入)及返回值(輸出)進行型別規範
any	ts	允許賦值為任意型別
unknown	ts	unknown 和 any 一樣可以接受任何型別賦值，但 any 可以賦值給任何型別，unknown 只能賦值給 any 和自己
void	ts	沒有任何返回值的函式
never	ts	表示不應該存在的狀態的型別，一般用於錯誤處理函式
union types	ts	聯合型別(union type) 使用 `｜` 表示其定義的值可以為多種型別
intersection types	ts	交集型別(intersection type) 使用 `&` 表示其定義的值都必須符合多種型別
literal types	ts	某些特殊的"值"可以當作"型別"來使用
tuple	ts	tuple 就是合併了不同型別的物件
enum	ts	列舉(enum)型別可以用來管理多個同系列的常數，作為狀態判斷使用

primitive：原始型別 ts： typescript 的特殊型別

typescript 的特殊型別

any

如果你不希望某些值出現型別檢查錯誤，可以使用 any，他是用來表示允許賦值為任意型別。

❌ 假設我們設定 favoriteNumber 變數的值的型別為 string，若使用數字則會報錯。

1
2
3


let favoriteNumber: string = 'seven';
favoriteNumber = 7;
//error : Cannot assign to 'favoriteNumber' because it is a constant.

✅ 這時候使用 any，則允許任何型別。

1
2


let favoriteNumber: any = 'seven';
favoriteNumber = 7;

宣告一個變數為任意值之後，對它的任何操作，返回的內容的型別都是任意值。在 any 型別下，可以賦值給任何型別，使用任何屬性和方法，都是被允許的。

但這樣是非常危險，非必要都不會使用 any，要慎用！

未宣告型別的變數及參數也視為 any 型別

變數如果在宣告的時候，未指定其型別，那麼它會被識別為 any 型別：

1
2
3


let something; // something: any
something = 7;
something = "seven";

用 noImplicitAny，來提醒我使用了 any

如上面所述，未指定型別則被識為 any，如果你想避免這種情況，可以在 tsconfig 設定 noImplicitAny = true，或是打開 “strict”: true 開啟所有嚴謹模式。他就會提醒你使用了 any 型別。

1
2
3
4
5


{
 // ...
 "noImplicitAny": true,
 // ...
}

unknown

unknow 可以接受任何型別賦值，有點類似 any 類型，但使用上比 any 安全，來看下面例子：

1
2
3
4
5
6
7


function f1(a: any) {
 a.b(); // success
}

function f2(a: unknown) {
 a.b(); // error: Property 'b' does not exist on type 'unknown'.
}

使用 unknow 會報錯，沒有 b 函式的屬性，而 any 則會不會告訴你。

雖然 unknown 和 any 一樣可以接受任何型別賦值，但 any 可以賦值給任何型別，unknown 只能賦值給 any 和自己。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


let value: unknown;

let value1: unknown = value; // success
let value2: any = value; // success
let value3: boolean = value; // error
let value4: number = value; // error
let value5: string = value; // error
let value6: object = value; // error
let value7: any[] = value; // error
let value8: Function = value; // error

void

JavaScript 沒有空值(void)的概念，在 TypeScript 中，可以用 void 表示沒有任何返回值的函式，如以下例子，這個函式只有 alert，不會 return 任何值。

1
2
3


function alertName(): void {
 alert('My name is iris');
}

never

表示不應該存在的狀態的型別，一般用於錯誤處理函式。

1
2
3


function error(message: string): never {
 throw new Error(message);
}

此外，以下面例子，參數使用 Union Types(聯合型別)，當參數被判斷沒有其他型別時，也會被視為 never。

1
2
3
4
5
6
7
8
9


function fn(x: string | number) {
 if (typeof x === "string") {
 // do something
 } else if (typeof x === "number") {
 // do something else
 } else {
 x; // has type 'never'!
 }
}

Union Types (聯合型別)

聯合型別(Union Types)表示取值可以為多種型別中的其中一種。跟JavaScript || or 的概念是一樣的。

✅ 聯合型別使用 | 分隔每個型別。

允許 id 的型別是 string 或者 number，但是不能是其他型別。

1
2
3
4
5


function printId(id: number | string) {
 console.log("Your ID is: " + id);
}
printId(101); // success
printId("202"); // success

❌ 若使用 boolean 值，就會報錯。

1
2


printId(false); // error
// error : Argument of type 'false' is not assignable to parameter of type 'string | number'.Type 'false' is not assignable to type 'number'.

存取聯合型別的屬性或方法

當 TypeScript 不確定一個聯合型別的變數到底是哪個型別的時候，我們只能存取此聯合型別的所有型別裡共有的屬性或方法。

✅ 使用兩種型別都有的屬性時，沒問題。

1
2
3


function printId(id: number | string) {
 console.log(id.toString());
}

❌ 如果使用不同屬性，則會報錯，toUpperCase 屬性無法適用於數值型別。

1
2
3
4
5
6


function printId(id: number | string) {
 console.log(id.toUpperCase());
}

// error: Property 'toUpperCase' does not exist on type 'string | number'.
// Property 'toUpperCase' does not exist on type 'number'.

若要解決不同情境，可以使用 typeof 去做判斷。官網將這些情況限縮某個具體型別上的行為，稱作為 Narrowing。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


function printId2(id: number | string) {
 if (typeof id === "string") {
 // 型別為字串才 toUpperCase
 console.log(id.toUpperCase());
 } else {
 // 其他自動判定為 number 型別
 console.log(id);
 }
}
printId2("ABC");

若是陣列型別與其他型別聯合，可以使用 Array.isArray() 來檢查傳入的值是否為一個 Array。

1
2
3
4
5
6
7
8


function welcomePeople(x: string[] | string) {
 if (Array.isArray(x)) {
 console.log("Hello, " + x.join(" and "));
 } else {
 console.log("Welcome lone traveler " + x);
 }
}
welcomePeople(["a","b","c"]);

Intersection Types (交集型別)

Intersection Types (交集型別) 跟 JavaScript 的 && and 概念相同，使用 & 表示其定義的值都必須同時符合兩種型別。

❌ 以下面的例子，Intersection 在 primitive type(原始型別)中使用，是無法同時滿足兩種型別的，會被認定為 never 型別。

1
2
3
4
5
6
7


function printId(id: number & string) {
 console.log("Your ID is: " + id);
}
printId(101); // error
printId("202"); // error

// error: Argument of type 'number' is not assignable to parameter of type 'never'.

✅ 主要用來組合現有的型別，若都沒符合兩種型別，則會報錯提醒。而且像下面的例子，ColorfulCircle 需滿足 Colorful 及 Circle 型別。而且 TS 很聰明，radius 寫錯字寫成 raidus，complier 也會報錯提醒！

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


interface Colorful {
 color: string;
}

interface Circle {
 radius: number;
}

//用 type aliases 宣告 ColorfulCircle 型別，需滿足 Colorful 及 Circle 型別
type ColorfulCircle = Colorful & Circle;

//帶入的參數需滿足 ColorfulCircle 型別
function draw(circle: ColorfulCircle) {
 console.log(`Color was ${circle.color}`);
 console.log(`Radius was ${circle.radius}`);
}

draw({ color: "blue", radius: 42 }); // ok
draw({ color: "red", raidus: 42 }); // error
// error: Argument of type '{ color: string; raidus: number; }' is not assignable to parameter of type 'Colorful & Circle'.
// Object literal may only specify known properties, but 'raidus' does not exist in type 'Colorful & Circle'. Did you mean to write 'radius'?

Literal Types 字面值型別

string literal types

就是值的表現方式，**某些特殊的"值"可以當作"型別"**來使用，用來約束取值只能是某幾個字串中的一個。如下方讓 x 變數的字面值為"hello"。

1
2
3


let x: "hello" = "hello";
x = "hello"; // success
x = "howdy"; // Type '"howdy"' is not assignable to type '"hello"'

但很少情況會使用到一個變數只有一個值，我們可以將想要的值結合起來，如 alignment 給予 3 個字面值，其參數要符合其中一個。如果不符合這 3 個值的其中一個或寫錯字，都會報錯。

1
2
3
4
5
6


function printText(s: string, alignment: "left" | "right" | "center") {
 console.log(`${s} placed at the ${alignment}`)
}
printText("Hello, world", "left"); // success
printText("G'day, mate", "centre"); // error
// error: Argument of type '"centre"' is not assignable to parameter of type '"left" | "right" | "center"'.

numeric literal types

除了文字上，數字的操作也一樣。

執行 compare 函式的回傳值只能 -1、0 和 1：

1
2
3


function compare(a: string, b: string): -1 | 0 | 1 {
 return a === b ? 0 : a > b ? 1 : -1;
}

non-literal types

非字面值型別也可以結合操作：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


interface Options {
 width: number;
}
function configure(x: Options | "auto") {
 console.log(x);
}
configure({ width: 100 }); // success
configure("auto"); // success
configure("automatic"); // 不符 Options 及 "auto"
// error： Argument of type '"automatic"' is not assignable to parameter of type 'Options | "auto"'.

Tuple 元組

Tuple 就是合併了不同型別的物件。

定義一對值分別為 string 和 number 的元組：

1

const wayne: [string, number] = ['wayne', 18];

可以針對型別有的屬性進行使用、賦值。但當直接對元組型別的變數進行初始化或者賦值，需提供所有項目。如果要新增不同型別的項目也是無法的：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


let wayne: [string, number];
wayne = ['wayne', 18]; // 如果只有宣告 wayne 沒賦值，會是undefined，tsconfig strictNullChecks 打開的話會報錯提醒
wayne[0] = 'wayne'; // success
wayne[1] = 25; // success
wayne[0].slice(1); // success
wayne[1].toFixed(2); // success
wayne.push('male'); // success

wayne = ['wayne lin']; // error: Property '1' is missing in type '[string]' but required in type '[string, number]'.
wayne.push(true); // error: Argument of type 'true' is not assignable to parameter of type 'string | number'.

enum

列舉(Enums)型別用於取值被限定在一定範圍內的場景，可以用來管理多個同系列的常數，作為狀態判斷使用。比如一週只能有七天，顏色限定為紅綠藍等。也可以自定義來表示每一個值。

Numeric Enums

使用 enum 關鍵字來定義：

1

enum Days { Sun, Mon, Tue, Wed, Thu, Fri, Sat };

這時候我們來看編譯後，列舉成員會被賦值為從 0 開始自動遞增的數字，同時也會對列舉值到列舉名進行反向對映：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


var Days;
(function (Days) {
 Days[Days["Sun"] = 0] = "Sun";
 Days[Days["Mon"] = 1] = "Mon";
 Days[Days["Tue"] = 2] = "Tue";
 Days[Days["Wed"] = 3] = "Wed";
 Days[Days["Thu"] = 4] = "Thu";
 Days[Days["Fri"] = 5] = "Fri";
 Days[Days["Sat"] = 6] = "Sat";
})(Days || (Days = {}));

手動賦值

可以手動去定義不同的值。

1

enum Days { Sun = 7, Mon = 1, Tue, Wed, Thu, Fri, Sat };

編譯後：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


var Days;
(function (Days) {
 Days[Days["Sun"] = 7] = "Sun";
 Days[Days["Mon"] = 1] = "Mon";
 Days[Days["Tue"] = 2] = "Tue";
 Days[Days["Wed"] = 3] = "Wed";
 Days[Days["Thu"] = 4] = "Thu";
 Days[Days["Fri"] = 5] = "Fri";
 Days[Days["Sat"] = 6] = "Sat";
})(Days || (Days = {}));

要小心覆蓋的情況

如果中間突然指定了了一個值，那他會從當前的值從新開始計算。如下， Days[3] 的值先是 “Sun”，而後又被 “Wed” 覆蓋了。這個 TypeScript 是不會報錯的，所以要特別注意。

1
2
3
4
5
6


enum Days { Sun = 3, Mon = 1, Tue, Wed, Thu, Fri, Sat };

console.log(Days["Sun"] === 3); // true
console.log(Days["Wed"] === 3); // true
console.log(Days[3] === "Sun"); // false
console.log(Days[3] === "Wed"); // true

可使用型別斷言(Type Assertion)來定義

手動賦值的列舉項其中一個不想是數字，此時可以使用 any 型別斷言來讓 TypeScript 無視型別檢查。

1

enum Days { Sun = 7, Mon, Tue, Wed, Thu, Fri, Sat = <any>"S" };

編譯後：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


var Days;
(function (Days) {
 Days[Days["Sun"] = 7] = "Sun";
 Days[Days["Mon"] = 8] = "Mon";
 Days[Days["Tue"] = 9] = "Tue";
 Days[Days["Wed"] = 10] = "Wed";
 Days[Days["Thu"] = 11] = "Thu";
 Days[Days["Fri"] = 12] = "Fri";
 Days[Days["Sat"] = "S"] = "Sat";
})(Days || (Days = {}));

String Enums 字串列舉

字串 enums 沒有 number enums 可以自動遞增的行為，但字串 enum 自行定義是有他的語意在的。

1
2
3
4
5
6


enum Direction {
 Up = "UP",
 Down = "DOWN",
 Left = "LEFT",
 Right = "RIGHT",
}

Heterogeneous Enums 異構列舉

雖然 enum 可以混合數字與字串，但盡量不要寫這種寫法：

1
2
3
4


enum BooleanLikeHeterogeneousEnum {
 No = 0,
 Yes = "YES",
}

Computed and constant members 常數項和計算所得項

列舉項有兩種型別：常數項(constant member)和計算所得項(computed member)。

前面我們所舉的例子都是常數項，一個典型的計算所得項的例子如下，“blue”.length 就是一個計算所得項：

1
2


enum Color { Red, Green, Blue = "blue".length };
console.log(Color.Blue); // 4

如何定義是常數項，可參考官網。

像是二元運算子 <<、|、& 等都歸為常數項：

1
2
3
4
5
6
7
8
9


enum FileAccess {
 // constant members
 None,
 Read = 1 << 1,
 Write = 1 << 2,
 ReadWrite = Read | Write,
 // computed member
 G = "123".length,
}

Const Enums 常數列舉

可以使用 const enum 定義的列舉型別：

1
2
3
4
5
6
7
8


const enum Directions {
 Up,
 Down,
 Left,
 Right
}

let directions = [Directions.Up, Directions.Down, Directions.Left, Directions.Right];

常數列舉與普通列舉的區別是，它會在編譯階段被刪除，並且不能包含 computed member (計算成員)，只能是常數項 (constant member)。

編譯後：

1

var directions = [0 /* Up */, 1 /* Down */, 2 /* Left */, 3 /* Right */];

Ambient Enums 外部列舉

外部列舉 (Ambient Enums) 是使用 declare enum 定義的列舉型別：

1
2
3
4
5
6
7
8


declare enum Directions {
 Up,
 Down,
 Left,
 Right
}

let directions = [Directions.Up, Directions.Down, Directions.Left, Directions.Right];

declare 定義的型別只會用於編譯時的檢查，編譯結果中會被刪除。

編譯後：

1

var directions = [Directions.Up, Directions.Down, Directions.Left, Directions.Right];

【Node.js】用 Typescript 與 Express 建立一個 server

Tue, 21 Feb 2023 00:00:00 +0000

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

最近前端離不開 typescript 後，我將原本用 javascript 撰寫的 mock server 改用 typescript 來撰寫；本篇就來記錄一下該如何使用 typescript 建立 node.js 的 Express！

使用 typescript 的好處

typescript 是為了彌補 javascript 不足的地方而誕生的語言，最主要的差別就在於宣告變數或是執行函數時需要指定 type ，不過這篇的重點在於在 node.js 中使用 typescript 建立 Express，所以就不描述太多 typescript 的特性了。

提供許多 OO pattern 的方法，如介面、繼承與抽象類別
強型別，能夠在編譯過程中先行找到一些錯誤
能夠編譯成不同版本的 JS
有 Declaration files 能夠使用 JS Library，因此不太需要擔心套件相容問題，像是 express 有 @type/express

建立 typescript 環境

進入初始化專案或現有專案的目錄

1
2
3
4


cd ~/project/node-express-project

# 初始化專案
# npm init

安裝 typescript 與 express

1
2


npm install --save-dev typescript @types/express @types/node
npm install --save express

設定 typescript

安裝 typescript 時，也會同時安裝將 typescript 編譯成 javascript 的編譯器 - tsc。

初始化 tsc

1

tsc --init

tsc --init 後會產生 tsconfig.json，當 typescript 透過 tsc 編譯成 javascript 時，就會遵循該檔案的設定進行編譯。

可能遇到的錯誤

tsc command not found

這個 error message ，請先在 global 安裝 typescript。

1

npm install -g typescript

若仍出現 “tsc command not found”，請在終端機輸入：

1

export PATH=”$PATH:/Users/{user name}/.npm-global/lib/node_modules/typescript/bin/”

再輸入 tsc -v ，確認 tsc 的版本即可。

tsconfig.json

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


{
 "compilerOptions": {
 "target": "es5", // 選擇要編譯成哪種版本的 javascript
 "module": "commonjs",
 "strict": true, // 嚴格模式，啟用後需要指定函數參數的 type
 "esModuleInterop": true,
 "skipLibCheck": true,
 "forceConsistentCasingInFileNames": true,
 "outDir": "dist" // 將編譯過後的 js 檔放到 dist 資料夾中
 }
}

官網有 tsconfig.json 所有屬性的說明，請參考官網。

node.js 的設定

安裝完 typescript 環境後，接著我們來設定 node.js 的部分。

1. 新增入口檔案

1
2
3


mkdir src

touch src/app.ts # 入口檔案

src/app.ts

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


import express from 'express';
​
const app = express();
const port = 3000;
app.get('/', (req, res) => {
 res.send('The server is working!');
});
app.listen(port, () => {
 if (port === 3000) {
 console.log('true')
 }
 console.log(`server is listening on ${port} !!!`);
});

2. 安裝 nodemon 與 ts-node

nodemon：用於在每次儲存檔案後自動重啟 node，看到即時的修正。
ts-node：可以當作 node.js + typescript，用於直接在 node.js 執行 typescript 檔案。

在專案資料夾內安裝：

1

npm install --save-dev nodemon ts-node

【推薦】也可以直接安裝於全域環境：

1

npm install -g nodemon ts-node

3. 調整 package.json 的 scripts

package.json

1
2
3
4
5


"scripts": {
 "start": "nodemon src/app.ts",
 "build": "tsc --project ./",
 "test": "echo \"Error: no test specified\" && exit 1"
}

4. 執行 npm start

1

npm run start

start 後，nodemon 會監聽檔案是否有儲存的動作，並用 ts-node 來重啟。

npm run build 後則會出現一個 dist 資料夾來存放編譯過後的 js 檔。

BONUS：使用自定義的 tsconfig.json

補充一下，若當前專案包含前後端，而前端也使用 typescript 撰寫時，已經有一隻前端部分的 tsconfig.json，此時若需拆分 Express 的 tsconfig.json，可以透過 nodemon 的參數 --config {express tsconfig.json 檔案位置} 來調整。

先複製一份 tsconfig.json 到 Express src 資料夾內

1
2


# 先複製一份 tsconfig.json
copy tsconfig.json src/tsconfig.json

調整 start 的 scripts

package.json

1
2
3
4
5


"scripts": {
 "start": "nodemon src/app.ts --config src/tsconfig.json",
 "build": "tsc --project ./ --config src/tsconfig.json",
 "test": "echo \"Error: no test specified\" && exit 1"
}

使用 http

這邊講解用 http module 寫 node.js，如需直接使用 express 可以直接跳到使用 Express。

建立完 typescript 的環境後，引入 node.js 的核心套件之一：http module。 http module 能讓你建立一個 http server，當你的 code 在執行的時候，可以隨時監聽網路上發送到你 url 的所有 request，並將你寫的程式邏輯 response 回去。

載入 http module 其實跟 javascript 的寫法差不多，只是在 request 和 response 加上對應的型別： IncomingMessage、ServerResponse。

PS：在 node 無法直接使用 import，得透過 Babel 轉譯，可以在 tsconfig.json 中設定 module。

src/tsconfig.json

 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


{
 "compilerOptions": {
 "target": "esnext",
 "module": "CommonJS", // 重點是這行
 "useDefineForClassFields": true,
 "strict": true,
 "jsx": "preserve",
 "outDir": "./dist",
 "importHelpers": true,
 "moduleResolution": "node",
 "experimentalDecorators": true,
 "allowJs": true,
 "skipLibCheck": true,
 "esModuleInterop": true,
 "allowSyntheticDefaultImports": true,
 "sourceMap": true,
 "isolatedModules": false,
 "resolveJsonModule": true,
 "baseUrl": ".",
 "types": ["node"],
 "paths": {
 "@/*": ["src/*"]
 },
 "lib": ["esnext", "dom", "dom.iterable", "scripthost"],
 "noFallthroughCasesInSwitch": true,
 "forceConsistentCasingInFileNames": true,
 "typeRoots": ["node_modules/@types", "src/types", "src"],
 "suppressImplicitAnyIndexErrors": true
 },
 "include": ["**/*.ts", "**/*.d.ts"]
}

src/app.ts

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


import { createServer, IncomingMessage, ServerResponse } from 'http';

const port = 5000;

const server = createServer((request: IncomingMessage, response: ServerResponse) => {
 response.on('error', (err) => {
 console.error(err);
 });
 response.writeHead(200, {"Content-Type": "text/plain"});
 response.end('Hello world!');
});

server.listen(port);
console.log(`server is running on http://localhost:${port}`)

如此一來每當有任何 client 對 http://localhost:5000 這個 url 發送 request 時，我們的 server 都會回應 “Hello world!” 給該 client。

取得 request 中的資料

取得 request body

大部分的時候，如果我們需要傳資料到 server，會發送 POST request ，並且將資料存在 body 當中，要在 node.js 取得 request 中的 body data 方法如下：

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


let body = [];
request
 .on('error', (err) => {
 console.error(err);
 })
 .on('data', (chunk) => {
 body.push(chunk);
 })
 .on('end', () => {
 body = Buffer.concat(body).toString();
 console.log(body);
 })

如果直接將 chunk console.log 出來會發現是一段看不懂的資料：<Buffer 7b 0d 0a 20 20 20 20 22 74 65 73 74 22 3a 20 22 35 22 0d 0a 7d>，這是因為 http request 在發送給 server 的時候是按照順序一個 byte、一個 byte 以資料流的方式發送的，因此需要用 Buffer.toString() 轉換回原本的資料。

當我使用 POST method 發送 request 時，我的 server 端就會印出 request 中 body 的資料。

取得 request header

直接用 request.headers 取得 request 中的基本資料：

1
2
3
4
5
6
7


request
 .on('error', (err) => {
 console.error(err);
 })
 .on('end', () => {
 console.log(request.headers);
 })

取得 request authorization

authorization 是我們習慣放置 token 的欄位，雖然在 postman 中是獨立的一欄，但事實上是存在 request 的 headers 裡的。

1
2
3
4
5
6
7
8


request
 .on('error', (err) => {
 console.error(err);
 })
 .on('end', () => {
 console.log(request.headers);
 console.log(request.headers.authorization);
 })

完整程式碼

src/app.ts

 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


import { createServer, IncomingMessage, ServerResponse } from 'http';

const port = 5000;

const server = createServer((request: IncomingMessage, response: ServerResponse) => {
 const { headers, method, url } = request;
 let body:any = [];
 request
 .on('error', (err) => {
 console.error(err);
 })
 .on('data', (chunk) => {
 body.push(chunk);
 })
 .on('end', () => {
 body = Buffer.concat(body).toString();
 console.log(body);
 console.log(request.headers);
 console.log(request.headers.authorization);
 })
 response.on('error', (err) => {
 console.error(err);
 });
 response.writeHead(200, {"Content-Type": "text/plain"});
 response.end('Hello world!');
});

server.listen(port);
console.log(`server is running on http://localhost:${port}`)

使用 Express

接著使用 Express 來改寫一下。

src/app.ts

 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


import express, { Express, Request, Response } from 'express';

const port = 5000;

const app: Express = express();

app.get('/', (request: Request, response: Response) => {
 response.type('text/plain');
 response.send('Homepage');
})

app.get('/articles', (request: Request, response: Response) => {
 response.type('text/plain');
 response.send('All articles are here!');
})

app.get('/about-me', (request: Request, response: Response) => {
 response.type('text/plain');
 response.send('My name is Jimmy.');
})

app.use((request: Request, response: Response) => {
 response.type('text/plain');
 response.status(404)
 response.send('Page is not found.');
})

app.listen(port, () => {
 console.log(`server is running on http://localhost:${port}`)}
);

加入 Route 與 Controller

當專案越長越大後，將所有 routes 和邏輯都寫在 app.ts 是個很難維護的做法，因此大多數的專案都會將 routes 和 controllers 獨立出來，把商業邏輯寫在 controllers 中。

Controller：請求經過 router 分配過後，會交由 controller 負責處理商業邏輯，並回傳對應的 response。
Route：我們要將使用者的請求，依照其進入的 Url 分配給不同的 Controller。

Controller

建立 controllers。

src/controllers/api-controllers.ts

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


import { Request, Response, NextFunction } from 'express';

export class ApiControllers {
 getHomePage(request: Request, response: Response, next: NextFunction) {
 response.type('text/plain');
 response.send('Homepage');
 }

 getAboutPage(request: Request, response: Response, next: NextFunction) {
 response.type('text/plain');
 response.send('My name is Jimmy.');
 }
}

Route

建立 routes。

src/routes/api-routes.ts

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


import express, { Router, Request, Response, NextFunction } from 'express';
import { ApiControllers } from '../controllers/api-controllers';

const apiControllers = new ApiControllers;

export class ApiRouter {
 router: Router;
 constructor() {
 this.router = express.Router();
 this.initializeRoutes();
 }

 initializeRoutes() {
 this.router.get('/', apiControllers.getHomePage);
 this.router.get('/articles', apiControllers.getArticlesPage);
 this.router.get('/about-me', apiControllers.getAboutPage)
 }
}

調整 src/app.ts

src/app.ts

 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


import express, { Express, Request, Response, NextFunction } from 'express';
import { ApiRouter } from './routes/api-routes';

const port = 5000;

const app: Express = express();
const apiRouter = new ApiRouter;

app.use((request: Request, response: Response, next: NextFunction) => {
 response.setHeader("Access-Control-Allow-Origin", "*");
 response.setHeader(
 "Access-Control-Allow-Headers",
 "Origin, X-Requested-With, Content-Type, Accept, Authorization"
 );
 response.setHeader("Access-Control-Allow-Methods", "GET, POST, PATCH, DELETE");

 next();
});

app.use('', apiRouter.router)

app.use((request: Request, response: Response) => {
 response.type('text/plain');
 response.status(404)
 response.send('Page is not found.');
})

app.listen(port, () => {
 console.log(`server is running on http://localhost:${port}`)}
);

檔案結構：

將 routes 拆分成多個檔案

先建立一個 route 的 abstract class

src/routes/route.ts

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


import { Router } from "express";

abstract class Route {
 protected router = Router();
 protected abstract setRoutes(): void;

 public getRouter() {
 return this.router;
 }
}

export default Route;

新增 AuthRoute 與 AuthController

src/controllers/AuthController.ts

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


import { Request, Response } from "express";

class AuthController {
 echo(request: Request, response: Response, next: NextFunction) {
 response.type('text/plain');
 response.send('echo');
 }
}

export default AuthController;

src/routes/auth.route.ts

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


import AuthController from "../controllers/AuthController"
import Route from "./route";

class AuthRoute extends Route{
 private authController = new AuthController();

 constructor() {
 super();
 this.setRoutes();
 }

 protected setRoutes() {
 this.router.get('/login', this.authController.echo);
 }
}

export default AuthRoute;

新增 ArticleRoute 與 ArticleController

src/controllers/ArticalController.ts

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


import { Request, Response } from "express";

class ArticleController {
 getArticlesPage(request: Request, response: Response, next: NextFunction) {
 response.type('text/plain');
 response.send('All articles are here!');
 }
}

export default ArticleController;

src/routes/article.route.ts

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


import ArticalController from "../controllers/ArticalController"
import Route from "./route";

class ArticleRoute extends Route{
 private articalController = new ArticalController();

 constructor() {
 super();
 this.setRoutes();
 }

 protected setRoutes() {
 this.router.get('/articles', this.articalController.getArticlesPage);
 }
}

export default ArticleRoute;

建立 router 並加載各個檔案的 route

移除原先的 src/routes/api-routes.ts，統一改成使用 src/routes/router.ts。

src/routes/router.ts

1
2
3
4
5
6
7
8


import Route from "./route";
import AuthRoute from "./auth.route";
import ArticleRoute from "./article.route";

export const router: Array<Route> = [
 new AuthRoute(),
 new ArticleRoute()
]

改寫 src/app.ts

src/app.ts

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


import express from 'express';
import { router } from "./routes/router";

const app: express.Application = express();

app.use(express.json());
app.use(express.urlencoded({ extended: false }));

// load router
for (const route of router) {
 app.use(route.getRouter());
}

module.exports = app;

前綴 Prefix

同一個 route 檔案常常會有相同的 prefix url，例如說 auth route 可能會有：

POST auth/login
POST auth/logout
POST auth/forgetPassword
…

我們在 Route class 中加入一個新的資料成員 prefix，用來設定每個 route 的前綴網址：

src/routes/route.ts

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




import { Router } from "express";

abstract class Route {
 protected router = Router();
 protected abstract setRoutes(): void;
 protected prefix: string = '/';

 public getRouter() {
 return this.router;
 }

 public getPrefix() {
 return this.prefix;
 }
}

export default Route;

在各個 Route 的建構子中修改它：

src/routes/auth.route.ts

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


import AuthController from "../controllers/AuthController"
import Route from "./route";

class AuthRoute extends Route{
 private authController = new AuthController();

 constructor() {
 super();
 this.prefix = '/auth';
 this.setRoutes();
 }

 protected setRoutes() {
 this.router.get('/login', this.authController.echo);
 }
}

export default AuthRoute;

src/routes/article.route.ts

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


import ArticalController from "../controllers/ArticalController"
import Route from "./route";

class ArticleRoute extends Route{
 private articalController = new ArticalController();

 constructor() {
 super();
 this.prefix = '/articles';
 this.setRoutes();
 }

 protected setRoutes() {
 this.router.get('/articles', this.articalController.getArticlesPage);
 }
}

export default ArticleRoute;

最後，在 app.ts 中，載入 router 時加入 prefix 的設定：

src/app.ts

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


import express from 'express';
import { router } from "./routes/router";

const app: express.Application = express();

app.use(express.json());
app.use(express.urlencoded({ extended: false }));

// load router
for (const route of router) {
 app.use(route.getPrefix(), route.getRouter());
}

module.exports = app;

如此一來，原本是 /login 的 url，在加上 prefix 之後，就會變成 /auth/login，而其他在 AuthRoute 定義的 url 也都會變成 /auth/*、在 ArticleRoute 定義的 url 也都會變成 /articles/*。

Middleware

在 Express 中，有三種可以嵌套 middleware 的方式：

應用到單一 url
應用到單一 route 檔案
全域使用，每個請求都會經過這個 middleware

我們先寫一個簡單的 middleware，他只看請求的 header 裡面有沒有 Authorization，若沒有的話會回傳 status code 401：

src/middleware/AuthMiddleware.ts

1
2
3
4
5
6
7
8
9


import { Request, Response, NextFunction } from "express";

export function AuthMiddleware(req: Request, res: Response, next: NextFunction) {
 if (!req.header('Authorization')) {
 return res.status(401).send('unauthorized');
 }

 next();
}

套用在單一 url

若你想套用在單一 url，只需要放在 router.METHOD 的第二個參數即可：

src/routes/auth.route.ts

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


import AuthController from "../controllers/AuthController"
import AuthMiddleware from "../middleware/AuthMiddleware"
import Route from "./route";

class AuthRoute extends Route{
 private authController = new AuthController();

 constructor() {
 super();
 this.prefix = '/auth';
 this.setRoutes();
 }

 protected setRoutes() {
 this.router.get('/login', AuthMiddleware, this.authController.echo);
 }
}

export default AuthRoute;

套用在單一 route 檔案

套用在單一 route 檔案，則在該 route class 的建構子加入 (必須在 setRoutes() 之前)：

src/routes/auth.route.ts

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


import AuthController from "../controllers/AuthController"
import AuthMiddleware from "../middleware/AuthMiddleware"
import Route from "./route";

class AuthRoute extends Route{
 private authController = new AuthController();

 constructor() {
 super();
 this.prefix = '/auth';
 this.router.use(AuthMiddleware); // 必須在 setRoutes() 之前
 this.setRoutes();
 }

 protected setRoutes() {
 this.router.get('/login', this.authController.echo);
 }
}

export default AuthRoute;

全域使用

全域使用的話，就在 app.ts 裡面加上：

src/app.ts

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


import express from 'express';
import { router } from "./routes/router";
import AuthMiddleware from "../middleware/AuthMiddleware"

const app: express.Application = express();

app.use(express.json());
app.use(express.urlencoded({ extended: false }));
app.use(AuthMiddleware);

// load router
for (const route of router) {
 app.use(route.getPrefix(), route.getRouter());
}

module.exports = app;

Validator

若要驗證 Request body 或 query string 的內容，建議可以使用 express-validator 套件，裡面有各式各樣的驗證用 middleware 可供使用。

1

npm install express-validator @types/express-validator

假設我們的登入表單需要有 username 和 password 兩個欄位，且最少要有四個字。

我們能夠將這個驗證寫成 request 檔案：

src/requests/AuthRequest.ts

1
2
3
4
5
6
7
8


import { check } from "express-validator";
import { showApiError } from "../middleware/AuthMiddleware";

export const loginRequest = [
 check('username').exists().isLength({min: 4}),
 check('password').exists().isLength({min: 4}),
 showApiError
];

改寫 AuthMiddleware ：

src/middleware/AuthMiddleware.ts

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


import { Request, Response, NextFunction } from "express";
import { validationResult } from "express-validator";

export function showApiError(req: Request, res: Response, next: NextFunction) {
 const errors = validationResult(req);
 if (!errors.isEmpty()) {
 return res.status(400).json({ errors: errors.array() });
 }

 next();
}

showApiError 是為了在有 input 錯誤發生時，能夠回傳對應的錯誤訊息而使用的 middleware，如果沒有它的話，validator 不會回傳錯誤訊息。

接著我們在 auth route class 裡面載入這個 request：

src/routes/auth.route.ts

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


import AuthController from "../controllers/AuthController";
import Route from "./route";
import { loginRequest } from "../requests/AuthRequest";

class AuthRoute extends Route{
 private authController = new AuthController();

 constructor() {
 super();
 this.prefix = '/auth';
 this.setRoutes();
 }

 protected setRoutes() {
 this.router.get('/login', loginRequest, this.authController.echo);
 }
}

export default AuthRoute;

如此一來 POST /login 的請求就會驗證 request body，當我的 username 輸入太短時，會得到以下錯誤：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


{
 "errors": [
 {
 "value": "123",
 "msg": "Invalid value",
 "param": "username",
 "location": "body"
 }
 ]
}

因為 request 其實就是 middleware 的陣列，因此若要嵌套其他 middleware 時，使用 Array merge 即可。

【Nuxt3】實戰練習 - 實作部落格

Mon, 16 Jan 2023 00:00:00 +0000

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

大家經過【Nuxt3】開箱即用的 Nuxt3 玩轉筆記這篇文章，應該對於 Nuxt 3 有初步的理解，接下來我們將進入實戰部分，我將會以 Nuxt 3 來實作部落格網站，讓已經註冊的使用者可以在網站上發布文章，實作這個網站的程式碼可能不會講解得非常仔細，但一些實務開發上會需要注意的細節我會把個人經驗做一個紀錄，大家可以再參考看看，文末也都會附上完整的範例程式。接下來，讓我們開始吧！

資料庫與會員系統

資料庫 (Database)

這篇文章實作的部落格，會把會員與文章等資料儲存於伺服器的資料庫之中，大家可以選擇自己習慣或合適的資料庫來做儲存。為了方便及後續的展示，我最終決定使用 Prisma 搭配本地的 SQLite 來當作儲存體，讓大家測試時不用再煩惱怎麼架設資料庫，可以快速的執行範例程式碼。

你可以在自己的 Nuxt 專案或從新專案開始進行，若你已經有自己的資料庫，也可以直接跳過此段介紹後續實作自己的後端 API 來接續我們的實作系列。

安裝 Prisma

Prisma 操作起來很像 ORM (Object-Relational Mapping)，但實際上依據官網的說明，其實不大依樣，Prisma 透過撰寫並根據 Schema 來建立或操作資料庫，在進行 CRUD 的操作時，都是透過 Prisma Client 進行，這也是最方便的地方，此外也支援多種資料庫的來源，只要操作 Model 就可以映射到資料庫的資料，不再需要寫 SQL，在一些情境之下是非常方便的。

首先，使用 NPM 安裝 prisma 與 @prisma/client

1
2
3


npm install -D prisma @prisma/client
# or
# yarn add -D prisma @prisma/client

打開終端機 (Terminal) 於 Nuxt 專案目錄中，使用下列指令，初始化一個 Prisma 的 Schema。

1

npx prisma ini

初始化完成後，會建立一個 schema.prisma 檔案。

./prisma/schema.prisma 檔案內容如下，這裡就是定義我們資料庫位置與 Schema 的地方，之後我們就可以透過 Prisma 的 Client 使用 ORM 來操作資料庫。

prisma/schema.prisma

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// This is your Prisma schema file,
// learn more about it in the docs: https://pris.ly/d/prisma-schema

generator client {
 provider = "prisma-client-js"
}

datasource db {
 provider = "postgresql"
 url = env("DATABASE_URL")
}

我們調整 ./prisma/schema.prisma 檔案內容，將 datasource 替換為 SQLite 並儲存在本地的 ./dev.db。

1
2
3
4


datasource db {
 provider = "sqlite"
 url = "file:./dev.db"
}

你也可以將 provider 替換為 PostgreSQL 或 MySQL 等，可以參考這裡，但要注意可能後面定義的 Schema 語法會略微不同。

接下來我們定義一個 User 的資料表，在 schema.prisma 撰寫如下：

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


model User {
 id String @id @default(uuid())
 providerName String?
 providerUserId String?
 nickname String @default("User")
 email String @unique
 password String?
 avatar String?
 emailVerified Boolean @default(false)
 createdAt DateTime @default(now())
 updatedAt DateTime @updatedAt
}

這張 User 資料表，將用作於部落格的登入使用者做使用，也可以視為是會員系統使用的資料表，大家也可以依據需求來擴增欄位，以下稍微講述一下各個欄位將作為何用。

id: 預設為 UUID，為使用者的唯一識別。
providerName: 作為第三方登入的供應商記錄使用，例如該名使用者使用 Google OAuth 註冊登入，我會在欄位就會填上 google。如果為空值 (null) 表示使用者用電子信箱註冊登入。
providerUserId: 與 providerName 搭配使用，第三方供應商通常也會有一組專屬於使用者的 Id，以此我們就可以來比對登入的是哪位使用者。如果為空值 (null) 表示使用者用電子信箱註冊登入。
nickname: 使用者暱稱，預設值為字串 User。
email: 使用者登入的電子信箱，這裡我將欄位設定為 @unique 表示，電子信箱是系統中唯一。
password:使用者密碼的雜湊值，如果使用第三方註冊登入，則該欄位為空值 (null)。
avatar: 使用者的頭像，存放圖片網址。
emailVerified: 布林值，預設為 false，表示使用者的電子信箱是尚未通過驗證。
createdAt: 使用者建立時間，預設為插入該筆資料的時間。
updatedAt: 使用者更新個人資料的時間，預設為更新該筆資料的時間。

./prisma/schema.prisma 檔案內容看起來如下：

prisma/schema.prisma

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


// This is your Prisma schema file,
// learn more about it in the docs: https://pris.ly/d/prisma-schema

generator client {
 provider = "prisma-client-js"
}

datasource db {
 provider = "sqlite"
 url = "file:./dev.db"
}

model User {
 id String @id @default(uuid())
 providerName String?
 providerUserId String?
 nickname String @default("User")
 email String @unique
 password String?
 avatar String?
 emailVerified Boolean @default(false)
 createdAt DateTime @default(now())
 updatedAt DateTime @updatedAt
}

當我們調整好 schema 後，就可以執行下列指令，來初始化資料庫，Prisma 會依照 schema.prism 來幫我們建立對應的資料表。

1

npx prisma db push

初始化完畢後，你可以登入你的資料庫查看是否建立成功，也可使用 Prisma 提供的 Prisma Studio 來快速的檢視與操作資料庫內的資料。Prisma Studio 已經內建在 prisma 套件中，執行以下指令後，就會啟動一個 Web 服務，如 http://localhost:5555，我們就可以在網頁中查看資料庫內的資料囉！

1

npx prisma studio

可以在 Prisma Studio 看到我們建立的 User 資料表，也將是我們稍後使用 Prisma 操作 ORM 所對應的 User Model。

最後記得執行下列指令來產生 Prisma Client，這樣我們就可以在 Nuxt 3 中使用 Prisma Client 操作資料庫囉！

1

npx prisma generate

Nuxt 3 操作 Prisma Client 建立一個使用者至資料庫

我們接下來就能使用如下程式碼建立 Prisma Client，後續可以用來來操作 Model，更多的 Prisma Client API 可以參考官方文件。

1
2
3


import { PrismaClient } from '@prisma/client'

const prismaClient = new PrismaClient()

我們建立一隻 Server API，新增 ./server/api/test-create-user.get.js，用來測試收到請求後建立一個測試使用者，詳細的程式碼如下：

server/api/test-create-user.get.js

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


import { PrismaClient } from '@prisma/client'

const prismaClient = new PrismaClient()

export default defineEventHandler(() => {
 const user = prismaClient.user.create({
 data: {
 providerName: null,
 providerUserId: null,
 nickname: 'Ryan',
 email: 'ryanchien8125@gmail.com',
 password: '這裡要放密碼的雜湊值',
 avatar: '',
 emailVerified: true
 }
 })

 return user
})

當我們送出 /api/test-create-user 後，後端會使用 Prisma Client 操作 User Model，我們就能使用 ORM 來建立出使用者的資料庫記錄。

Nuxt 3 使用者註冊帳號

我們將【Nuxt3】開箱即用的 Nuxt3 玩轉筆記這篇文章，所串接的 Google OAuth 及 Cookie 做一個結合，讓使用者透過 Google Auth 登入後可以自動的註冊建立使用者或登入產生 Access Token。

./server/api/auth/google.post.js 程式碼如下：

server/api/auth/google.post.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
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86


import { OAuth2Client } from 'google-auth-library'
import jwt from 'jsonwebtoken'
import db from '@/server/db'

const runtimeConfig = useRuntimeConfig()

export default defineEventHandler(async (event) => {
 const body = await readBody(event)
 const oauth2Client = new OAuth2Client()
 oauth2Client.setCredentials({ access_token: body.accessToken })

 const userInfo = await oauth2Client
 .request({
 url: 'https://www.googleapis.com/oauth2/v3/userinfo'
 })
 .then((response) => response.data)
 .catch(() => null)

 oauth2Client.revokeCredentials()

 if (!userInfo) {
 throw createError({
 statusCode: 400,
 statusMessage: 'Invalid token'
 })
 }

 let userRecord = await db.user.getUserByEmail({
 email: userInfo.email
 })

 if (userRecord) {
 if (
 (userRecord.providerName === 'google' && userRecord.providerUserId === userInfo.sub) === false
 ) {
 throw createError({
 statusCode: 400,
 statusMessage: 'This email address does not apply to this login method'
 })
 }
 } else {
 userRecord = await db.user.createUser({
 providerName: 'google',
 providerUserId: userInfo.sub,
 nickname: userInfo.name,
 email: userInfo.email,
 password: null,
 avatar: userInfo.picture,
 emailVerified: userInfo.email_verified
 })
 }

 const jwtTokenPayload = {
 id: userRecord.id
 }

 const maxAge = 60 * 60 * 24 * 7
 const expires = Math.floor(Date.now() / 1000) + maxAge

 const jwtToken = jwt.sign(
 {
 exp: expires,
 data: jwtTokenPayload
 },
 runtimeConfig.jwtSignSecret
 )

 setCookie(event, 'access_token', jwtToken, {
 httpOnly: true,
 maxAge,
 expires: new Date(expires * 1000),
 secure: process.env.NODE_ENV === 'production',
 path: '/'
 })

 return {
 id: userRecord.id,
 provider: {
 name: userRecord.providerName,
 userId: userRecord.providerUserId
 },
 nickname: userRecord.nickname,
 avatar: userRecord.avatar,
 email: userRecord.email
 }
})

程式碼內容稍微有一點多，但講解一下流整與概念：

當前端 Google OAuth 登入成功後，將回傳的 Google access_token 傳送至這隻 API，並使用 Google API 取得使用者資訊。
db.user.getUserByEmail 這個是我封裝的方法，裡面對應著 Prisma 的 ORM 操作，如果你想也可以在這邊替換你的資料庫操作邏輯，主要這個方法，就是依照使用者的 Email 回傳資料庫內是否存在一筆符合的使用者記錄。
如果存在，我會判斷 provider 是否符合 Google 的使用者資訊，否則判斷為應該是用電子信箱註冊的使用者。
如果不存在，則建立一個新的使用者至資料庫內，建立時不需要傳入 id 資料庫因為設定為自動產生 UUID。
最後就是產生使用者的 JWT 並設定在 cookie 之中。

另外，我也實作了使用電子信箱直接註冊的方式，./server/api/auth/register.post.js 程式碼如下：

server/api/auth/register.post.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
33


import bcrypt from 'bcrypt'
import db from '@/server/db'

export default defineEventHandler(async (event) => {
 const body = await readBody(event)

 let userRecord = await db.user.getUserByEmail({
 email: body.email
 })

 if (userRecord) {
 throw createError({
 statusCode: 400,
 statusMessage: 'A user with that email address already exists'
 })
 }

 userRecord = await db.user.createUser({
 providerName: null,
 providerUserId: null,
 nickname: body.nickname,
 email: body.email,
 password: bcrypt.hashSync(body.password, 10),
 avatar: null,
 emailVerified: false
 })

 return {
 id: userRecord.id,
 nickname: userRecord.nickname,
 email: userRecord.email
 }
})

使用電子信箱與密碼註冊的流程很簡單，就是判斷是否存在相同信箱的使用者，不存在的話就為它建立一筆紀錄。

這邊要注意的是，會員系統或牽扯到帳號密碼相關的，請一律使用雜湊演算法，例如 BCrypt 或 Argon2，為使用者的密碼做 Hash，不要再存明碼在資料庫之中囉，以免發生資安事件時，造成不可挽回的悲劇。

順便也實作一下使用電子信箱與密碼登入的 API，./server/api/auth/login.post.js 程式碼如下：

server/api/auth/login.post.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
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61


import bcrypt from 'bcrypt'
import jwt from 'jsonwebtoken'
import db from '@/server/db'

const runtimeConfig = useRuntimeConfig()

export default defineEventHandler(async (event) => {
 const body = await readBody(event)

 const userRecord = await db.user.getUserByEmail({
 email: body.email
 })

 if (!userRecord) {
 throw createError({
 statusCode: 400,
 statusMessage: 'Email or password is incorrect'
 })
 }

 if ((await bcrypt.compare(body.password, userRecord.password)) !== true) {
 throw createError({
 statusCode: 400,
 statusMessage: 'Email or password is incorrect'
 })
 }

 const jwtTokenPayload = {
 id: userRecord.id
 }

 const maxAge = 60 * 60 * 24 * 7
 const expires = Math.floor(Date.now() / 1000) + maxAge

 const jwtToken = jwt.sign(
 {
 exp: expires,
 data: jwtTokenPayload
 },
 runtimeConfig.jwtSignSecret
 )

 setCookie(event, 'access_token', jwtToken, {
 httpOnly: true,
 maxAge,
 expires: new Date(expires * 1000),
 secure: process.env.NODE_ENV === 'production',
 path: '/'
 })

 return {
 id: userRecord.id,
 provider: {
 name: userRecord.providerName,
 userId: userRecord.providerUserId
 },
 nickname: userRecord.nickname,
 avatar: userRecord.avatar,
 email: userRecord.email
 }
})

使用 Google OAuth 登入

使用電子信箱與密碼登入

結合 Pinia 儲存使用者資料

我們可以結合 Pinia 來將使用者的資料持久話儲存在 Local Storage 之中，這樣就可以在前端儲存使用者登入的狀態，例如導覽列的頭像、信箱，就可以從 Store 中拿出來囉。

建立 ./server/profile.get.js 檔案，用來取得使用者資料：

server/profile.get.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
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49


import jwt from 'jsonwebtoken'
import db from '@/server/db'

const runtimeConfig = useRuntimeConfig()

export default defineEventHandler(async (event) => {
 const jwtToken = getCookie(event, 'access_token')

 let userInfo = null

 try {
 const { data } = jwt.verify(jwtToken, runtimeConfig.jwtSignSecret)
 userInfo = data
 } catch (e) {
 throw createError({
 statusCode: 401,
 statusMessage: 'Unauthorized'
 })
 }

 if (!userInfo?.id) {
 throw createError({
 statusCode: 401,
 statusMessage: 'Unauthorized'
 })
 }

 const userRecord = await db.user.getUserById({
 id: userInfo.id
 })

 if (!userRecord) {
 throw createError({
 statusCode: 400,
 statusMessage: 'Could not find user.'
 })
 }

 return {
 id: userRecord.id,
 provider: {
 name: userRecord.providerName,
 userId: userRecord.providerUserId
 },
 nickname: userRecord.nickname,
 avatar: userRecord.avatar,
 email: userRecord.email
 }
})

新增一個 user 的 store，./stores/user.js 內容如下：

stores/user.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
33
34
35


import { defineStore } from 'pinia'

export const useUserStore = defineStore('user', {
 state: () => ({
 profile: {
 id: null,
 provider: {
 name: null,
 userId: null
 },
 nickname: null,
 avatar: null,
 email: null
 }
 }),
 actions: {
 async refreshUserProfile() {
 const { data, error } = await useFetch('/api/user/profile', { initialCache: false })
 if (data.value) {
 this.profile = data.value
 } else {
 return error.value?.data?.message ?? '未知錯誤'
 }
 }
 },
 persist: {
 enabled: true,
 strategies: [
 {
 key: 'user',
 storage: process.client ? localStorage : null
 }
 ]
 }
})

我們就可以直接使用 refreshUserProfile() 來發送請求至 /api/user/profile 取得最新的使用者資料來更新 store。

1
2
3
4


import { useUserStore } from '@/stores/user'
const userStore = useUserStore()

userStore.refreshUserProfile()

使用伺服器中間件來驗證 JWT

我們的會員系統在登入後，會產生一組 JWT 放置於 cookie 之中，在後端 API 使用時都要在呼叫 getCookie() 來解析 cookie，所以我們可以將驗證 JWT 的流程，放置在伺服器中間件 (middleware) 之中，後端收到的每個請求就會經過這個中間件，只要有夾帶 access_token 的 cookie 就會進行驗證解析出 JWT 所含的 payload id，即為使用者的 ID。

建立 ./server/middleware/auth.js 檔案，內容如下：

server/middleware/auth.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


import jwt from 'jsonwebtoken'

const runtimeConfig = useRuntimeConfig()

export default defineEventHandler((event) => {
 const jwtToken = getCookie(event, 'access_token')

 if (!jwtToken) {
 return
 }

 let userInfo = null

 try {
 const { data } = jwt.verify(jwtToken, runtimeConfig.jwtSignSecret)

 userInfo = data
 if (userInfo?.id) {
 event.context.auth = {
 user: {
 id: userInfo.id
 }
 }
 }
 } catch (e) {
 console.error('Invalid token')
 }
})

伺服器的中間件只要定義在 ./server/middleware 目錄下就會自動被載入，之後在每個 Server API 收到請求，中間件只要有成功驗證並解析 JWT，就會在 event.context.auth 添加使用者資訊，之後在 Server API 的處理函數中，就可以以下列程式碼進行使用。

1
2
3


export default defineEventHandler(async (event) => {
 const user = event.context?.auth?.user
})

調整後的 ./server/profile.get.js 檔案，就會乾淨許多囉！

server/profile.get.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
33
34


import db from '@/server/db'

export default defineEventHandler(async (event) => {
 const user = event.context?.auth?.user

 if (!user?.id) {
 throw createError({
 statusCode: 401,
 statusMessage: 'Unauthorized'
 })
 }

 const userRecord = await db.user.getUserById({
 id: user.id
 })

 if (!userRecord) {
 throw createError({
 statusCode: 400,
 statusMessage: 'Could not find user.'
 })
 }

 return {
 id: userRecord.id,
 provider: {
 name: userRecord.providerName,
 userId: userRecord.providerUserId
 },
 nickname: userRecord.nickname,
 avatar: userRecord.avatar,
 email: userRecord.email
 }
})

為了實作部落格，我們使用 Prisma 快速的建立資料庫環境，也方便大家可以下載範例程式碼，就可以在自己的電腦上運作 SQLite。也結合 Pinia 來將使用者的資料進行持久化的儲存，這樣我們就可以實作出如判斷使用者是否登入或是建立導覽列上的登入狀態。

範例程式碼 - Nuxt 3 - 實作部落格資料庫與會員系統

導覽列模板與新增文章

上面我們完成了基本的會員登入，接下來將進入網站的切版，以下會使用布局模板來實現，上方導覽列與下方顯示網站內容的排版方式，接下來就會快速的進入到新增一篇部落格的文章，該如何實現 Server API 與前端進行串接。

預設布局模板

首先，建立一個預設布局模板，我們預計使每個頁面於上方顯示導覽列，下方則是依據不同的頁面來顯示，大概如下所示。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


+---------------------------+
| +-----------------------+ |
| | 導覽列 | |
| +-----------------------+ |
| +-----------------------+ |
| | 不同頁面的內容顯示的位置 | |
| | | |
| | | |
| | | |
| +-----------------------+ |
+---------------------------+

我們可以建立一個 default.vue 於 layouts 目錄中，作為預設的佈局模板，模板內約會實作下面的程式碼：

1
2
3
4
5
6
7
8


<template>
 <div>
 <header>
 <!-- 導覽列 -->
 </header>
 <slot />
 </div>
</template>

<header> 裡面就是我們可以實作導覽列的位置，下方的 <slot /> 插槽，即會是我們可以放置頁面的容器。

完整的 ./layouts/default.vue 程式碼如下：

layouts/default.vue

 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
33
34
35
36
37
38


<template>
 <div>
 <header class="flex w-full justify-center px-8 xl:px-0">
 <nav class="flex w-full max-w-7xl items-center justify-between py-2">
 <div>
 <a aria-label="TailwindBlog" href="/">
 <div class="flex items-center justify-between">
 <div class="mr-3">
 <Icon class="h-12 w-12" name="logos:nuxt-icon" />
 </div>
 <div class="hidden h-6 text-2xl font-semibold text-gray-700 sm:block">
 Nuxt 3 Blog
 </div>
 </div>
 </a>
 </div>
 <div class="flex items-center text-base leading-5">
 <div class="flex flex-row items-center">
 <NuxtLink
 class="px-3 py-2 text-gray-700 transition hover:text-emerald-500"
 to="/login"
 >
 登入
 </NuxtLink>
 </div>
 </div>
 </nav>
 </header>
 <slot />
 </div>
</template>

<script setup>
import { useUserStore } from '@/stores/user'

const userStore = useUserStore()
const userProfile = computed(() => userStore.profile)
</script>

接著記得調整 app.vue 內容，添加一個 <NuxtLayout> 元件來顯示預設的布局模板，包裹著的 <NuxtPage /> 即會放置於 default.vue 預設插槽之中，如此就能顯示路由的頁面。

1
2
3
4
5


<template>
 <NuxtLayout>
 <NuxtPage />
 </NuxtLayout>
</template>

至此，我們就完成的第一個導覽列，可以由導覽列提供的「登入」，切換至登入頁面，並且在每個頁面中，都使用預設的布局模板，所以都會顯示導覽列。

取消或替換特定頁面的布局模板

在【Nuxt3】開箱即用的 Nuxt3 玩轉筆記 - Nuxt 3 布局模板 (Layouts) 內有介紹到，我們可以建立多個布局模板，而 Nuxt 也提供我們可以為頁面元件取消使用或選擇特定的布局模板。

例如，我們想將登入與註冊頁面，取消套用預設的布局模板，我們就可以使用 definePageMeta() 來傳入 layout: false 屬性來取消布局模板的使用。

調整登入頁面 ./pages/login.vue

pages/login.vue

1
2
3
4
5
6
7


<script setup>
// ...

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

如此一來，登入頁面將不會使用布局模板，導覽列也就不會顯示。

建立使用者選單

為了豐富導覽列，我們可以為已登入的使用者，建立一個使用者頭像，點擊後可以顯示使用者專用的選項，例如登出等功能。

安裝 headless UI

我們的使用的是 Tailwind CSS 來做樣式的處理，headless UI 已經封裝一些實用且好看的元件，元件基於 Tailwind CSS 可以讓我們的風格更一致，也能更彈性的自訂成自己喜歡的樣式。

使用 NPM 安裝 @headlessui/vue：

1
2
3


npm install -D @headlessui/vue
# or
# yarn add -D @headlessui/vue

調整 nuxt.config.ts，將 @headlessui/vue 新增至 build.transpile 屬性之中。

nuxt.config.ts

1
2
3
4
5


export default defineNuxtConfig({
 build: {
 transpile: ['@headlessui/vue']
 }
})

建立使用者頭像選單元件

新增 ./components/NavigationBar/NavigationBarAvatarMenu.vue 內容如下：

components/NavigationBar/NavigationBarAvatarMenu.vue

 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
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51


<template>
 <div>
 <Menu as="div" class="relative inline-block text-left">
 <div>
 <MenuButton class="inline-flex w-full justify-center">
 <img
 class="inline-block h-10 w-10 rounded-full bg-white/90 object-cover object-center p-0.5 shadow-lg shadow-zinc-800/5 ring-1 ring-zinc-900/5 backdrop-blur hover:bg-opacity-30 focus:outline-none focus-visible:ring-2 focus-visible:ring-white focus-visible:ring-opacity-75"
 src="https://images.unsplash.com/photo-1577023311546-cdc07a8454d9?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=128&q=80"
 alt="使用者選單"
 />
 </MenuButton>
 </div>

 <transition
 enter-active-class="transition duration-100 ease-out"
 enter-from-class="transform scale-95 opacity-0"
 enter-to-class="transform scale-100 opacity-100"
 leave-active-class="transition duration-75 ease-in"
 leave-from-class="transform scale-100 opacity-100"
 leave-to-class="transform scale-95 opacity-0"
 >
 <MenuItems
 class="absolute right-0 mt-2 w-56 origin-top-right divide-y divide-gray-100 rounded-md bg-white shadow-lg ring-1 ring-black ring-opacity-5 focus:outline-none"
 >
 <div class="px-1 py-1">
 <MenuItem v-slot="{ active }">
 <button
 :class="[
 active ? 'bg-emerald-500 text-white' : 'text-gray-900',
 'group flex w-full items-center rounded-md px-2 py-2 text-sm'
 ]"
 >
 <Icon
 :active="active"
 class="mr-2 h-5 w-5 text-emerald-400"
 name="ri:logout-box-line"
 aria-hidden="true"
 />
 登出
 </button>
 </MenuItem>
 </div>
 </MenuItems>
 </transition>
 </Menu>
 </div>
</template>

<script setup>
import { Menu, MenuButton, MenuItems, MenuItem } from '@headlessui/vue'
</script>

將 <NavigationBarAvatarMenu> 元件添加至導覽列之中，我們就可以擁有一個使用者頭像的選單囉。

結合使用者 Store 來控制顯示的時機

使用者頭像選單的元件應該控制於使用者登入之後再顯示，所以我們可以結合 Pinia 進行狀態管理，來檢查使用者資訊的 store 是否具有資料且符合我們的判定依據再進行顯示，否則，我們僅需要渲染出登入的按鈕即可。

例如，我們從 User Store 取出使用者資訊 (Profile)，並判斷是否有 id 來決定要顯示使用者頭像選單或登入。

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


<template>
 <div>
 <ClientOnly>
 <NavigationBarAvatarMenu v-if="userProfile?.id" />
 <NuxtLink
 v-else
 class="px-3 py-2 text-gray-700 transition hover:text-emerald-500"
 to="/login"
 >
 登入
 </NuxtLink>
 </ClientOnly>
 </div>
</template>

<script setup>
import { useUserStore } from '@/stores/user'

const userStore = useUserStore()
const userProfile = computed(() => userStore.profile)
</script>

整個完成後，介面看起來就會比較乾淨也符合登入與未登入時，應該顯示的介面樣子。

新增部落格文章

當我們處理好登入後，就開可以開始來實作使用者建立部落格的文章囉！

建立文章資料表

我們的資料庫，是透過 Prisma 的 Schema 來自動產生資料表，我們可以建立如下的 Schema，來作為儲存文章內容的資料表。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


model Article {
 id Int @id @default(autoincrement())
 title String
 content String
 cover String
 tags String
 authorId String?
 createdAt DateTime @default(now())
 updatedAt DateTime @updatedAt
}

欄位相對簡單，各個欄位的用途與說明如下：

id: 文章的 ID，採用自動遞增的數字。
title: 文章的標題。
content: 文章的內容。
cover: 文章的封面圖片。
tags: 文章的標籤。
authorId: 對應 User 資料表的 id 欄位，表示文章的作者。
createdAt: 文章建立時間，預設為插入該筆資料的時間。
updatedAt: 使用者更新文章資料的時間，預設為更新該筆資料的時間。

另外，我想讓 Article 具有關聯性，所以我們可以使用 Prisma 提供的語法，來建立與 User 的外鍵 (Foreign Key)，最後完整的 schema.prisma 如下：

 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
33
34
35
36
37


// This is your Prisma schema file,
// learn more about it in the docs: https://pris.ly/d/prisma-schema

generator client {
 provider = "prisma-client-js"
}

datasource db {
 provider = "sqlite"
 url = "file:./dev.db"
}

model User {
 id String @id @default(uuid())
 providerName String?
 providerUserId String?
 nickname String @default("User")
 email String @unique
 password String?
 avatar String?
 emailVerified Boolean @default(false)
 createdAt DateTime @default(now())
 updatedAt DateTime @updatedAt
 Article Article[]
}

model Article {
 id Int @id @default(autoincrement())
 title String
 content String
 cover String
 tags String
 authorId String?
 createdAt DateTime @default(now())
 updatedAt DateTime @updatedAt
 User User? @relation(fields: [authorId], references: [id])
}

記得執行以下指令，來讓 Prisma 建立新的資料表。

1

npx prisma db push

建立新增文章的 API

建立 ./server/api/manage/articles.post.js，內容如下：

server/api/manage/articles.post.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
33


import db from '@/server/db'

export default defineEventHandler(async (event) => {
 const user = event.context?.auth?.user

 if (!user?.id) {
 throw createError({
 statusCode: 401,
 statusMessage: 'Unauthorized'
 })
 }

 const body = await readBody(event)

 const authorId = user.id

 const articleRecord = await db.article.createArticle({
 title: body.title,
 content: body.content,
 cover: body.cover,
 tags: body.tags,
 authorId
 })

 if (!articleRecord) {
 throw createError({
 statusCode: 400,
 statusMessage: 'Create article failed. Please try again later.'
 })
 }

 return articleRecord
})

整個 Server API 的運作流程如下：

使用者將欲新增的文章資料以 POST 發送至 /api/manage/article，伺服器中間件，將會解析 JWT 來得到 user。
判斷 user.id 來決定是否具有權限，如果正確解析 JWT，表示請求為一個已登入的使用者發送，也將放行給予新增文章。
處理函數將解析 Body 內的資料，並建構出往資料庫新增文章記錄的內容。
判斷是否新增成功，回傳新增的文章資料。

建立文章的 Prisma Client 操作如下：

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


async createArticle(options) {
 const articleRecord = await prisma.article
 .create({
 data: {
 title: options.title,
 content: options.content,
 cover: options.cover,
 tags: options.tags,
 authorId: options.authorId
 }
 })
 .catch((error) => {
 console.error(error)
 throw createError({
 statusCode: 500,
 statusMessage: 'Could not create article. Please try again later.'
 })
 })

 return articleRecord
}

我們就完成了建立文章的 API 囉！

取得部落格文章

使用 Prisma Client 來取得文章，也非常方便，如下程式碼，我們就能取出文章資料並以建立時間遞減排序囉！

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


async getArticles(options = {}) {
 const articleRecords = await prisma.article
 .findMany({
 orderBy: {
 createdAt: 'desc'
 },
 skip: options.pageSize ? options.page * options.pageSize : undefined,
 take: options.pageSize
 })
 .catch((error) => {
 console.error(error)
 throw createError({
 statusCode: 500,
 statusMessage: 'Could not create user. Please try again later.'
 })
 })

 return articleRecords
}

./server/api/articles.get.js 是實作取得文章的 API，我們期望任何人都可以瀏覽這個部落格的文章，所以這隻 API 我們無需驗證使用者即可放行，程式碼如下：

server/api/articles.get.js

1
2
3
4
5
6
7


import db from '@/server/db'

export default defineEventHandler(async () => {
 const articlesRecord = await db.article.getArticles()

 return articlesRecord
})

我們也可以在 ./server/api/articles.get.js 處理函數內，添加資料的分頁或為文章資料進行加工，以利前端顯示。

我們建立好了部落個的版面，有了導覽列和使用者選單，網站看起來也更專業了一些，結合布局模板，我們可以控制每個頁面所顯示的布局，在未來有更多頁面的時候能具有可控性。最後也實作了新增文章的 API，完成了第一篇文章的新增與瀏覽。

頁面的導航守衛與切換效果

我們完成了新增文章的頁面與流程，在網站開發的過程中，有些頁面是具有瀏覽的限制，例如，我們不希望一般的使用者能進到管理者頁面專用的頁面進行操作，這時候我們就需要做一些權限的驗證與限制，在 Nuxt 的頁面提供了路由中間件可以在我們導航至頁面之前，執行一些處理函數，就實作導航守衛 (Navigations Guards) 的效果。最後會介紹一下在 Nuxt 3 所提供的頁面和布局切換時的進度條 (Progress bar) 與轉場效果 (Transitions)。

頁面間的導航守衛

只允許已登入使用者新增文章

首先，我們新增一個路由中間件 ./middleware/manage-auth.js 內容如下：

middleware/manage-auth.js

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


import { useUserStore } from '@/stores/user'

export default defineNuxtRouteMiddleware(() => {
 if (process.client) {
 const userStore = useUserStore()

 if (!userStore.profile?.id) {
 return navigateTo('/login')
 }
 } else {
 return navigateTo('/')
 }
})

在頁面元件中使用 definePageMeta() 來套用 manage-auth 中間件。調整 ./pages/manage/articles/create.vue 內容：

pages/manage/articles/create.vue

1
2
3
4
5
6
7


<script setup>
// ...

definePageMeta({
 middleware: 'manage-auth'
})
</script>

我們首頁新增一個可以導向至 /manage/articles/create 頁面的按鈕。

1
2
3
4
5
6


<NuxtLink
 class="text-md mt-12 rounded-sm bg-emerald-500 py-2 px-4 font-medium text-white hover:bg-emerald-600 focus:outline-none focus:ring-2 focus:ring-emerald-400 focus:ring-offset-2"
 to="/manage/articles/create"
>
 前往撰寫文章
</NuxtLink>

當我們處於未登入的情況，點擊前往後，會經由中間件判斷 process.client 是否是在客戶端，進而從 User Store 取出使用者資訊進行判斷，當不存在 userStore.profile.id 時，表示未登入，我們將導航至登入頁面 /login；當登入完成後，就可以使用按鈕成功導航至新增文章的頁面。如果 process.client 為 false，表示導航是在伺服器端觸發的，例如，我們直接透過網址進入新增文章頁面，將會一律被重新導航至首頁。

登入完成後導回至登入前瀏覽的頁面

當使用者在瀏覽網站時被引導或準備登入時，我們可以將使用者目前的頁面進行記錄，以便登入完成後，可以重新導向至使用者登入前的頁面，以此提供使用者更棒的體驗。

首先，我們新增一個路由中間件 ./middleware/logged-in-redirect.js 內容如下：

middleware/logged-in-redirect.js

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


export default defineNuxtRouteMiddleware((to, from) => {
 if (from && to.path !== from.path && !to.query.redirect_to) {
 let redirectTo = null
 if (from.query.redirect_to) {
 redirectTo = from.query.redirect_to
 from.query.redirect_to = undefined
 } else {
 redirectTo = from.fullPath
 }

 to.query.redirect_to = redirectTo

 return navigateTo(to)
 }
})

這個 logged-in-redirect 中間件的處理邏輯，我們接收 to 與 from，分別為目標頁面與來源頁面，當使用者目標頁面 /login 還未帶上了 Query 參數 redirect_to，我們就將來源的完整路徑添加上去 from.fullPath，最後進行導向。

這裡需要進行判斷 redirect_to，否則會重複發生重新導向。

在登入頁面中使用 definePageMeta() 來套用 logged-in-redirect 中間件。調整 ./pages/login.vue 內容：

pages/login.vue

1
2
3
4
5
6
7


<script setup>
// ...

definePageMeta({
 middleware: 'logged-in-redirect'
})
</script>

在登入完成的地方，我們就可以使用 navigateTo() 導向至 redirect_to 給的頁面路徑。

1
2
3
4
5
6
7
8
9


<script setup>
const route = useRoute()

const handleEmailLogin = async () => {
 // ...

 navigateTo(route.query.redirect_to ?? '/')
}
</script>

完成後，我們從首頁點擊登入後．當登入完成後就會導向回首頁；而從文章頁面點擊登入，完成後則會導向回文章頁面。

頁面載入進度元件

Nuxt 3 提供一個 <NuxtLoadingIndicator> 元件，用作頁面導航後顯示載入的進度，會在頁面上方有一個進度條 (Progress bar)。

只需要將 <NuxtLoadingIndicator> 元件添加至 app.vue 或布局之中，調整 app.vue 內容如下：

app.vue

1
2
3
4
5
6


<template>
 <NuxtLayout>
 <NuxtLoadingIndicator />
 <NuxtPage />
 </NuxtLayout>
</template>

元件可以傳入的屬性 (Props) 如下：

color：進度條的顏色，可以傳入CSS 支援的色碼或 repeating-linear-gradient() 函数，預設為 repeating-linear-gradient(to right,#00dc82 0%,#34cdfe 50%,#0047e1 100%)。
height：進度條的高度數值，單位： px，預設值為 3。
duration：進度條載入的持續時間，單位： 毫秒，預設值為 2000。
throttle：進度條的隱藏與顯示，限制在特定時間內僅觸發一次，單位： 毫秒，預設值為 200。

當我們從首頁切換頁面時，網頁上方就會出現一個進度條，表示頁面正在載入中。

頁面切換的轉場效果

除了載入的進度條，頁面切換之間，也可以使用轉場效果 (Transitions) 來讓頁面之間的銜接更柔順，Nuxt 利用了 Vue 內建的 <Transition> 元件來幫助處理轉場和動畫，用以響應不斷變化的頁面與狀態。

Nuxt 預設為所有頁面 (Pages) 都設置了轉場，如果要啟用，請將以下 CSS 添加至 app.vue 中：

app.vue

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


<template>
 <NuxtPage />
</template>

<style>
.page-enter-active,
.page-leave-active {
 transition: all 0.4s;
}
.page-enter-from,
.page-leave-to {
 opacity: 0;
 filter: blur(1rem);
}
</style>

每個頁面的 pageTransition 預設屬性皆為 { name: 'page', mode: 'out-in' }，name 為 page 也就對應了 CSS 類別的開頭；mode 有 in-out、out-in 及 default 三種參數可選。

1
2
3
4
5
6
7
8
9


.[pageTransition.name]-enter-active,
.[pageTransition.name]-leave-active {
 transition: all 0.4s;
}
.[pageTransition.name]-enter-from,
.[pageTransition.name]-leave-to {
 opacity: 0;
 filter: blur(1rem);
}

套用好頁面的轉場，就會有切換頁面時有模糊的效果。

自訂頁面的轉場

既然知道 pageTransition 的 name 會對應頁面轉場的 CSS 名稱，我們就可以來自定義更多轉場，讓不同頁面套用不同的效果。

例如在 app.vue 添加 rotate 為前綴的類別名稱 CSS。

app.vue

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


<style>
/* ... */
.rotate-enter-active,
.rotate-leave-active {
 transition: all 0.4s;
}
.rotate-enter-from,
.rotate-leave-to {
 opacity: 0;
 transform: rotate3d(1, 1, 1, 15deg);
}
</style>

在頁面中使用 definePageMeta() 來設定 pageTransition.name 為 rotate。調整 ./pages/login.vue 添加如下程式碼。

pages/login.vue

1
2
3
4
5
6
7
8
9


<script setup>
// ...

definePageMeta({
 pageTransition: {
 name: 'rotate'
 }
})
</script>

當頁面切換時，皆會使用預設的模糊轉場效果，當切換至登入頁面就會套用指定的 rotate 頁面轉場，而有旋轉的轉場效果。

布局的轉場效果

Nuxt 同樣為所有布局 (Layouts) 都設置了轉場，如果要啟用，請將以下 CSS 添加至 app.vue 中。

1
2
3
4
5
6
7
8


.layout-enter-active,
.layout-leave-active {
 transition: all 0.4s;
}
.layout-enter-from,
.layout-leave-to {
 filter: grayscale(1);
}

建立 ./layouts/teal.vue 布局，程式碼如下：

layouts/teal.vue

1
2
3
4
5


<template>
 <div class="h-screen bg-teal-50">
 <slot />
 </div>
</template>

將登入頁面的布局套用 teal。

1
2
3
4
5
6
7


<script setup>
// ...

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

建立 ./layouts/green.vue 布局，程式碼如下：

layouts/green.vue

1
2
3
4
5


<template>
 <div class="h-screen bg-teal-50">
 <slot />
 </div>
</template>

將註冊頁面的布局套用 green。

1
2
3
4
5
6
7


<script setup>
// ...

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

在登入頁面與註冊頁面切換時，因為兩個頁面使用了不同的布局，布局的轉場效果，使背影顏色會有灰階效果的轉場。

你也可以像自訂頁面轉場一樣，來使用 definePageMeta() 設定 layoutTransition.name 屬性，來指定自訂的轉場效果。

1
2
3
4
5
6
7
8


<script setup>
definePageMeta({
 layout: 'green',
 layoutTransition: {
 name: 'slide-in'
 }
})
</script>

禁用轉場效果

頁面與布局的轉場效果，都可以透過 definePageMeta 來設定 pageTransition 或 layoutTransition 為 false 來禁止套用轉場效果。

1
2
3
4
5
6


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

全域預設的轉場效果

你也可以在 nuxt.config.ts 設置預設的頁面與轉場效果，例如：

nuxt.config.ts

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


export default defineNuxtConfig({
 pageTransition: {
 name: 'fade',
 mode: 'out-in' // default
 },
 layoutTransition: {
 name: 'slide',
 mode: 'out-in' // default
 }
})

當然要將所有頁面與布局預設禁用也可以設置如下：

1
2
3
4


export default defineNuxtConfig({
 pageTransition: false,
 layoutTransition: false
})

pageTransition 與 layoutTransition 接受的屬性可以參考 TransitionProps。

元件屬性傳入 transition

在 app.vue 中使用 <NuxtPage /> 時，你可以將 TransitionProps 作為元件的 Props 來啟用全域預設的轉場效果。

1
2
3
4
5
6
7
8
9


<template>
 <div>
 <NuxtPage :transition="{
 name: 'bounce',
 mode: 'out-in'
 }" />
 </NuxtLayout>
 </div>
</template>

當使用此方法設定轉場效果時，就不能在頁面中使用 definePageMeta() 來覆蓋這裡的頁面轉場設置。

以上我們主要實作了導航守衛，來為特定頁面添加瀏覽的權限，我們除了使用客戶端的 User Store 驗證外，也可以搭配 Cookie 再後端進行驗證，甚至為每個請求解析使用者，並查詢資料庫是否具有權限瀏覽，以此來控制使用者瀏覽頁面的權限，除了前端的阻擋外，更重要的是後端 API 也需要搭配進行權限驗證，才能有要的防止網頁漏洞產生，否則可能會發生，使用者無權瀏覽新增或管理的頁面，但是可以透過打 API 來進行相關操作，這樣是非常危險的。最後，我們將頁面切換時設置了進度條與轉場效果，使得整體網站能提供使用者更好的操作體驗，更多的轉場設置，也可以參考 Nuxt 官方文件。

範例程式碼 - Nuxt 3 - 設置導航守衛與頁面切換效果範例

添加 HTML Meta Tag

詳細 Nuxt3 添加 HTML Meta Tag 的說明，可以參考【Nuxt3】開箱即用的 Nuxt3 玩轉筆記 - 搜尋引擎最佳化 (SEO) 與 HTML Meta Tag，這邊我們說明為實作的部落格文章添加 Meta，調整 ./pages/articles/[id].vue 檔案，添加以下程式碼：

pages/articles/[id].vue

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


<script setup>
// ...

useHead({
 meta: [
 { name: 'description', content: `${article.value.summary} | Nuxt 3 Blog` },
 { name: 'keywords', content: `${article.value.tags}` },
 { property: 'og:title', content: `${article.value.title} | Nuxt 3 Blog` },
 { property: 'og:description', content: article.value.summary },
 { property: 'og:image', content: article.value.cover }
 ],
 title: `${article.value.title} | Nuxt 3 Blog`
})
</script>

其中 article 是我們從 Server API 回傳的指定貼文的資料並具有響應性，最後看看成果。

在 Nuxt 3 提供了一些可以設置網頁屬性與 Meta 的組合式函數，更能動態的調整與響應，結合 SSR 讓這些標記在伺服器端就能渲染出來，對網站做搜尋引擎最佳化 (SEO) 非常得友善，也是多數人選擇 Nuxt 3 來處理 SSR 與 SEO 的原因。除了 SEO 可能會使用到的的標記外，也有 OG Tag 可以加強網頁的連結預覽效果，雖然 OG Tag 與 SEO 沒有絕對的關係，但是透過伺服器端渲染調整這些 Meta 對搜尋引擎或網站都非常的方便，我們只要根據需求及指引做設定，就能對網站的能見度有所提升。

邁向國際化實作多國語系I18n

當一個網站需要面向不同國家或不同語言的使用者，我們就需要做國際化 (Internationalization)，將網站內容進行翻譯或語言的對應，讓使用者能理解網頁上的操作或內容，I18n 意謂著「Internationalization」這個單字中，I 和 n 之間有 18 個字母，也正是各個框架的實作多國語系套件的一個常用名稱，例如 Vue 生態就有 vue-i18n，而這篇文章將講述如何在 Nuxt 3 中整合 Vue I18n 來協助實作多國語系。

Nuxt 3 使用 Vue I18n

想要在 Vue 3 使用 Vue I18n 獲得比較好的支援度需要使用正處於 Beta 階段的 v9 版本，因此有幾種方式可以在 Nuxt 整合 Vue I18n，分別是依照 Vue I18n 官方指引、使用 Nuxt Community提供的 @nuxtjs/i18n@next 模組及 @intlify/nuxt3 模組。

比較早以前，Nuxt 3 社群模組還沒有支援比較新的 Vue I18n，所以需要自己額外的製作插件來安裝，後來也有一些相容性的問題，所以 Vue I18n v9 的作者 kazupon 發布了 @intlify/nuxt3 模組來方便 Nuxt 3 整合 vue-i18n-next (Vue I18n v9)，目前仍然可以使用 @intlify/nuxt3 來進行整合，但我最後選擇使用 @nuxtjs/i18n@next 模組，除了看好是由 Nuxt Community 提供的支援及未來的發展外，也能使用到 @nuxtjs/i18n 提供的一些組合函數等。

Nuxt 3 整合 @nuxtjs/i18n

目前 @nuxtjs/i18n 模組的穩定版本在 v7.3.0，而使用 Vue 3 和 Vue I18n v9 的模組則是下一個迭代版本 v8，所以使用 NPM 安裝的時候需要稍微注意一下。

下圖於 2020/10/10 擷取自 NPM - @nuxyjs/i18n

Step 1. 安裝 @nuxtjs/i18n

目前有 A 或 B 兩種方式可以安裝 @nuxtjs/i18n v8 分別如下，可以選擇其中一種即可：

A. 使用 next 標籤來安裝 v8 版本

1
2
3


npm install -D @nuxtjs/i18n@next
# or
# yarn add -D @nuxtjs/i18n@next

B. 安裝 @nuxtjs/i18n-edge (Edge Version)

添加 "@nuxtjs/i18n": “npm:@nuxtjs/i18n-edge” 至 package.json 的 dependencies 或 devDependencies 依賴中，看起來可能像這樣：

1
2
3
4
5
6
7
8


{
 // ...
 "devDependencies": {
 // ...
 "@nuxtjs/i18n": "npm:@nuxtjs/i18n-edge",
 // ...
 }
}

執行 npm install

這邊我使用的是用 next 標籤來安裝。

Step 2. 添加模組

於 nuxt.config.ts 中的 modules 屬性添加 '@nuxtjs/i18n'，參考如下：

nuxt.config.ts

1
2
3


export default defineNuxtConfig({
 modules: ['@nuxtjs/i18n']
})

Step 3. 設定 i18n 參數

當添加完模組後，我們可以先設置 @nuxhjs/i18n 模組的選項，來測試是否能正常運作，於 nuxt.config.ts 中，添加 i18n 屬性，用以設置**@nuxhjs/i18n** 模組；i18n.vueI18n 設置的選項也可以參考 Vue I18n v9 官方文件。

nuxt.config.ts

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


export default defineNuxtConfig({
 modules: ['@nuxtjs/i18n'],
 i18n: {
 vueI18n: {
 legacy: false,
 locale: 'zh',
 messages: {
 en: {
 hello: 'Hello!',
 language: 'Language'
 },
 zh: {
 hello: '你好!',
 language: '語言'
 }
 }
 }
 }
})

記得設置 i18n.vueI18n.legacy 為 false 來關閉使用較舊的 API 模式。

Step 4. 確認專案下的 pages 目錄

當完成 Step 3. 的模組設置後，就可以啟動伺服器來看看效果；不過若是 Nuxt 3 專案目錄下缺少了 pages 目錄，可能會無法啟用 Vue Router 自動產生路由，而出現下圖的錯誤。

我們只需要新增 ./pages/ingex.vue 路由頁面，就可以解決錯誤囉！

建立英語和繁體中文的語系切換

我們安裝與配置好 @nuxtjs/i18n 後，可以嘗試建立頁面來看看效果，以下以 en 與 zh 作為英語和繁體中文兩個語系的使用範例。

新增 ./pages/index.vue 內容如下：

pages/index.vue

1
2
3
4
5
6
7


<template>
 <div class="flex flex-col items-center bg-white">
 <h1 class="mt-48 text-8xl font-medium text-blue-500">
 {{ $t('hello') }}
 </h1>
 </div>
</template>

我們就可以使用 $t() 來傳入我們在 nuxt.config.ts 中的 i18n.vueI18n.messages 定義語系與對應的文字，而我們預設是 zh 繁體中文語系，畫面上就出現 hello: ‘你好!’ 對應的「你好!」文字囉！

新增按鈕來實現切換不同的語系，完整的程式碼如下：

 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
33


<template>
 <div class="flex flex-col items-center bg-white">
 <h1 class="mt-48 text-8xl font-medium text-blue-500">
 {{ $t('hello') }}
 </h1>
 <div class="mt-24 space-x-4">
 <button
 type="button"
 class="inline-flex items-center rounded-md border border-transparent bg-blue-100 px-4 py-2 text-sm font-medium text-blue-700 hover:bg-blue-200 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2"
 @click="setLocale('en')"
 >
 English
 </button>

 <button
 type="button"
 class="inline-flex items-center rounded-md border border-transparent bg-blue-100 px-4 py-2 text-sm font-medium text-blue-700 hover:bg-blue-200 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2"
 @click="setLocale('zh')"
 >
 繁體中文
 </button>
 </div>
 <div class="mt-4 flex flex-row justify-center">
 <label class="text-gray-600">{{ $t('language') }}</label>
 <span class="ml-4 font-bold text-gray-800">{{ locale }}</span>
 </div>
 </div>
</template>

<script setup>
import { useI18n } from 'vue-i18n'
const { locale } = useI18n()
</script>

若沒有特殊需求，切換語系你可以選擇直接設定 locale 來自動響應或使用 setLocale() 來設定語系。

1
2
3
4
5
6
7
8


<script setup>
import { useI18n } from 'vue-i18n'
const { locale, setLocale } = useI18n()

locale.value = 'en'
// or
setLocale('en')
</script>

完成後我們就可以切換 en 與 zh 語系，當然你也可以製作成選單來放置更多的語系來支援切換。

獨立存放語系檔案

隨著專案增大，語系的翻譯數量也會增多，而全部放在 nuxt.config.ts 中也實在太過冗長，所以我習慣獨立放置在一個資料夾內做處理。

稍微調整一下 nuxt.config.ts 如下：

nuxt.config.ts

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


export default defineNuxtConfig({
 modules: ['@nuxtjs/i18n'],
 i18n: {
 defaultLocale: 'zh',
 langDir: 'locales',
 locales: [
 { code: 'en', file: 'en.json', iso: 'en-US', name: 'English' },
 { code: 'zh', file: 'zh.json', iso: 'zh-TW', name: '繁體中文' }
 ],
 strategy: 'no_prefix',
 vueI18n: {
 legacy: false
 }
 }
})

接著我們就可以建立各個語系放置的資料夾對應著 i18n.langDir 屬性，目錄名稱為 locales，再依序建立 en.json 與 zh.json 檔案，最終目錄的結構大概會長這樣：

1
2
3
4
5
6
7


nuxt-app/
├── ...
├── locales/
│ ├── en.json
│ └── zh.json
├── ...
└── nuxt.config.ts

./locales/en.json 內容如下：

locales/en.json

1
2
3
4


{
 "hello": "Hello!",
 "language": "Language"
}

./locales/zh.json 內容如下：

locales/zh.json

1
2
3
4


{
 "hello": "你好!",
 "language": "語言"
}

翻譯的語系檔案，也可以在根據需求使用 .js、yaml 或 json 格式的檔案，來搭配接受參數來產生翻譯文字。

持久化語系設定

當使用者切換語系之後，我們希望儲存這個語系設定，讓使用者下次瀏覽網站時，能套用儲存的語系，而不用再次切換，我們可以藉由瀏覽器的 LocalStorage 或 Cookie 來持久化。

LocalStorage 來儲存語系設定

我們可以在變更語系時，同時將語系儲存至 LocalStorage 之中，下次瀏覽網站時，再從中取出套用語系。

例如，我們調整 ./pages/index.vue 程式碼如下，在我們自訂的 changeLanguage() 方法內，同時呼叫 localStorage.setItem('i18n-lang', localeCode) 來儲存語系。

pages/index.vue

 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


<template>
 <div class="flex flex-col items-center bg-white">
 <h1 class="mt-48 text-8xl font-medium text-blue-500">
 {{ $t('hello') }}
 </h1>
 <div class="mt-24 space-x-4">
 <button
 v-for="localeItem in locales"
 :key="localeItem.code"
 type="button"
 class="inline-flex items-center rounded-md border border-transparent bg-blue-100 px-4 py-2 text-sm font-medium text-blue-700 hover:bg-blue-200 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2"
 @click="changeLanguage(localeItem.code)"
 >
 {{ localeItem.name }}
 </button>
 </div>
 <div class="mt-4 flex flex-row justify-center">
 <label class="text-gray-600">{{ $t('language') }}</label>
 <span class="ml-4 font-bold text-gray-800">{{ locale }}</span>
 </div>
 </div>
</template>

<script setup>
import { useI18n } from 'vue-i18n'
const { locale, locales } = useI18n()

const changeLanguage = (localeCode) => {
 locale.value = localeCode
 localStorage.setItem('i18n-lang', localeCode)
}
</script>

調整 app.vue 從 LocalStorage 讀取 i18n-lang 的設定值

app.vue

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


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

<script setup>
import { useI18n } from 'vue-i18n'
const { locale } = useI18n()

const defaultLocaleCode = locale.value

if (process.client) {
 locale.value = localStorage.getItem('i18n-lang') ?? defaultLocaleCode
}
</script>

當下次我們瀏覽網站時，就會查看 LocalStorage 中的語系設定並套用。

Nuxt 3 的伺服器渲染，會導致第一次的請求無法在伺服器端取得 LocalStorage 的設定，所以上面的例子，仔細看會發現，雖然正確的套用儲存的 en 英語語系設定，但畫面是先從預設的 zh 繁體中文再切換過去，導致語系切換時閃了一下。

我們可以透過使用 cookie 的方式來儲存語系，這樣伺服器端在接受第一次請求時也能解析出使用者的偏好設定，回傳正確的語系翻譯文字。

你可以自己使用 Nuxt 3 提供 useCookie 等方式操作 cookie 來實現這套流程，不過呢，@nuxtjs/i18n 模組預設是啟用 cookie 相關的設定，提供的 setLocaleCookie() 與 getLocaleCookie() 可以來協助儲存語系設定至 cookie。

調整 ./pages/index.vue 程式碼如下，在我們自訂的 changeLanguage() 方法內，同時呼叫 setLocaleCookie(localeCode) 來儲存語系。

pages/index.vue

 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


<template>
 <div class="flex flex-col items-center bg-white">
 <h1 class="mt-48 text-8xl font-medium text-blue-500">
 {{ $t('hello') }}
 </h1>
 <div class="mt-24 space-x-4">
 <button
 v-for="localeItem in locales"
 :key="localeItem.code"
 type="button"
 class="inline-flex items-center rounded-md border border-transparent bg-blue-100 px-4 py-2 text-sm font-medium text-blue-700 hover:bg-blue-200 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2"
 @click="changeLanguage(localeItem.code)"
 >
 {{ localeItem.name }}
 </button>
 </div>
 <div class="mt-4 flex flex-row justify-center">
 <label class="text-gray-600">{{ $t('language') }}</label>
 <span class="ml-4 font-bold text-gray-800">{{ locale }}</span>
 </div>
 </div>
</template>

<script setup>
import { useI18n } from 'vue-i18n'
const { locale, locales, setLocaleCookie } = useI18n()

const changeLanguage = (localeCode) => {
 locale.value = localeCode
 setLocaleCookie(localeCode)
}
</script>

調整 app.vue 呼叫 getLocaleCookie() 從 cookie 解析的設定值，並再進行套用。

app.vue

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


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

<script setup>
import { useI18n } from 'vue-i18n'
const { locale, getLocaleCookie } = useI18n()

const defaultLocaleCode = locale.value

locale.value = getLocaleCookie() ?? defaultLocaleCode
</script>

當我們使用 setLocaleCookie() 儲存語系至 cookie，會將 localeCode 儲存在 cookie 的 i18n_redirected 值上，當我們重新進入網頁，cookie 也將自動夾帶了這個 cookie 過去給伺服器端，並由 getLocaleCookie() 解析再由我們進行語系套用。

其實 @nuxtjs/i18n 因為已將 detectBrowserLanguage.useCookie 預設為 true 等啟用了 cookie 儲存的相關設定，當使用者進入網站時，就會嘗試檢查瀏覽器的 cookie 來將使用者儲存的偏好語言進行套用或重定向。

因此，我們在 app.vue 也不需要特別從 cookie 取出再進行套用，@nuxtjs/i18n 會自動幫我們完成。

app.vue

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


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

<script setup>
// 除非你有特需的需求，不然這邊都不需要自己來了

// import { useI18n } from 'vue-i18n'
// const { locale, getLocaleCookie } = useI18n()

// const defaultLocaleCode = locale.value

// locale.value = getLocaleCookie() ?? defaultLocaleCode
</script>

而當使用者調整語系時，在第一個範例有提到，如果沒有特別需求，我們可以直接使用 locale 來設定語系，來自動響應變更語系，再使用 setLocaleCookie(localeCode) 將語系保存至 cookie 之內。

1
2
3
4
5
6
7
8
9


<script setup>
import { useI18n } from 'vue-i18n'
const { locale, locales, setLocaleCookie } = useI18n()

const changeLanguage = (localeCode) => {
 locale.value = localeCode
 setLocaleCookie(localeCode)
}
</script>

但我們只要使用 setLocal() 方法來套用語系，就會一同更新至 cookie 中進行儲存，非常方便。最後我們將 ./pages/index.vue 中的調整如下，一樣可以達到在 cookie 中儲存使用者語系並在下次瀏覽網頁時自動套用。

pages/index.vue

1
2
3
4
5
6
7
8


<script setup>
import { useI18n } from 'vue-i18n'
const { locale, locales, setLocale } = useI18n()

const changeLanguage = (localeCode) => {
 setLocale(localeCode)
}
</script>

使用 setLocaleCookie() 與 getLocaleCookie() 操作的預設設定，我們可以透過 nuxt.config.ts 中的 i18n.detectBrowserLanguage 進行調整，例如，調整 cookieKey 來變更儲存的名稱 i18n_redirected 等，更多選項可以參考這裡。

nuxt.config.ts

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


export default defineNuxtConfig({
 modules: ['@nuxtjs/i18n'],
 i18n: {
 // ...
 detectBrowserLanguage: {
 useCookie: true,
 cookieKey: 'i18n_redirected'
 },
 // ...
 }
})

@nuxtjs/i18n 模組提供的 cookie 操作語系持久化，甚至能做到一些重導向等行為，較 Nuxt 3 提供 useCookie 等方式自己來實現這套流程能更擁有更多功能。

範例程式碼 - Nuxt 3 - 搜尋引擎最佳化 (SEO) 之設定網頁 Meta 及 OG Tag 範例

【Nuxt3】開箱即用的 Nuxt3 玩轉筆記

Sat, 14 Jan 2023 00:00:00 +0000

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

在使用 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。

開始建立第一個專案

先決條件

開始之前，依照 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 會詢問你是否安裝最新版本的套件 nuxi@3.0.0-rc.10 輸入 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 的規則的配置，這裡稍微注意一下順序如下：

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

匹配模式	匹配路徑	匹配參數 (Params)
/posts	/posts	無

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

匹配模式	匹配路徑	匹配參數 (Params)
/posts/top-:number	/posts/top-3	{ number: 3 }
/posts/top-:number	/posts/top-5	{ number: 5 }

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

匹配模式	匹配路徑	匹配參數 (Params)
/posts/:postId	/posts/8	{ postId:8 }

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

匹配模式	匹配路徑	匹配參數 (Params)
/posts/:postId/comments/:commentId	/posts/8/comments/1	{ postId: 8, commentId: 1 }

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

巢狀路由 (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 /> 顯示。

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

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

如果插槽沒有給予 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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


<template>
 <div>
 <ClientOnly>
 <IronManWelcome />
 <template #fallback>
 <p class="my-6 flex justify-center">[IronManWelcome] 載入中...</p>
 </template>
 </ClientOnly>
 </div>
</template>

當進入首次網頁，會先渲染 fallback 插槽內的元素，所以瀏覽器先顯示 [IronManWelcome] 載入中… 文字，接著客戶端載入完 JS 後接手渲染 <IronManWelcome> 元件。

你也可以透過瀏覽器頁面中點擊右鍵後展開選單的「檢視網頁原始碼」功能，所看到的網頁原始碼，發現伺服器端僅先回應了 <p class="my-6 flex justify-center">[IronManWelcome] 載入中...</p>，表示這是由伺服器端渲染 <ClientOnly> 元件 fallback 插槽的內容。

.client 與 .server

Nuxt 3 的元件，也可以透過元件的檔案名稱來控制僅顯示在客戶端或伺服器端。

如果元件僅在客戶端呈現，則可以將 .client 加入元件檔名的後綴中。

建立一個 ./components/JustClient.client.vue 元件檔案，表示 <JustClient> 元件，僅會在客戶端進行渲染。

而添加 .server 後綴的元件檔案，則會是這個元件在伺服器端渲染的內容。

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

我們使用 <ClientOnly> 元件、.client 與 .server 做一個範例來看呈現的效果。

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>

components/JustClient.client.vue

1
2
3
4
5
6


<template>
 <div class="mx-16 my-4 rounded-lg bg-green-100 p-4 text-sm text-green-700">
 <span class="font-semibold">[JustClient]</span>
 <span class="ml-2">這是只有在 <span class="font-bold">Client</span> 才會渲染的元件</span>
 </div>
</template>

components/ClientAndServer.client.vue

1
2
3
4
5
6
7
8


<template>
 <div class="mx-16 my-4 rounded-lg bg-sky-100 p-4 text-sm text-sky-700">
 <span class="font-semibold">[ClientAndServer]</span>
 <span class="ml-2">
 這是從 <span class="font-bold text-red-500">Client</span> 渲染出來的元件
 </span>
 </div>
</template>

components/ClientAndServer.server.vue

1
2
3
4
5
6
7
8
9


<template>
 <div class="mx-16 my-4 rounded-lg bg-sky-100 p-4 text-sm text-sky-700">
 <span class="font-semibold">[ClientAndServer]</span>
 <span class="ml-2">
 這是從 <span class="font-bold text-red-500">Server</span> 渲染出來的元件，請等待 Client
 接手渲染
 </span>
 </div>
</template>

app.vue

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


<template>
 <div>
 <ClientOnly>
 <IronManWelcome />
 <template #fallback>
 <p class="my-6 flex justify-center">[IronManWelcome] 載入中...</p>
 </template>
 </ClientOnly>
 <JustClient />
 <ClientAndServer />
 </div>
</template>

我們重新瀏覽網頁，可以發現到由伺服器渲染的插槽元素 [IronManWelcome] 載入中… 文字與 ClientAndServer.server.vue 元件，率先被顯示了出來。接著當 JS 載入完畢後，被包裹的元件 <IronManWelcome> 也接手並覆蓋了「[IronManWelcome] 載入中…」文字，ClientAndServer.client.vue 與 JustClient.client.vue 僅在客戶端渲染的元件，也分別的覆蓋與顯示出來。

透過元件我們能更好的整理可重複使用的程式碼，也提升了可維護性，而 Nuxt 中的動態載入更是能將非必要使用的元件延遲載入，大大提升了首次進入網頁所需要下載的檔案大小，最後我們也介紹了如何控制伺服器端或客戶端渲染元件，熟悉了之後就能針對網站需求設定元件的載入及渲染方式囉！

組合式函數 (Composables)

組合式函數 (Composables) 是一種利用 Vue 3 的 Composition API 來封裝和複用有狀態邏輯的函數，在 Nuxt 我們可以將一些通用的商業邏輯放置在 composables 來建立組合式函數，這樣一來就可以在各個頁面共用這個組合式函數。

Options API 與 Composition API

選項式 API (Options API)：

下列這段是 Vue 依據 Options API 撰寫出來的程式碼，也是 Vue 2 處理邏輯的寫法，所謂 Options (選項、可選的) 指的就是以程式碼的性質來分割程式碼，所有設定資料初始值的都會在 data 這邊處理，這個元件所需要的方法則會在 methods 這裡建立，data 及 methods 也就是使用者需要的選項。

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


<script>
export default {
 data() {
 return {
 count: 0,
 doubleCount: 0
 }
 },
 methods: {
 increment() {
 this.count += 1
 },
 incrementByTwo() {
 this.doubleCount += 2
 }
 }
}
</script>

組合式 API (Composition API)：

目前在 Vue 3 你仍可以繼續使用 Vue 2 的 Options API，但隨著程式碼邏輯的增加，看似有條理的分類，其實對於理解及維護上沒有想像中便利。

Vue 3 提出的組合式 API (Composition API) 則是以邏輯功能來進行分類，你可以將所有與某個功能的 data、computed、methods 與 watch …等，寫在同一個段落行程一個區塊。

詳細說明可閱讀先前撰寫的圖解 Option API vs Composition API文章。

Mixins 與 Composables

在 Options API 可以使用 mixin 來引入可以重複使用的程式碼，讓不同的元件可以共用函數方法，但隨著專案變大，同一個元件可能使用 mixin 同時來引用許多的共用函數，這將導致容易產生命名衝突、元件間的耦合與來源不夠清晰等問題（詳細原因請參考淺談為什麼 Vue 和 React 都選擇了 Hooks？）。

Vue 3 為我們帶來了組合式 API，實現了更乾淨的程式碼編排與高效的邏輯重用，**組合式函數 (Composables)**也基於組合式 API 來進行封裝這些可複用的邏輯，更解決了使用 mixin 實現共用函數的缺點。

組合式函數 (Composables)

在 Nuxt 3 中要建立一個組合式函數 (Composables) 我們可以在 composables 目錄下編寫，這些常用的函數，將會被 Nuxt 3 自動載入做使用，實現在各個元件使用這些函數方法。

建立組合式函數

首先，我們新增 ./composables/useCounter.js，內容如下：

composables/useCounter.js

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


export default function () {
 const count = ref(0)

 const increment = () => {
 count.value += 1
 }

 return {
 count,
 increment
 }
}

Nuxt 自動導入的特性，現在我們就能在其他元件中使用 useCounter 組合式函數。

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

pages/count.vue

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


<template>
 <div class="flex flex-col items-center">
 <span class="mt-8 text-4xl text-gray-700">{{ count }}</span>
 <button
 class="my-6 rounded-sm bg-sky-600 py-2 px-4 text-base font-medium text-white hover:bg-sky-700 focus:outline-none focus:ring-2 focus:ring-sky-500 focus:ring-offset-2"
 @click="increment"
 >
 增加 1
 </button>
 </div>
</template>

<script setup>
const { count, increment } = useCounter()
</script>

Composables 組合式函數的名稱

前面範例使用的 useCounter() 是 Nuxt 3 從 ./composables/useCounter.js 自動載入的，而且 Nuxt 3 的組合式函數的名稱，有兩種方式會影響使用時的函數名稱，不過也建議在建立組合式函數可以使用 use 作為開頭來加以識別。

1. 使用預設匯出 (Default export)

如果在檔案內使用的是預設匯出，那麼這個組合式函數在使用時，即對應檔案名稱，檔案名稱可以是小寫駝峰式 (Camel case) 或烤肉串 (Kebab case)，例如建立 ./composables/useCounter.js 或 ./composables/use-counter.js 檔案內容如下，使用時組合式函數為小寫駝峰式(Camel case) 名為 useCounter。

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


export default function () {
 const count = ref(0)

 const increment = () => {
 count.value += 1
 }

 return {
 count,
 increment
 }
}

2. 使用具名匯出 (Named export)

如果建立組合式函數時，使用的是有具名的匯出，那麼組合式函數對應的名稱，就不是檔案名稱，而是檔案內 export 出來的名稱。

例如，建立 ./composables/count.js，檔案內容如下，組合式函數名稱就不會是檔案名稱 count，而是具名導出的名稱 useCounter。

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


export const useCounter = () => {
 const count = ref(0)

 const increment = () => {
 count.value += 1
 }

 return {
 count,
 increment
 }
}

Composables 自動載入的規則

composables 目錄下，Nuxt 3 會自動掃描 .js、.ts 與 .vue 副檔名的檔案，但只有最上層的檔案，才會自動的被載入為組合式函數，以下面這個目錄結構為例，只有 ./composables/useCounter.js 才會被正確的自動載入。

1
2
3
4


composables/
├── time/
│ └── useDateFormat.js
└── useCounter.js

下列這種形式，./composables/time/index.js 也能正確的自動載入：

1
2
3
4


composables/
├── time/
│ └── index.js
└── useCounter.js

如果你想讓巢狀的目錄結構下也能被 Nuxt 自動掃描載入，那麼你可以使用下面兩種方法：

一、重新匯出 [推薦]

配置 ./composables/index.js 將目錄下的函數於這裡整理並匯出你需要的作為組合式函數。

二、配置掃描巢狀目錄

修改 nuxt.config.ts 檔案，配置自動載入額外掃描 composables 下的巢狀目錄。

nuxt.config.ts

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


export default defineNuxtConfig({
 imports: {
 dirs: [
 // 掃描 composables 目錄頂層
 'composables',
 // 掃描深度一層的特定檔案
 'composables/*/index.{ts,js,mjs,mts}',
 // 掃描整個 composables 目錄下的檔案
 'composables/**'
 ]
 }
})

不論在 Nuxt 3 或是 Vue 3，組合式函數 (Composables) 都是能幫助你在整個網站可以共用函數的方法，目前也有專案 VueUse 提供了常用與實用的組合式函數集合，能幫我們省去不少開發時間與提升重複使用性，VueUse的介紹請點我前往。

插件 (Plugins)

在開發時，為了不重複造輪子，我們可能會在網路上找看看有沒有現成的套件可以做使用，如果這個套件在 Nuxt 3 沒有專用的模組或插件，那麼我們就只能依照套件的支援與安裝方式嘗試添加至 Nuxt 中使用。這邊將會介紹在 Nuxt 插件的規則與特性，如何建立自己的插件及安裝 Vue 的插件。

說到插件 (Plugins)，Chrome 或 Firefox 等瀏覽器的使用者，一定都聽過也安裝過插件；如果瀏覽器中的功能不夠滿足你的需求，那麼你可以透過安裝插件來嘗試解決你的問題，而插件做的就是幫助你的瀏覽器或是網站，添加一些功能或是配置，做一個擴充的動作。在 Nuxt 3 指的插件，道理也是一樣的，我們可以透過插件來協助我們擴充功能。

Nuxt 3 插件目錄

Nuxt 將自動讀取 plugins 目錄中的檔案並自動載入它們，也因為目錄中的所有插件都是自動載入的，因此不必於 nuxt.config.ts 中再個別配置。

Nuxt 會自動掃描 plugins 目錄下的 .js、.ts 與 .vue 副檔名的檔案，但只有最上層的檔案或最上層目錄下的 index.js 檔案才會被自動載入。

例如，只有 ./plugins/myPlugin.js 及 ./plugins/myPlugin/index.js 會自動的被 Nuxt 載入。

1
2
3
4


plugins/
├── myPlugin/
│ └── index.js
└── myPlugin.js

如何建立插件

當您建立好插件的檔案後，只需要使用預設導出 Nuxt 3 中的 defineNuxtPlugin 方法，傳遞給插件的唯一參數是 nuxtApp，接著就可以在裡頭實作功能。

1
2
3


export default defineNuxtPlugin(nuxtApp => {
 // 可以使用 nuxtApp 來做一些事情
})

初次建立插件時，可以嘗試印出 nuxtApp 參數看看，如下圖，nuxtApp 包含了各種的實例 (Instance)，例如我們要使用 Vue 的 app.use，就可以在 nuxtApp 找到 Vue 的實例 vueApp，並透過 nuxtApp.vueApp.use 來安裝 Vue 的插件。

在插件中使用組合式函數 (Composables)

你也可以在自定義的插件中使用組合式函數，但在插件中存在著一些限制和差異。

插件的載入順序

插件是依照順序來呼叫的，如果你使用的組合式函數，依賴著尚未載入的插件，它將無法正常的執行；除非你很確定插件的載入順序，不然儘量在插件內使用其他會依賴插件或由其他插件所提供的組合式函數。

依賴 Vue 的生命週期

如果插件內所使用的組合式函數，依賴於 Vue 的生命週期，那麼也會無法正常的執行，因為插件只會綁定到 nuxtApp 的實例上，與 Vue 元件內使用組合式函數綁定的元件實例，有所不同。

Automatically Providing Helpers

如果想在 NuxtApp 的實例上提供 helper，我們可以在插件回傳的物件中添加 provide。

例如，我們建立一個插件 ./plugins/myPlugin.js，內容如下：

plugins/myPlugin.js

1
2
3
4
5
6
7


export default defineNuxtPlugin(() => {
 return {
 provide: {
 hello: (msg) => `Hello ${msg}!`
 }
 }
})

調整 ./app.vue 內容：

app.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="my-2 text-6xl font-semibold text-sky-400">{{ title }}</h1>
 <h1 class="my-2 text-6xl font-semibold text-emerald-400">{{ $hello('Jennifer') }}</h1>
 </div>
 </div>
</template>

<script setup>
const { $hello } = useNuxtApp()
const title = $hello('Ryan')
</script>

我們就可以直接在 template 中使用 $hello，這個由插件提供的 Helper，注意這邊要加上錢字符號 $。也可以透過 useNuxtApp 方法取得 NuxtApp 的實例後再使用 $hello。

僅限伺服器端或客戶端中使用

有些插件可能只能在瀏覽器中使用，原因可能是這個插件不需要或無法在伺服器端中執行。

我們可以透過插件的檔案名稱來添加後綴 .client 或 .server，控制伺服器端或客戶端中使用。

Vue 插件與指令

這裡我們嘗試在 Nuxt 3 中使用 Vue 的 vue-gtag 插件，來添加 Google 分析標籤。

Nuxt 3 中使用 vue-gtag 插件

Step 1. 安裝套件

1
2
3


npm install -D vue-gtag-next
# or
# yarn add -D vue-gtag-next

Step 2. 建立 Nuxt 插件

新增 vue-gtag.client.js 檔案，內容如下：

plugins/vue-gtag.client.js

1
2
3
4
5
6
7
8
9


import VueGtag from 'vue-gtag-next'

export default defineNuxtPlugin((nuxtApp) => {
 nuxtApp.vueApp.use(VueGtag, {
 property: {
 id: 'GA_MEASUREMENT_ID'
 }
 })
})

完成效果

可以看見瀏覽器就出現使用 vue-gtag 插件，幫我們自動插入與配置 script 的效果囉！

Nuxt 3 中建立 Vue 指令

在插件中可以取得 Vue 的實例，所以我們也能在插件註冊自定義的指令。

例如，新增 ./plugins/directive.js 檔案，內容如下：

plugins/directive.js

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


export default defineNuxtPlugin((nuxtApp) => {
 nuxtApp.vueApp.directive('focus', {
 mounted(el) {
 el.focus()
 },
 getSSRProps() {
 // you can provide SSR-specific props here
 return {}
 }
 })
})

我們就可以直接使用 v-focus 這個指令來控制元素聚焦的效果。

Nuxt 讓我們可以很輕鬆的建立插件並選擇配置於伺服器端或客戶端，對於使用 UI 框架或元件，更能在插件中直接取得實例來安裝 Vue 的插件與指令，不過呢，目前也有個 RFC 正在徵求意見期待讓 Nuxt 使用 Vue 插件可以更方便容易。

模組 (Modules)

Nuxt 提供了一個模組系統來擴展自身框架的核心，也簡化了整合過程中需要的繁瑣配置。當你想擴展 Nuxt 或 Vue 的功能，雖然 Nuxt 可以通過安裝與配置插件進行功能擴展，但是在多個專案或使用上可能繁瑣耗時或重複性很高的，但如果套件已經有針對 Nuxt 模組做整合，我們就不必從頭開始開發或像安裝插件一樣需要建立與維護這些配置。

Nuxt 3 中插件與模組的差異

Nuxt 模組與 Nuxt 插件的差異在於，模組載入執行的時間點更早，意思是 Nuxt 在啟動伺服器後，首先會依序的載入模組並執行，接續建立 Nuxt 的環境 (Context) 與 Vue 的實例 (Instance)，最後才開始執行 Nuxt 的插件。

因此，Nuxt 模組可以做更多的事情，包含在使用 nuxi dev、nuxi build 啟動或建構 Nuxt 時，可以透過模組來覆蓋模板、配置 webpack 及配置插件等許多任務。

Nuxt 3 安裝使用模組

Nuxt 模組是一個導出異步函數的 JavaScript 檔案，當安裝使用模組時，通常會配置在 nuxt.config.ts 檔案的 modules 中，例如使用 Nuxt Tailwind 模組會添加上 ’@nuxtjs/tailwindcss’。

通常模組的開發人員會提供這些模組應該如何在 modules 屬性來做配置，甚至一些可選用的參數來配置這些模組。

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


export default defineNuxtConfig({
 modules: [
 // 使用套件名稱 (推薦使用)
 '@nuxtjs/example',

 // 載入本地目錄的模組
 './modules/example',

 // 添加模組的選項參數
 ['./modules/example', { token: '123' }]

 // 在行內定義模組
 async (inlineOptions, nuxt) => { }
 ]
})

Nuxt 3 模組列表

你可以在 Explore Nuxt Modules 上尋找由 Nuxt 官方或社群生態所發展建置的模組，Nuxt 的模組通常遵循著官方指南所製，使用時只需要安裝與添加至 nuxt.config 中，基本上就能完成配置。

使用 Nuxt Icon 模組

Nuxt Icon 模組整合了 Iconify 提供多達 100,000 個以上的 Icon 圖示，只要在 Nuxt 中安裝後，我們就可以直接做使用。

Step 1. 安裝套件

1
2
3


npm install -D nuxt-icon
# or
# yarn add -D nuxt-icon

Step 2. 配置使用模組

在 nuxt.config.ts 中的 modules 屬性，添加 Nuxt Icon 模組的名稱 nuxt-icon。

1
2
3


export default defineNuxtConfig({
 modules: ['nuxt-icon']
})

Step 3. 開始使用

依照說明，我們就可以使用 Nuxt Icon 模組，為我們所添加的元件 <Icon>，這個 Icon 元件可以傳入 name 屬性，以此來顯示不同的 Icon 圖示，size 則可以控制圖示的大小。

1
2
3
4
5


<template>
 <div class="flex justify-center">
 <Icon name="logos:nuxt" size="360" />
 </div>
</template>

如何建立 Nuxt 模組

Nuxt Kit 是 Nuxt 官方提供的一個標準和方便的 API 來定義 Nuxt 模組。

通常使用如下程式碼使用 defineNuxtModule 方法來建立一個模組：

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


import { defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
 meta: {
 // 模組的名稱，通常也會對應 NPM 發布的套件名稱
 name: '@nuxtjs/example',
 // 如果有配置這個模組的一些選項，會將其保存在這個設定鍵值下
 configKey: 'sample',
 // 相容性限制 `nuxt.config`
 compatibility: {
 // 為了控制模組的版本相容性，通常會在這裡配置 Nuxt 版本的需求
 nuxt: '^3.0.0'
 }
 },
 // 模組預設的選項
 defaults: {},
 hooks: {},
 async setup(moduleOptions, nuxt) {
 // Nuxt 啟動載入模組後，模組所執行的邏輯會在這裡實作
 }
})

更多 Nuxt 模組的建立指南可以參考 Nuxt 3 - Module Author Guide，這邊就不再贅述，畢竟我們比較常為模組的使用者。

模組的載入

前面我們使用了 Nuxt Icon 模組，我們也可以閱讀一下 Nuxt Icon v0.1.6 模組套件的原始碼。

以下是 Nuxt Icon 模組的 module.ts 檔案。

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


export default defineNuxtModule<ModuleOptions>({
 meta: {
 name: 'nuxt-icon',
 configKey: 'icon',
 compatibility: {
 nuxt: '^3.0.0-rc.9'
 }
 },
 defaults: {},
 setup (_options, nuxt) {
 const { resolve } = createResolver(import.meta.url)

 addComponent({
 name: 'Icon',
 global: true,
 filePath: resolve('./runtime/Icon.vue')
 })
 }
})

Nuxt 的模組使用了一個 defineNuxtModule 方法來定義模組，也可以視為模組的入口點，meta.name 對應的就是模組的名稱，也是我們添加至 modules 屬性所需要的模組名稱。

setup 就是模組載入後執行的函數，可以看到模組使用 addComponent 為我們 Nuxt 添加了一個元件名稱為 Icon，使用的元件檔案來自 ./runtime/Icon.vue。

模組中的 runtime/Icon.vue 為我們封裝了 Iconify 圖示的使用邏輯以及取得 Nuxt 配置的參數等。

透過模組我們可以省去這些繁瑣的封裝與配置，只需要專注在配置模組與開發上面。

模組與插件其實還是存在著載入執行順序與使用情境上的差異性，以 Nuxt 來說，通常 Nuxt 的插件會是用來封裝及使用 Vue 中會使用到的插件與或套件；而 Nuxt 的模組，會將需要繁瑣配置的套件或插件來與 Nuxt 進行整合與封裝，不論是透過第三方插件或模組，這都將使 Nuxt 在開發與擴充上擁有更多的可能性。

中間件目錄 (Middleware Directory)

在 Vue 的專案內我們的頁面通常由 Vue Router 來控制路由及導航，Vue Router 提供了導航守衛 (Navigation Guards) 的 Hook API，讓我們可以在全域、路由甚至是元件中，來控制路由跳轉或取消的方式來守護我們的路由，不讓其隨意導航至特定頁面。Nuxt 3 提供了一個中間件的目錄，讓我們可以製作路由的中間件，來實作出類似導航守衛的效果。

導航守衛就是在訪問頁面之前，會攔截你的路由請求並執行自訂的驗證邏輯，依據驗證的成功與否，准予放行跳轉至路由頁面，抑或是取消訪問該路由，再依照不同處理方式進行中斷或重導向至特定路由頁面。

導航守衛在實務上常見的使用情境，就是拿來做頁面訪問的權限驗證，例如，只有管理員才能訪問 /admin 路由下的頁面，我們可能就會添加攔截的 hook 來驗證使用者是否登入及夾帶的 Token 或 Role 是否有權限可以瀏覽，如果驗證成功就准予瀏覽管理員相關頁面，否則，將路由頁面導回至首頁、登入頁或錯誤頁面，如同一個守衛在路由之間進行把關驗證權限。

我們以 Vue Route v4 來舉例，Vue Route 提供了以下三種情況下可以使用的 hook，分別是在全域、路由或是元件中：

全域

全域前置守衛 (Global Before Guards)

當全域守衛 hook 添加好之後，每次導航至不同路由時，都會攔截以異步的方式執行相對應的處理邏輯。

全域守衛提供了 router.beforeEach() hook 可以在進入任何一個路由前進行攔截處理，當導航觸發時就會依照建立的順序做呼叫，因為是異步函數解析執行，所以在所有的守衛 resolve 之前，會一直處於 pending 的狀態。

全域解析守衛 (Global Resolve Guards)

而同樣屬於全域守衛的 router.beforeResolve() hook 會在所有元件內的導航守衛、路由都被解析及執行完畢後才執行，也就是說這個 router.beforeResolve() 呼叫的時間點晚於 router.beforeEach()。

全域後置 Hooks (Global After Hooks)

與 router.beforeEach() hook 相反，全域後置 hooks 提供的 router.afterEach() Hook 會是在路由跳轉結束後才觸發，在這裡路由已經完成跳轉，路由本身也不會再被更動，這個 hook 通常用於分析類或設置頁面相關的資訊等輔助型的功能很有幫助。

路由獨有守衛 (Per-Route Guard)

與 router.beforeEach() 不同，我們可以為每一個路由添加 beforeEnter() hook，來達到每一個路由頁面有不同的執行方法，同時也只會在不同的路由導航中切換才會觸發。

元件內的守衛

在元件的內部中，也提供三種 hooks 分別為：

beforeRouteEnter(): 在路由進入並渲染這個元件之前呼叫，所以還沒有元件的實體可以操作使用。
beforeRouteUpdate(): 目前的路由改變，而且還處於同一個元件中時呼叫。
beforeRouteLeave(): 當導航準備離開時且沒有使用到這個元件時呼叫。

導航守衛 (Navigation Guards) 在導航出發後的 hook 觸發順序如下圖：

Nuxt 3 路由中間件

Nuxt 3 中提供了一個路由中間件的框架，我們可以在專案下建立名為 middleware 目錄，在這個目錄下我們可以建立中間件，並讓整個 Nuxt 頁面或特定的路由做使用，也可以在頁面中添加，這個中間件可以理解為 Vue Router 中的導航守衛 (Navigation Guards)，同樣有 to 與 from 參數用以在導航至特定路由之前驗證權限或執行商業邏輯等。

路由中間件格式

當我們想要建立路由中間件時，可以在 Nuxt 專案的 middleware 目錄下建立檔案，並預設匯出一個由 defineNuxtRouteMiddleware() 定義的函數，例如：

1
2
3
4
5
6


export default defineNuxtRouteMiddleware((to, from) => {
 if (to.params.id === '1') {
 return abortNavigation()
 }
 return navigateTo('/')
})

路由中間件能接收目前的路由 to 與下一個路由 from 做為參數，如同 Vue Router 的導航守衛，以此我們就可以來做一些判斷與驗證操作。

路由中間件的回傳

Nuxt 提供了兩個全域的 helpers，可以直接從中間件回傳：

navigateTo(to, options)

在插件或中間件中重新定向到給定的路由。也可以直接呼叫它進行頁面導航。

navigateTo 參數依序為：

to： RouteLocationRaw | undefined | null
options： { replace: boolean, redirectCode: number, external: boolean }

abortNavigation(err)

可以在中間件中回傳 abortNavigation() 來中止導航，並可以選擇是否傳入錯誤訊息。

abortNavigation 參數為：

err?: string | Error

與 Vue Router 中的導航守衛稍有不同，在 Nuxt 的中間件中可以使用 navigateTo 與 abortNavigation 來決定導航至新的路由或終止導航，如果中間件沒有回傳任何東西，則表示不阻塞導航，如果有下一個中間件，則而移往下一個功能做執行，或者完成路由導航。

nothing - 不阻塞導航並且會移動到下一個中間件功能。
如果有的話，或者完成路由導航 return navigateTo(’/’) 或 return navigateTo({ path: ‘/’ }) - 重定向到給定路徑。

如果使用 navigateTo() 重定向是發生在伺服器端，則將 HTTP Status Code 設置為暫時重定向狀態碼 302 Found。

如果使用 navigateTo() 並夾入 options.redirectCode 屬性，例如 return navigateTo('/', { redirectCode: 301 })，發生的重定向在伺服器端，將 HTTP Status Code 設置為永久重定向狀態碼 301 Moved Permanently。

路由中間件的種類

在 Nuxt 中路由中間件分為以下三種：

匿名或者是行內的路由中間件

不需要建立檔案，通常在路由頁面中使用 definePageMeta() 來定義的中間件，就屬於這種類型。

例如，直接定義一個匿名的中間件在頁面元件中使用：

1
2
3
4
5
6
7


<script setup>
definePageMeta({
 middleware: defineNuxtRouteMiddleware(() => {
 console.log(`[匿名中間件] 我是直接定義在頁面內的匿名中間件`)
 })
})
</script>

具名的路由中間件

在 middleware 目錄下所建立的中間件，當在頁面使用 definePageMeta() 來指定使用具名的中間件時，將透過異步來自動載入。具名的路由的名稱被規範為是烤肉串式 (Kebab case) 命名。

例如，建立一個 ./middleware/random-redirect.js 中間件檔案：

middleware/random-redirect.js

1
2
3
4
5
6
7
8


export default defineNuxtRouteMiddleware(() => {
 if (Math.random() > 0.5) {
 console.log(`[來自 random-redirect 中間件] 重新導向至 /haha`)
 return navigateTo('/haha')
 }

 console.log(`[來自 random-redirect 中間件] 沒發生什麼特別的事情～`)
})

當我們要使用這個中間件時，可以在頁面中使用 definePageMeta() 並傳入 middleware 屬性，來添加路由中間件。

1
2
3
4
5


<script setup>
definePageMeta({
 middleware: 'random-redirect'
})
</script>

如果中間件有多個，你也可以使用陣列來傳入多個中間件，並且會依序執行這些路由中間件。

1
2
3
4
5


<script setup>
definePageMeta({
 middleware: ['random-redirect', 'other']
})
</script>

當我們在頁面中添加這個中間件後，在切換到這個路由頁面時，約有一半的機會，會被導航至 /haha 頁面。

全域的路由中間件

在具名的中間件的檔名添加後綴 .global，如 auth.global.js，這個路由中間件將會被自動載入，並在每次導航變更時自動執行。

例如，我們建立一個 ./middleware/always-run.global.js 中間件檔案，內容如下：

middleware/always-run.global.js

1
2
3


export default defineNuxtRouteMiddleware((to, from) => {
 console.log(`[全域中間件] to: ${to.path}, from: ${from.path}`)
})

這個全域的路由中間件，將會在每一次導航切換頁面時執行。

動態添加路由中間件

你可以使用 addRouteMiddleware() 輔助函數來手動添加全域或命名路由中間件，例如在插件中。

1
2
3
4
5
6
7
8
9


export default defineNuxtPlugin(() => {
 addRouteMiddleware('global-test', () => {
 console.log('這個是由插件添加的全域中間件，並將在每次路由變更時執行')
 }, { global: true })

 addRouteMiddleware('named-test', () => {
 console.log('這個是由插件添加的具名中間件，並將會覆蓋任何現有的同名中間件')
 })
})

在 Nuxt 中我們可以使用所提供的中間件框架，來建立路由頁面中的中間件，而路由中間件會在到特定路由之前執行想要運行的邏輯，對於驗證權限等非常方便，也正是實現導航守衛 (Navigation Guards) 的方式。這裡我們主要講述的路由中間件，也將會與我們後面會提到的伺服器端的中間件有所不同，雖然名稱相似但與 Nitro 啟動時執行的伺服器中間件完全不同。

Server API 與 Nitro Engine

這裡會先介紹一下 Nitro Engine 是什麼東西，Nitro 可能不多人聽過但與 Nuxt 3 息息相關，Nitro 伺服器引擎除了有跨平台支援與多種強大的功能外，更包含了 API 路由的支援，意思就是我們可以直接在基於 Nitro 的 Nuxt 3 上直接開發由後端處理的邏輯或與資料庫互動，再將結果回傳至前端，實作出 Server API。

Nitro Engine

在開始建置 Sever API 之前，先來介紹一下 Nitro 伺服器引擎，Nuxt 3 的一大特點就是採用了一個名為 Nitro 的伺服器引擎 (Server Engine)，Nitro 基於 rollup 與 h3，為達高效能與可移植性目標而建構的最小 HTTP 框架。

Nitro 提供了以下多種功能特色，使得 Nuxt 更佳完善與強大，如同官網所說 Nitro 讓 Nuxt 直接解鎖了新的全端能力。

快速的開發體驗：開箱即用的特性，無需任何配置，就可以啟動具有 hot module reloading 的開發伺服器，寫完程式碼存檔後，就能讓伺服器載入新的程式邏輯。
基於檔案系統的路由：我們只需要專注在建立伺服器的目錄與頁面，就能擁有自動載入與路由的效果。
可移植且便攜：基本上 Nuxt 3 使用的依賴套件都在 package.json 檔案的 devDependencies 中，建構正式環境的網站時，Nitro 自動拆分的程式碼與打包出來的 .output 目錄不再需要安裝依賴套件，意味著不再有 node_modules，因此部署時更輕便好攜。
混合模式：透過**混合模式 (Hybrid mode)**可以將一部分頁面預渲染產生出靜態頁面，部分頁面是動態的在伺服器或客戶端渲染，讓每個路由頁面有不同的靜態或動態甚至擁有快取規則，這將讓 Nuxt 3 的通用渲染 (Universal Rendering) 方式更進一步成混合渲染 (Hybrid Rendering) 也能結合無伺服器 (Serverless) 來配置混合模式。

看到這裡，可以發現 Nuxt 3 與 Nitro 都下了非常大的功夫，雖然還有些功能尚未穩定與需要改進的地方，但是已經為開發上提供了強大支援與良好的體驗，更多特性與細節可以參考 Nuxt 3 - Server Engine 或 Nitro 官方。

Nuxt 3 的 Server 目錄

我們可以透過 Nuxt 3 專案下的 server 目錄來建立具有 hot module reloading 支援的 Server API 與後端處理邏輯。

server 目錄常用的有下面三個子目錄：

在這個目錄的檔案，將會由 Nuxt 自動載入並產生 /api 開頭的路由並對應檔案名稱，例如建立 ./server/api/hello.js，就會擁有 /api/hello 的路由對應這個 API，可以使用 http://localhost:3000/api/hello 訪問該路由。

routes

在這個目錄的檔案，將會由 Nuxt 自動載入並產生對應檔案名稱的路由，例如建立 ./server/routes/world.js，就會擁有 /world 的路由對應這個 API，可以使用 http://localhost:3000/world 訪問該路由。

middleware

在這個目錄的檔案，會被 Nuxt 自動載入，並添加至伺服器中間件，並在每個 Request 進入伺服器 API 的路由前執行。

建立第一個伺服器 API

Nuxt 會自動掃描 server 目錄中的檔案結構，建立 Server API 時通常以 .js 或 .ts 作為副檔名，並依照官方建議，每個檔案都應該預設匯出 defineEventHandler() 函數，並在其 handler 內實作處理邏輯。

handler 接收了一個 event 參數，用來解析請求的資料，並可以直接回傳一個字串、JSON、Promise 或者使用 event.res.end() 送出請求回應。

舉例來說，我們建立一個檔案 ./server/api/hello.js，內容如下：

server/api/hello.js

1
2
3
4
5
6


export default defineEventHandler(() => {
 return {
 ok: true,
 data: 'Hello World!'
 }
})

如同 pages 頁面路由一樣，在 ./server/api 目錄下會基於檔案系統結構來產生出相對應的路由，並且會添加一個路由前綴 /api，現在，可以使用 http://localhost:3000/api/hello 訪問該路由，看見回傳的 JSON 資料。

伺服器路由

基於檔案的路由

前面的例子有提到，Server API 的路由是基於檔案結構來自動產生，如果你不想要有 /api 的前綴，可以將 API 處理邏輯檔案，放置在 ./server/routes 目錄中。

舉例來說，以下的檔案結構會產生兩個可以訪問的伺服器 API 路由，分別為 /api/hello 及 /api/world。

1
2
3
4
5
6


nuxt-app/
└── server/
 ├── api/
 │ └── hello.js
 └── routes/
 └── world.js

匹配路由參數

將檔案名稱添加中括號 []，其中放入欲設定的參數名稱，以此來處理動態路由匹配。舉例來說，建立 ./server/api/hello/[name].js 檔案，內容如下：

server/api/hello/[name].js

1
2
3
4


export default defineEventHandler((event) => {
 const { name } = event.context.params
 return `Hello, ${name}!`
})

在 handler 內就能使用 event.context.params 來訪問 name 路由參數。

匹配 HTTP 請求方法 (HTTP Request Method)

我們可以添加 .get、.post、.put 或 .delete 等檔案名稱後綴，來匹配對應的 HTTP request methods。

新增 server/api/test.get.js，內容如下：

server/api/test.get.js

1
2
3
4
5
6


export default defineEventHandler(() => {
 return {
 ok: true,
 message: '測試 [GET] /api/test'
 }
})

新增 server/api/test.post.js，內容如下：

server/api/test.post.js

1
2
3
4
5
6


export default defineEventHandler((event) => {
 return {
 ok: true,
 message: '測試 [POST] /api/test'
 }
})

我們使用 Postman 來打這兩隻 API，可以看到使用不同的 HTTP Request Method，就會匹配至對應後綴檔案中的 handler 進行處理。

[GET] /api/test

[POST] /api/test

從上面的例子，我們建立了 test.get.js 與 test.post.js 檔案，分別對應了 GET 與 POST 方法，如果同一個路由使用了其他方法而無法匹配處理的檔案時，則會回傳 HTTP 狀態碼 405 Method Not Allowed 表示錯誤。

匹配包羅萬象的路由 (Catch-all Route)

你可以建立 […].js 的檔案，來將所有不匹配的路由交由這個 handler 作處理。

例如，建立 ./server/api/catch-all/[…].js，將可以匹配 /api/catch-all/x、/api/catch-all/x/y…等 /catch-all 下所有層級的路由。

server/api/catch-all/[…].js

1
2
3
4
5
6
7
8
9


export default defineEventHandler((event) => {
 return {
 ok: true,
 data: {
 url: event.req.url
 },
 message: '/api/catch-all 下不匹配的路由都會進入這裡'
 }
})

建立 ./server/api/[…].js 檔案如下，將可以接手所有 /api 下無法匹配的路由。

server/api/[…].js

1
2
3
4
5
6
7
8
9


export default defineEventHandler(() => {
 return {
 ok: true,
 data: {
 url: event.req.url
 },
 message: '/api 下不匹配的路由都會進入這裡'
 }
})

下圖示範中，當我們輸入的路由如果沒有辦法處理，將會被 [...].js 所匹配，以此我們可以來實作返回、重新導向或錯誤頁面。

伺服器中間件

Nuxt 會自動載入 ./server/middleware 中的檔案，並添加至伺服器中間件，伺服器的中間件與路由中間件不同的是，pages 路由頁面的請求是不會執行伺服器中間件。

伺服器的中間件會在每個 Request 進入伺服器 API 的路由前執行，通常用來添加或檢查請求的標頭 (headers)、記錄請求或擴展調整請求的物件。

伺服器中間件的處理邏輯，不應該回傳任何內容，也不應中斷或直接回應請求，伺服器中間件應該僅檢查、擴展請求上下文或直接拋出錯誤。

舉理來說，你可以新增 ./server/middleware/log.js 用來記錄每個請求的 URL。

server/middleware/log.js

1
2
3


export default defineEventHandler((event) => {
 console.log('New request: ' + event.req.url)
})

或者，新增 ./server/middleware/auth.js 用來解析請求或擴展請由物件。

server/middleware/auth.js

1
2
3


export default defineEventHandler((event) => {
 event.context.auth = { username: 'ryan' }
})

伺服器插件

Nuxt 會自動掃描並載入 ./server/plugins 目錄下的檔案，並將他們註冊為 Nitro 的插件，在 Nitro 啟動時，這些插件將會在伺服器載入並執行，插件允許擴展 Nitro 執行時的行為及連接到生命週期的事件。

更多細節可以參考 Nitro Plugins。

伺服器通用功能

Nuxt 中伺服器的路由，是由 unjs/h3 所提供，h3 內建一些方便實用的 helpers，可以參考 Available H3 Request Helpers。

伺服器路由常用的 HTTP 請求處理

處理 HTTP 請求中的 Body

1
2
3
4
5
6
7


export default defineEventHandler(async (event) => {
 const body = await readBody(event)
 return {
 ok: true,
 data: body
 }
})

可以使用 readBody(event) 來解析請求中的 Body，注意 readBody() 是一個異步函數，記得 await 等待解析完成。

處理 URL 中的查詢參數 (Query Parameters)

可以使用 getQuery(evnet) 來解析查詢參數。

1
2
3
4
5
6
7
8
9


export default defineEventHandler((event) => {
 const query = getQuery(event)
 return {
 ok: true,
 data: {
 name: query.name
 }
 }
})

當請求 URL 為 /api/query?name=ryan，可以解析出查詢參數 query.name。

可以使用 parseCookies(event) 來解析請求所夾帶的 Cookie。

1
2
3
4
5
6
7
8
9


export default defineEventHandler((event) => {
 const cookies = parseCookies(event)
 return {
 ok: true,
 data: {
 cookies
 }
 }
})

我透過瀏覽器的開發工具，手動添加了一組 cookie 名為 token，Server API 可以透過 parseCookies() 來解析出瀏覽器自動夾帶的 cookie。

進階使用範例

Nitro 配置

你可以在 nuxt.config.ts 中使用 nitro 屬性來配置 Nitro 設定。

nuxt.config.ts

1
2
3
4


export default defineNuxtConfig({
 // https://nitro.unjs.io/config
 nitro: {}
})

使用巢狀路由

你可以直接使用 h3 的 createRouter() 方法來建立巢狀路由。

1
2
3
4
5
6
7


import { createRouter } from 'h3'

const router = createRouter()

router.get('/', () => 'Hello World')

export default router

伺服器儲存

Nitro 提供了一個跨平台的儲存層，你可以 Nitro 的配置中設定 storage 屬性，來配置額外的儲存掛載位置，官網提供了一個使用 Redis 的範例。

更多 Nitro 伺服器的設定與使用可以參考官網。

Nitro 伺服器引擎將 Nuxt 3 提升至另一個境界，不僅功能強大且讓開發中擁有不錯的體驗，伺服器路由更是能在後端直接處理邏輯實作 Server API，而接下來將介紹如何在 Nuxt 打 API 取得資料。

資料獲取 (Data Fetching)

Nuxt 提供了 $fetch 及四種組合式函數 (Composables)，來進行資料獲取，也就是說，我們不需要再額外安裝任何 HTTP Client ，如 axios 來發送 HTTP 請求，因為 Nuxt 本身就自帶了打 API 的方法，而且在頁面、元件或插件中都能直接呼叫做使用，非常方便。

首先，我們先介紹一下 $fetch 這個由 Nuxt 提供使用 ohmyfetch 套件所封裝的 helper，$fetch 可以在 Nuxt 中用於發送 HTTP 請求。

如果在伺服器端渲染的期間，呼叫 $fetch 打內部 API 路由，也就是打我們自己在 ./server 下實作的後端 API，那麼因為使用 $fetch 的關係，Nuxt 會模擬請求，改由直接呼叫內部 API 的處理函數，這樣就能節省額外的 API 呼叫。

使用的方法，如下：

1

$fetch(url, options)

我們可以使用 $fetch(’/api/count’) 建立一個 GET 請求，發送至 /api/count 後會返回一個 Promise，完成後我們就可以接收回傳的資料。

$fetch 的 options 的參數及建立攔截器等功能可以參考 ohmyfetch，不過呢，我們還會使用 Nuxt 提供的組合函數結合 $fetch 來打 API。

接下來我們就來依序介紹，如何使用 Nuxt 提供的四種組合函數來從 API 獲取資料。

useAsyncData

這個 useAsyncData() 組合函數，其實不是傳入 URL 直接呼叫就會發出 API 請求，而是 Nuxt 可以透過這個函數來添加異步請求資料的邏輯。

useAsyncData 組合函數能接收 key、handler 與 options，其中 handler 會來添加請求異步資料的邏輯。當我們在頁面、元件和插件中呼叫 useAsyncData，並等待回傳的 Promise，我們的頁面或元件的渲染將會阻塞路由載入至 handler 異步邏輯處理完畢後才會繼續執行，也就是說，整個頁面元件將會等待所有使用 useAsyncData 呼叫的 API 回傳完成後才會開始進行渲染。

舉個例子，我們新增一個 Server API，並稍微添加一下延遲，模擬 API 約需要處理 2 秒才回傳資料，./server/api/count.js 內容如下：

server/api/count.js

1
2
3
4
5
6
7
8
9


let counter = 0

export default defineEventHandler(async () => {
 await new Promise((resolve) => setTimeout(resolve, 2 * 1000)) // 等待 2 秒

 counter += 1

 return JSON.stringify(counter)
})

新增一個路由頁面，./pages/count/useAsyncData.vue 內容如下：

pages/count/useAsyncData.vue

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


<template>
 <div class="my-24 flex flex-col items-center">
 <p class="text-4xl text-gray-600">瀏覽次數</p>
 <span class="mt-4 text-6xl font-semibold text-sky-400">{{ data }}</span>
 </div>
</template>

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

當我們瀏覽 /count/useAsyncData 時，會打 /api/count 這隻 API，並等待返回後才開始渲染元件。

因為瀏覽 http://localho:3000/count/useAsyncData 時，第一次都是由後端渲染處理，看不太出導航有被阻塞的效果，建議可以添加一下路由連結來進行導航，就可以發現差異。

當我們從首頁，由客戶端導航至 /count/useAsyncData 頁面時，會發現網址的路由已經變化，但是頁面約等了一會兒才渲染出現，這就是因為頁面中使用了 useAsyncData() 來獲取資料，await 將阻塞整個頁面元件的載入與渲染，直至 API 處理完畢回傳後才開始載入路由渲染元件。

useAsyncData() 共有兩種呼叫時使用參數差異，可以選擇是否傳入第一個參數 key，所傳入參數的類型如下

 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
33
34


function useAsyncData(
 handler: (nuxtApp?: NuxtApp) => Promise<DataT>,
 options?: AsyncDataOptions<DataT>
): AsyncData<DataT>

function useAsyncData(
 key: string,
 handler: (nuxtApp?: NuxtApp) => Promise<DataT>,
 options?: AsyncDataOptions<DataT>
): Promise<AsyncData<DataT>>


type AsyncDataOptions<DataT> = {
 server?: boolean
 lazy?: boolean
 default?: () => DataT | Ref<DataT> | null
 transform?: (input: DataT) => DataT
 pick?: string[]
 watch?: WatchSource[]
 initialCache?: boolean
 immediate?: boolean
}

interface RefreshOptions {
 _initial?: boolean
}

type AsyncData<DataT, ErrorT> = {
 data: Ref<DataT | null>
 pending: Ref<boolean>
 execute: () => Promise<void>
 refresh: (opts?: RefreshOptions) => Promise<void>
 error: Ref<ErrorT | null>
}

useAsyncData() 傳入的參數

key：唯一鍵，可以確保資料不會重複的獲取，也就是如果 Key 相同便不會再發送相同的請求，除非重新整理頁面由後端再次渲染獲取，或呼叫 useAsyncData 回傳的 refresh() 函數重新取得資料。
handler：回傳異步請求資料的處理函數，打 API 或加工的異步邏輯都可以在這裡處理。
options：
- server：是否在伺服器端獲取資料，預設為 true。
- lazy：是否於載入路由後才開始執行異步請求函數，預設為 false，所以會阻止路由載入直到請求完成後才開始渲染頁面元件。
- default：當傳入這個 factory function，可以將異步請求發送與回傳解析前，設定資料的預設值，對於設定 lazy: true 選項特別有用處，至少有個預設值可以使用及渲染顯示。
- transform：修改加工 handler 回傳結果的函數。
- pick：handler 若回傳一個物件，只從中依照需要的 key 取出資料，例如只從 JSON 物件中取的某幾個 key 組成新的物件。
- watch：監聽 ref 或 reactive 響應式資料發生變化時，觸發重新請求資料，適用於資料分頁、過濾結果或搜尋等情境。
- initialCache：預設為 true，當第一次請求資料時，將會把有效的 payload 快取，之後的請求只要是相同的 key，都會直接回傳快取的結果。
- immediate：預設為 true，請求將會立即觸發。

useAsyncData() 的回傳值

data：傳入異步函數的回傳結果。
pending：以 true 或 false 表示是否正在獲取資料。
refresh / execute：一個函數，可以用來重新執行 handler 函數，回傳新的資料，類似重新整理、重打一次 API 的概念。預設情況下 refresh() 執行完並回傳後才能再次執行。
error：資料獲取失敗時回傳的物件。

看到這裡，我們再重新閱讀與解釋 useAsyncData() 的範例

1
2
3
4
5
6


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

呼叫 useAsyncData() 並不是直接幫我們送出 HTTP 請求，而是在 handler 內使用 $fetch 來打 API，只是 useAsyncData() 組合式函數，封裝了更多打 API 時可以使用的方法與參數，來因應不同的使用情境。當然如果想要，你也可以使用其他套件來替換 $fetch 但可能就沒辦法享受它所帶來的好處。

useFetch

這個組合式函數將 useAsyncData 和 $fetch 進行包裝，當使用這個函數時它會根據 URL 和 fetch 的選項來自動產生 useAsyncData 需要的參數 key，如果呼叫的 API 是伺服器端所提供的，也會自動根據伺服器 API 路由來為請求提供類型提示，並推斷 API 的回傳類型。

useFetch() 所傳入參數的類型如下

 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


function useFetch(
 url: string | Request | Ref<string | Request> | () => string | Request,
 options?: UseFetchOptions<DataT>
): Promise<AsyncData<DataT>>

type UseFetchOptions = {
 key?: string
 method?: string
 params?: SearchParams
 body?: RequestInit['body'] | Record<string, any>
 headers?: { key: string, value: string }[]
 baseURL?: string
 server?: boolean
 lazy?: boolean
 immediate?: boolean
 default?: () => DataT
 transform?: (input: DataT) => DataT
 pick?: string[]
 watch?: WatchSource[]
 initialCache?: boolean
}

type AsyncData<DataT> = {
 data: Ref<DataT>
 pending: Ref<boolean>
 refresh: () => Promise<void>
 execute: () => Promise<void>
 error: Ref<Error | boolean>
}

useFetch() 傳入的參數

url：要獲取資料的 URL 或 API Endpoint。
options：(繼承自 unjs/ohmyfetch 選項與 AsyncDataOptions)
- method：發送 HTTP 請求的方法，例如 GET、POST 或 DELETE 等。
- params：查詢參數 (Query params)。
- body：請求的 body，可以傳入一個物件，它將自動被轉化為字串。
- headers：請求的標頭 (headers)。
- baseURL：請求的 API 路徑，基於的 URL。
options：(繼承自 useAsyncData 的選項)
- key：唯一鍵，可以確保資料不會重複的獲取，也就是如果 Key 相同便不會再發送相同的請求，除非重新整理頁面由後端再次渲染獲取，或呼叫 useAsyncData 回傳的 refresh() 函數重新取得資料。
- server：是否在伺服器端獲取資料，預設為 true。
- lazy：是否於載入路由後才開始執行異步請求函數，預設為 false，所以會阻止路由載入直到請求完成後才開始渲染頁面元件。
- immediate：預設為 true，請求將會立即觸發。
- default：當傳入這個 factory function，可以將異步請求發送與回傳解析前，設定資料的預設值，對於設定 lazy: true 選項特別有用處，至少有個預設值可以使用及渲染顯示。
- transform：修改加工 handler 回傳結果的函數。
- pick：handler 若回傳一個物件，只從中依照需要的 key 取出資料，例如只從 JSON 物件中取的某幾個 key 組成新的物件。
- watch：監聽 ref 或 reactive 響應式資料發生變化時，觸發重新請求資料，適用於資料分頁、過濾結果或搜尋等情境。
- initialCache：預設為 true，當第一次請求資料時，將會把有效的 payload 快取，之後的請求只要是相同的 key，都會直接回傳快取的結果。

useFetch() 的回傳值

data：傳入異步函數的回傳結果。
pending：以 true 或 false 表示是否正在獲取資料。
refresh / execute：一個函數，可以用來重新執行 handler 函數，回傳新的資料，類似重新整理、重打一次 API 的概念。預設情況下 refresh() 執行完並回傳後才能再次執行。
error：資料獲取失敗時回傳的物件。

舉個例子，我們新增一個 Server API，./server/api/about.js 內容如下：

server/api/about.js

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


let counter = 0

export default defineEventHandler(() => {
 counter += 1

 return {
 name: 'Ryan',
 gender: '男',
 email: 'ryanchien8125@gmail.com',
 counter
 }
})

新增一個路由頁面，./pages/about/useFetch.vue 內容如下：

pages/about/useFetch.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>
 <div class="my-24 flex flex-col items-center">
 <p class="text-2xl text-gray-600">
 請求狀態:
 {{ pending ? '請求中' : '完成' }}
 </p>
 <span v-if="error" class="mt-4 text-6xl text-gray-600">是否錯誤: {{ error }}</span>
 <span class="mt-4 text-2xl text-gray-600">回傳資料:</span>
 <p class="mt-4 text-3xl font-semibold text-blue-500">{{ data }}</p>
 <button
 class="mt-6 rounded-sm bg-blue-500 py-3 px-8 text-xl font-medium text-white hover:bg-blue-600 focus:outline-none focus:ring-2 focus:ring-blue-400 focus:ring-offset-2"
 @click="refresh"
 >
 重新獲取資料
 </button>
 </div>
</template>

<script setup>
const { data, pending, error, refresh } = await useFetch('/api/about', {
 pick: ['name', 'counter']
})
</script>

透過 useFetch() 我們能更簡單的發送 API 請求，並能得到狀態與重新獲取資料的函數，甚至在第一次進入頁面時，利用 $fetch 可以直接呼叫伺服器 API 函數的特性來降低 API 的請求次數。

攔截器

我們也可以透過 $fetch 提供的選項來設置攔截器。

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


const { data, pending, error, refresh } = await useFetch('/api/auth/login', {
 onRequest({ request, options }) {
 // 設定請求時夾帶的標頭
 options.headers = options.headers || {}
 options.headers.authorization = '...'
 },
 onRequestError({ request, options, error }) {
 // 處理請求時發生的錯誤
 },
 onResponse({ request, response, options }) {
 // 處理請求回應的資料
 return response._data
 },
 onResponseError({ request, response, options }) {
 // 處理請求回應發生的錯誤
 }
})

useLazyAsyncData

預設的情況下，useAsyncData() 的 options.lazy 為 false，意思是，預設得情況下，當進入路由後，會開始執行異步請求函數，並會會阻止路由載入元件等，直到請求完成後才開始渲染頁面元件。

useLazyAsyncData() 則是 options.lazy 預設為 true 的封裝，也就是請求資料時它將不會阻塞，並讓頁面繼續渲染元件。

舉個例子，我們新增一個 Server API，並稍微添加一下延遲，模擬 API 約需要處理 2 秒才回傳資料，./server/api/count.js 內容如下：

server/api/count.js

1
2
3
4
5
6
7
8
9


let counter = 0

export default defineEventHandler(async () => {
 await new Promise((resolve) => setTimeout(resolve, 2000)) // 等待 2 秒

 counter += 1

 return JSON.stringify(counter)
})

新增一個路由頁面，./pages/count/useLazyAsyncData.vue 內容如下：

pages/count/useLazyAsyncData.vue

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


<template>
 <div class="my-24 flex flex-col items-center">
 <p class="text-6xl text-gray-600">瀏覽次數</p>
 <span class="mt-4 text-9xl font-semibold text-sky-400">{{ data }}</span>
 <div class="mt-8">
 <NuxtLink to="/count">回首頁</NuxtLink>
 </div>
 </div>
</template>

<script setup>
const { data } = useLazyAsyncData('count', () => $fetch('/api/count'))
</script>

可以發現，我們使用 useLazyAsyncData() 後，會與前面使用 useAsyncData() 的效果不一樣，會先渲染出元件，即看到的文字「瀏覽次數」，並再 API 回傳後才響應資料重新渲染數值。

透過 default 選項可以來建立 API 回傳前的預設值，在 options.lazy 為 true 的情況下，都建議設定一下預設值，可以讓使用者體驗更好一些。

添加 default 選項，./pages/count/useLazyAsyncData.vue 內容如下：

pages/count/useLazyAsyncData.vue

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


<template>
 <div class="my-24 flex flex-col items-center">
 <p class="text-6xl text-gray-600">瀏覽次數</p>
 <span class="mt-4 text-9xl font-semibold text-sky-400">{{ data }}</span>
 <div class="mt-8">
 <NuxtLink to="/">回首頁</NuxtLink>
 </div>
 </div>
</template>

<script setup>
const { data } = useLazyAsyncData('count', () => $fetch('/api/count'), {
 default: () => '-'
})
</script>

在 API 請求回來前，預設值會是 -。

useLazyFetch

如同 useLazyAsyncData 所描述，useLazyFetch 則是 useFetch 的 options.lazy 選項預設為 true 的封裝。

重新獲取資料

前面有提到我們可以使用 refresh() 來重新獲取具有不同查詢參數的資料。

refreshNuxtData

你也可以透過 refreshNuxtData 來使 useAsyncData、useLazyAsyncData、useFetch 與 useLazyFetch 的快取失效，再觸發刷新資料。

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


<template>
 <div>
 {{ pending ? 'Loading' : count }}
 </div>
 <button @click="refresh">Refresh</button>
</template>

<script setup>
const { pending, data: count } = useLazyAsyncData('count', () => $fetch('/api/count'))

const refresh = () => refreshNuxtData('count')
</script>

Nuxt 已經為我們封裝好可以打 API 的組合函數，用起來也相當簡單方便，照著官網範例及 ohmyfetch 套件的說明，相信很快就能上手。

狀態管理 (State Management)

Vue 3 父子元件間資料傳遞與讀寫或是跨元件間的狀態共享，可以選擇使用 Props / Emit、Provide / Inject 或 Vuex store 來處理，這三種資料流都不大一樣，我們也會依據情境來決定狀態管理的方式。這邊會針對 Nuxt 3 所提供的組合式函數 useState 來講述元件間的共享狀態，應該如何做定義，以及使用 Pinia 替代 Vuex 來做狀態管理。

Hydration

首先，我們先來看一個例子，建立 ./pages/random.vue 內容如下：

pages/random.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">
 <span class="text-9xl font-semibold text-sky-400">{{ count }}</span>
 </div>
 </div>
</template>

<script setup>
const count = ref(Math.round(Math.random() * 1000))
</script>

頁面呈現出，每次重新整理頁面，頁面會顯示新的亂數：

細心你的可能會發現，每次重整頁面，數字好像變化了兩次，圖中數字停留在 517，重新整理網頁後竟然先變成了 163 後再變成 101。

這個現象其實是伺服器端渲染後與客戶端再次渲染所導致的。講的白話一點就是，因為 Nuxt 預設的渲染模式 Universal Rendering 在 SSR 時期，將 random.vue 內容於伺服器端渲染完成後亂出產生出 163 作為初始值，意即 const count = ref(163)，所以網頁先顯示了 163 這個數字，同時，瀏覽器的背景也正在下載客戶端所需要的 JS 準備接手做 CSR，當 JS 載入完成後又再一次的執行 Vue 元件的 const count = ref(Math.round(Math.random() * 1000)) 這段程式碼，此時亂數產生了 101 這個數字，客戶端也就重新渲染出了 101 於頁面上，這也就是為什麼每次重新整理數字會變化兩次的原因。

Nuxt 預設的通用渲染 (Universal Rendering) 模式，是結合了 SSR 與 CSR 的技術，在 Nuxt 收到網頁請求後，會在伺服器渲染出 HTML 回傳至瀏覽器渲染顯示出靜態頁面，同時開始載入需要的 Vue 程式碼，讓客戶端接手為 SPA 使得網頁具有互動性，接手後的渲染行為都是在客戶端進行的 CSR，這也就讓通用渲染同時兼具 SSR 對 SEO 的友善以及 CSR 良好互通性的使用者體驗。

這種在瀏覽器中使後端渲染出的靜態頁面具有交互性，稱之為「Hydration」。

依據官網所提供的圖片，我添加了一些文字來幫助理解。前述提到了在伺服器渲染網頁 HTML 給瀏覽器時，使用可以正常的看見網頁，但是在 JS 下載完成之前，網頁是不具有互動性的，也就是還不具有路由跳轉等 Vue 互動邏輯，直至 JS 下載完後會 Hydrate Vue 程式碼，這時客戶端就完全接手後續的互動與 CSR，到這邊 Hydration 完成，我們也就能與網站完整的互動了。

回到一開始的例子，我們在瀏覽器打開開發者工具的主控台 (Console)，可以發現到其實開發的過程，也出現了錯誤提示「Hydration completed but contains mismatches.」，告訴我們 Hydration 完成了但是包含了不匹配，正是前端與後端初始值不同的錯誤。

接下來我們將介紹 Nuxt 提供的組合式函數 useState，來可以解決這個問題。

Nuxt 3 的狀態管理 (State Management)

Nuxt 提供了一個組合式函數 useState 用來建立具有響應式及對於 SSR 友善的共享狀態。

在前面的例子我們提到因為 Hydration 而導致前後端的初始值可能不一致，而 useState 是一個對 SSR 友善的 ref 替代品，使用 useState 建立的響應式變數，它的值會在伺服器端渲染後與客戶端 Hydration 期間的得以被保留。

useState 有兩種接收不同數量參數的呼叫方式：

1
2


useState<T>(init?: () => T | Ref<T>): Ref<T>
useState<T>(key: string, init?: () => T | Ref<T>): Ref<T>

key：唯一鍵，用於確保資料能被正確請求且不重複。
init：用於提供的初始值給 State 的函數，這個函數也可以回傳一個 ref。

舉個例子，新增 ./pages/count.vue，內容如下：

pages/count.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">
 <span class="text-9xl font-semibold text-emerald-400">{{ count }}</span>
 </div>
 </div>
</template>

<script setup>
const count = useState('count', () => Math.round(Math.random() * 1000))
</script>

可以發現，使用 useState 初始化 count 的值後，瀏覽器重整頁面，就不像前面的例子會發生兩次的數值變動。

當我們使用 useState 並以 count 當作 key，在網頁請求進入伺服器端執行時，還沒有這個 count 狀態，所以執行了初始化函數產生出一個亂數，例如 888 就會回傳給 count 當作響應式變數的初始值，此時這個網頁請求，已經有一個 count 的響應式狀態，當前端於 Hydration 步驟再次的執行了下面這段程式碼，useState 一樣是以 count 當作 key，但是存在了一個由伺服器端建立好的 count，就會直接使用該狀態，也就不會在執行初始化函數，而導致前後端的初始狀態不一致的問題。

1

const count = useState('count', () => Math.round(Math.random() * 1000))

useState 的基本用法

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

pages/counter/increment.vue

 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


<template>
 <div class="bg-white py-24">
 <div class="flex flex-col items-center">
 <span class="text-9xl font-semibold text-sky-600">{{ counter }}</span>
 <div class="mt-8 flex flex-row">
 <button
 class="font-base mx-2 rounded-full bg-sky-500 px-4 py-2 text-xl text-white hover:bg-sky-600 focus:outline-none focus:ring-2 focus:ring-sky-400 focus:ring-offset-2"
 @click="counter++"
 >
 增加
 </button>
 <button
 class="font-base mx-2 rounded-full bg-sky-500 px-4 py-2 text-xl text-white hover:bg-sky-600 focus:outline-none focus:ring-2 focus:ring-sky-400 focus:ring-offset-2"
 @click="counter--"
 >
 減少
 </button>
 </div>
 <p class="mt-4 text-slate-500">如果是第一次進入這個頁面，數值初始設定為 0</p>
 <div class="mt-8">
 <NuxtLink to="/">回首頁</NuxtLink>
 </div>
 </div>
 </div>
</template>

<script setup>
const counter = useState('counter', () => 0)
</script>

我們使用 useState 並以 counter 當作 key，首次於後端渲染時會初始化為 0，當前端Hydration 步驟載入 Vue 或跳轉頁面，因為使用相同的 key 所以這個狀態也會繼續被保留，直至我們下一次重新整理網頁。

useState 的共享狀態

前面 useState 的基本用法以 counter 當作 key，我們可以再建立不同的頁面元件並使用 useState('counter') 就可以把這個狀態拿做出來用，也就達到了在任何元件中可以共享相同的響應式狀態。

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

pages/counter/surprise.vue

 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


<template>
 <div class="bg-white py-24">
 <div class="flex flex-col items-center">
 <span class="text-9xl font-semibold text-sky-600">{{ counter }}</span>
 <div class="mt-8 flex flex-row">
 <button
 class="font-base mx-2 rounded-full bg-sky-500 px-4 py-2 text-xl text-white hover:bg-sky-600 focus:outline-none focus:ring-2 focus:ring-sky-400 focus:ring-offset-2"
 @click="counter++"
 >
 增加
 </button>
 <button
 class="font-base mx-2 rounded-full bg-sky-500 px-4 py-2 text-xl text-white hover:bg-sky-600 focus:outline-none focus:ring-2 focus:ring-sky-400 focus:ring-offset-2"
 @click="counter--"
 >
 減少
 </button>
 </div>
 <p class="mt-4 text-slate-500">如果是第一次進入這個頁面，數值初始設定為亂數</p>
 <div class="mt-8">
 <NuxtLink to="/">回首頁</NuxtLink>
 </div>
 </div>
 </div>
</template>

<script setup>
const counter = useState('counter', () => Math.round(Math.random() * 1000))
</script>

我們可以任意導航至 /counter/increment 與 /counter/surprise 頁面，可以發現兩個頁面可以共享相同的 counter 狀態，當首次進入或重新整理 increment.vue 頁面，會將 counter 初始化為 0；而首次進入或重新整理 surprise.vue 頁面則是產生一個亂數給予 counter。

當然你也可以直接在其他元件中使用 useState('counter')，就可以取得共享的響應式裝態，但如果這個元件是初次進入而沒有預設值的建立函數，可能會引發一些錯誤，要特別的注意。

使用組合式函數建立共享狀態

如下例子，我們可以建立組合式函數 (Composables) 來搭配 useState。

新增 ./composables/states.ts，內容如下：

composables/states.ts

1

export const useColor = () => useState<string>('color', () => 'green')

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

pages/color.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">
 <span class="text-9xl font-semibold text-emerald-400">{{ color }}</span>
 </div>
 </div>
</template>

<script setup>
const color = useColor()
</script>

如此一來我們定義好的組合式函數就可以被自動的導入及建立具有類型安全的狀態，在各個元件之間就可以呼叫這個組合函數來取得共享狀態。

在通用渲染的模式之下，瀏覽器於 Hydration 完成前，網頁雖然能瀏覽但是尚不具有互動性，直至 Hydration 完成後，Vue 的頁面元件會重新載入與綁定，因此我們對於響應式的變數，儘量使用 useState 來替代 ref 以確保 Hydration 前後的初始值得以被保留，而且 useState 因為可以使用 key 來使狀態於元件間共享。

狀態管理 - Store & Pinia

上述我們介紹了如何在 Nuxt 3 使用 useState 來建立一個元件間的共享狀態，隨著專案的健壯增大，我們就需要一個更好的方式來管理與儲存這些狀態，例如在 Vue 中使用 Vuex 或 Pinia 來建立一個 Store 管理這些狀態就是一個解決方案。如果你還不了解 Pinia，可以理解為是 Vuex v5。因為目前 Pinia 已經成為 Vue 官方推薦的狀態管理解決方案，本篇將針對 Nuxt 使用 Pinia 做一個簡單的介紹。

Pinia

如果你使用過 Vuex 大概會知道 Vue 如何建立 Store 來做狀態管理，隨著時間 Vuex 很積極的蒐集社群及使用者的意見來規劃 Vuex v5。Pinia 的作者 Eduardo 是 Vue.js 核心團隊的成員之一，也參與著 Vuex 的開發，當時他正測試著 Vuex v5 的提案，而 Pinia 成為探索這些意見及可能性的先驅，實現了 Vuex v5 可能的樣子，現在 Pinia 的 API 已經進入穩定狀態，也成為 Vue 官方推薦使用的狀態管理解決方案，並遵循著 Vue 生態的 RFC 流程。

Pinia 相較於 Vuex 有以下差異：

沒有 mutation，只需要使用 action 就可以改狀態。
不再有 modules 巢狀的結構，也不再需要為模組定義命名空間，因為在 Pinia 中，可以定義多個 Store 而且每個都是獨立的也都具有自己的命名空間。
更完整的支援 TypeSctipt，也不再需要使用多餘的 types 來封裝，所有的內容都是類型化的，Pinia API 的設計方式盡可能使用 TypeSctipt 類型推斷。
非常輕巧，約僅有 1 KB，而且可以自定義插件。
支援伺服器端渲染 (SSR) 與程式碼自動拆分。

Nuxt 3 安裝 Pinia

1
2
3


npm install -D pinia @pinia/nuxt --force
# or
# yarn add -D pinia @pinia/nuxt --force

目前照著官方安裝 Pinia，會發生一些問題，所以我們在安裝時加上 –force 參數

添加 @pinia/nuxt 至 nuxt.config.ts 的 modules 屬性中。

nuxt.config.ts

1
2
3


export default defineNuxtConfig({
 modules: ['@pinia/nuxt']
})

建立第一個 Pinia 的 Store

Pinia 提供了一個函數 defineStore 用來定義 store，呼叫時需要一個唯一的名稱來當作第一個參數傳遞，也稱之為 id，Pinia 會使用它來將 store 連接到 devtools。

建議將回傳的函數命名為 use...，例如 useCounterStore，use 作為開頭是組合式函數命名的約定，來符合使用上的習慣。

而 defineStore 的第二個參數，可以傳入 Options 物件或是 Setup 函數，例如我們使用 Options 來定義一個 Store，新增 ./stores/counter.js，內容如下：

stores/counter.js

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


import { defineStore } from 'pinia'

export const useCounterStore = defineStore('counter', {
 state: () => ({
 count: 0
 }),
 actions: {
 increment() {
 this.count += 1
 },
 decrement() {
 this.count -= 1
 }
 },
 getters: {
 doubleCount: (state) => state.count * 2
 }
})

可以發現到與 Vue 的 Options API 非常類似，我們可以傳遞帶有 state、actions 和 getters 屬性的物件。這些屬性正好讓 Store 與 Options API 呼應彼此的關係，如 state 對應 data、actions 對應 methods 而 getters 對應 computed。

還有另一種方式可以來定義 Store，與 Vue Composition API 的 setup 函數類似，我們可以傳入一個函數，這個函數裡面定義響應式屬性、方法等函數，最後回傳我們想公開的屬性和方法所組成的物件。

以 setup 函數定義 counter store，內容如下：

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


import { defineStore } from 'pinia'

export const useCounterStore = defineStore('counter', () => {
 const count = ref(0)

 const increment = () => {
 count.value += 1
 }
 const decrement = () => {
 count.value -= 1
 }

 const doubleCount = computed(() => count.value * 2)

 return {
 count,
 increment,
 decrement,
 doubleCount
 }
})

開始使用 Store

我們只需要在元件中，如下程式碼匯入並呼叫 useCounterStore() 就可以操作 store 裡面的方法或屬性囉！

1
2
3


import { useCounterStore } from '@/stores/counter'

const counterStore = useCounterStore()

我們新增一個頁面元件 ./pages/counter.vue，內容如下：

pages/counter.vue

 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


<template>
 <div class="bg-white py-24">
 <div class="flex flex-col items-center">
 <span class="text-9xl font-semibold text-sky-600">{{ counterStore.count }}</span>
 <div class="mt-8 flex flex-row">
 <button
 class="font-base mx-2 rounded-full bg-sky-500 px-4 py-2 text-xl text-white hover:bg-sky-600 focus:outline-none focus:ring-2 focus:ring-sky-400 focus:ring-offset-2"
 @click="counterStore.increment"
 >
 增加
 </button>
 <button
 class="font-base mx-2 rounded-full bg-sky-500 px-4 py-2 text-xl text-white hover:bg-sky-600 focus:outline-none focus:ring-2 focus:ring-sky-400 focus:ring-offset-2"
 @click="counterStore.decrement"
 >
 減少
 </button>
 </div>
 <div class="mt-8">
 <NuxtLink to="/">回首頁</NuxtLink>
 </div>
 </div>
 </div>
</template>

<script setup>
import { useCounterStore } from '@/stores/counter'

const counterStore = useCounterStore()
</script>

這樣我們就完成了一個 store 的顯示狀態值，透過呼叫 counterStore 內定義的 increment 與 decrement 來改變狀態。

在不同的元件間，你也可以使用 useCounterStore 取得已經建立好的 store 來共享這些狀態或進行操作。

Pinia Store 的 State

預設情況下，可以直接對 store 的實例來取得狀態，而使用 Pinia 定義的 store 比較特別的是，我們可以不用透過呼叫函數來修改狀態，也可以直接對 store 的狀態進行修改。

1
2
3


const counterStore = useCounterStore()

counterStore.count += 10

改變狀態

除了直接使用 counterStore.count += 10 修改 store，你也可以使用 store 提供的 helper $patch 來修改部分的狀態。

1
2
3
4


userStore.$patch({
 name: 'Ryan'
 money: '88888888',
})

對於集合類型的修改，例如陣列的新增、刪除或指定修改某一個元素等操作，你可以使用 $patch 傳入一個函數，這個函數會接收一個 state 讓你可以修改，對於比較複雜的操作會很方便。

1
2
3
4


cartStore.$patch((state) => {
 state.items.push({ name: 'shoes', quantity: 1 })
 state.hasChanged = true
})

如果你需要，也可以將 store 的整個 state 重新設置成一個新的物件。

1
2
3
4


cartStore.$state = {
 items: [],
 hasChanged: false,
}

重置狀態

store 的實例提供了一個 $reset() 的 helper，呼叫它就可以將 store 的狀態重置至初始值，不過目前只在使用 Option 物件定義的 store 才有實作。

1
2
3


const counterStore = useCounterStore()

counterStore.$reset()

Pinia Store 的 Getters

使用同一個 store 中的其他 getter

在 store 內你可以組合多個 getter，在 Option 物件下，可以透過使用 this 來呼叫使用其他的 getter。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


export const useStore = defineStore('main', {
 state: () => ({
 counter: 0,
 }),
 getters: {
 doubleCount: (state) => state.counter * 2,
 doubleCountPlusOne() {
 return this.doubleCount + 1
 },
 }
})

使用其他 store 的 getter

在 store 內你也可以組合其他 store 的 getter，只要建立出其他 store 實例就可以呼叫使用了。

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


import { useOtherStore } from './other-store'

export const useStore = defineStore('main', {
 state: () => ({
 // ...
 }),
 getters: {
 otherGetter(state) {
 const otherStore = useOtherStore()
 return state.localData + otherStore.data
 },
 },
})

Pinia Store 的 Actions

Actions 相當於元件中的方法，也是修改狀態的商業邏輯定義的位置，action 可以是同步也可以是異步的，因此，我們也能在 action 中打後端 API 來取得資料後更新狀態。

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


import { defineStore } from 'pinia'

export const useUserStore = defineStore('user', {
 state: () => ({
 profile: {
 name: '',
 gender: '',
 email: ''
 }
 }),
 actions: {
 async getUserProfile() {
 try {
 const { data } = await useFetch('/api/profile')
 this.profile = data
 } catch (error) {
 return error
 }
 }
 }
})

Store 的解構

有些情況，你可能需要將 Store 中的屬性或方法獨立的提取出來，但為了保持屬性的響應性，你需要使用 storeToRefs 來建立屬性的參考，就像使用 toRefs 來建立 props 的參考一樣。

1
2
3
4
5
6
7


import { storeToRefs } from 'pinia'
import { useCounterStore } from '@/stores/counter'

const counterStore = useCounterStore()

const { count } = storeToRefs(counterStore)
const { increment, decrement } = counterStore

Pinia 持久化插件 - Pinia Plugin Persistedstate

Pinia 是個非常輕量的狀態管理解決方案，而且也提供底層 API 使得 Pinia 能夠自定義插件來擴展功能，舉例來說，我們有些狀態需要儲存在使用者瀏覽器中，下次再瀏覽時可以取的當時儲存的狀態資料，我們就需要將 store 的狀態持久化。

我們可以使用 Pinia Plugin Persistedstate 這個插件，來做到持久化這件事，這對於儲存使用者資訊或登入狀態非常的方便。

在 Nuxt 3 中配置使用 Pinia Plugin Persistedstate

Step 1. 安裝套件

1
2
3


npm install -D pinia-plugin-persistedstate --force
# or
# yarn add -D pinia-plugin-persistedstate --force

目前照著官方安裝 Pinia，會發生一些問題，所以我們在安裝時加上 –force 參數

Step 2. 在 Nuxt 3 為 Pinia 添加 Persist 插件

建立 ./plugins/pinia-plugin-persistedstate.client.js，內容如下：

plugins/pinia-plugin-persistedstate.client.js

1
2
3
4
5


import piniaPersistedstate from 'pinia-plugin-persistedstate'

export default defineNuxtPlugin((nuxtApp) => {
 nuxtApp.$pinia.use(piniaPersistedstate)
})

Step 3. 為你的 Store 添加持久化配置

在現有的 store 定義中添加，persist 屬性，來配置 store 持久化，將狀態儲存在瀏覽器的 localStorage。

 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


import { defineStore } from 'pinia'

export const useCounterStore = defineStore('counter', {
 state: () => ({
 count: 0
 }),
 actions: {
 increment() {
 this.count += 1
 },
 decrement() {
 this.count -= 1
 }
 },
 getters: {
 doubleCount: (state) => state.count * 2
 },
 persist: {
 enabled: true,
 strategies: [
 {
 key: 'counter',
 storage: process.client ? localStorage : null
 }
 ]
 }
})

如果是使用 setup 函數定義 store，你可以在 defineStore 傳入第三個參數並添加 persist 屬性。

 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
33
34
35


import { defineStore } from 'pinia'

export const useCounterStore = defineStore(
 'counter',
 () => {
 const count = useState('count', () => 0)

 const increment = () => {
 count.value += 1
 }
 const decrement = () => {
 count.value -= 1
 }

 const doubleCount = computed(() => count.value * 2)

 return {
 count,
 increment,
 decrement,
 doubleCount
 }
 },
 {
 persist: {
 enabled: true,
 strategies: [
 {
 key: 'counter',
 storage: process.client ? localStorage : null
 }
 ]
 }
 }
)

Step 4. 持久化效果

當我們設置好 counterStore 的持久化後，我們的狀態就會被儲存在瀏覽器的 localStorage 之中，就算關閉瀏覽器或重新整理網頁，store 的狀態都會再從 localStorage 讀取出來。

在小型的專案中，你可以使用 useState 來管理，但大專案你就需要一個更好的方式來管理這些狀態，如 Pinia 來為我們管理這些狀態，甚至定義多個 store，Pinia 支援的插件能協助我們擴展 Pinia 的功能，Pinia Plugin Persistedstate 就是一個很常用的插件，能協助我們將 Pinia 的狀態持久化至瀏覽器的 localStorage 或 sessionStorage 中。

Runtime Config & App Config

在 Nuxt 3 中提供了兩種可以方式設定環境變數或前端需要使用的共用設定，分別是在 Nuxt 啟動時會在後端載入使用的 Runtime Config 及可以在前端被使用的 App Config 這兩者間的區別這邊做一些講解。

Runtime Config

在開發網站或部署時，我們總是有一些環境變數需要做設置，dotenv 就是一個很好用的套件，能幫助我們將專案下的 .env 檔案載入到 Node.js 的 process.env 之中，尤其在後端伺服器的 API 開發，這些不能公開或敏感的 Key 或設定值，通常不會與整個專案一起進行版本控制，而是針對不同環境與機器，配置於 .env 或環境變數之中。

這個 .env 設定檔內的環境變數，例如：資料庫的帳號密碼、第三方服務的 Token 或 API Key …等，通常只會在伺服器被讀取做使用，也不會洩漏這些設定給使用者知道，我們也稱之為執行時的設定 (Runtime Config)。

Nuxt 3 提供了可以設定 Runtime Config 的方式，我們可以很方便的來設定這些環境變數給予伺服器執行時使用。

配置 runtimeConfig

我們可以在 nuxt.config.ts 中添加 runtimeConfig 屬性，就可以來設定只有伺服器端可以使用的環境變數。

例如，在 nuxt.config.ts 檔案中，添加一個 apiSecret 至 runtimeConfig 屬性內：

nuxt.config.ts

1
2
3
4
5


export default defineNuxtConfig({
 runtimeConfig: {
 apiSecret: '怎麼可以讓你知道呢 :P'
 }
})

我們就可以在 Server API 使用 useRuntimeConfig() 獲得執行時的設定，再從中取得 apiSecret 環境變數。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


const runtimeConfig = useRuntimeConfig()

export default defineEventHandler((event) => {
 const { apiSecret } = runtimeConfig

 console.log(`接收到了一個 Server API 請求: ${event.req.url}`)
 console.log(`執行時的環境變數 [apiSecret]: ${apiSecret}`)

 return 'ok'
})

因為我們是定義在 Server API，所以可以在測試伺服器啟動的 Terminal 看見 console.log 的結果。

此外你也可以在插件或 Vue 中使用 useRuntimeConfig() 來取得執行時的設置，但也僅在 setup 或 Nuxt Lifecycle Hooks 中有效。

客戶端使用 runtimeConfig

通常一些密鑰或敏感資訊，我們都會定義在 runtimeConfig 僅供伺服器端做使用，而 runtimeConfig 也可以配置一個 public 的屬性，來把一些環境變數於伺服器端或客戶端做使用，例如，API 的 Base URL 這類在伺服器端打 API 時會需要使用，而客戶端的操作流程也會打同樣的 API 位置，我們就可以使用 public 的屬性。

例如，在 nuxt.config.ts 檔案中，添加一個 apiBase 至 runtimeConfig.public 屬性內：

nuxt.config.ts

1
2
3
4
5
6
7
8


export default defineNuxtConfig({
 runtimeConfig: {
 apiSecret: '怎麼可以讓你知道呢 :P',
 public: {
 apiBase: '/api'
 }
 }
})

新增 ./pages/profile.vue 頁面：

pages/profile.vue

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


<template>
 <div class="my-24 flex flex-col items-center">
 <span class="mt-4 text-2xl text-gray-600">回傳資料:</span>
 <p class="mt-4 text-3xl font-semibold text-blue-500">{{ data }}</p>
 </div>
</template>

<script setup>
const runtimeConfig = useRuntimeConfig()
const { apiBase } = runtimeConfig.public

console.log(toRaw(runtimeConfig))

const { data } = await useFetch(`${apiBase}/hello`)
</script>

添加在 runtimeConfig.public 屬性的環境變數，在伺服器端與客戶端都可以讀取得到。

下圖中可以發現，在瀏覽器中的 Console 所印出的 runtimeConfig 是不會包含僅有在伺服器端能使用的 apiSecret。

使用 .env 建立環境變數

Nuxt 在開發模式或執行時，已經有內建 dotenv，如果在專案目錄下添加了 .env，Nuxt 會在開發期間、建構時或產生靜態網站時，自動載入 .env 內的環境變數。

例如建立 .env 檔案，內容如下：

.env

1
2


NUXT_API_SECRET=api_secret_token
NUXT_PUBLIC_API_BASE=https://nuxtjs.org

這兩個值，將被 dotenv 自動載入至 process.env 中，作為環境變數。

環境變數的覆蓋

不論是透過 dotenv 自動載入 .env 或其他方式配置的環境變數，只要環境變數命名是 NUXT_ 開頭，這個環境變數將會覆蓋 runtimeConfig 的設置。

舉例來說，當我們 runtimeConfig 設置如下：

1
2
3
4
5
6
7
8


export default defineNuxtConfig({
 runtimeConfig: {
 apiSecret: '怎麼可以讓你知道呢 :P',
 public: {
 apiBase: '/api'
 }
 }
})

建立 .env 檔案或其他方式設置下列環境變數：

1
2


NUXT_API_SECRET=api_secret_token
NUXT_PUBLIC_API_BASE=https://nuxtjs.org

那麼 NUXT_API_SECRET 環境變數，將會覆蓋 runtimeConfig.apiSecret，而 NUXT_PUBLIC_API_BASE 將會覆蓋 runtimeConfig.public.apiBase，最終 runtimeConfig 的設定會變成如下：

1
2
3
4
5
6


{
 apiSecret: "api_secret_token", // 被 NUXT_API_SECRET 環境變數覆蓋
 public: {
 apiBase: "https://nuxtjs.org" // 被 NUXT_PUBLIC_API_BASE 環境變數覆蓋
 }
}

會有這樣子的特性是因為 Nuxt 會在啟動時，先載入 nuxt.conf.ts 內的 runtimeConfig，建立出呼叫 useRuntimeConfig() 所得到的執行時設定，例如，先建構出了 _runtimeConfig 物件。

1
2
3
4
5
6


const _runtimeConfig = {
 apiSecret: '怎麼可以讓你知道呢 :P',
 public: {
 apiBase: '/api'
 }
}

接著會走訪這個 _runtimeConfig 物件裡面的 key，逐一將 key 的名稱轉換蛇形命名法 (Snake case)，並轉成全大寫再加上 NUXT_ 前綴後取得對應的環境變數，如果存在就會以新值來覆蓋 _runtimeConfig 內的屬性。

例如 apiSecret 經過轉換變成 api_secret，接著轉大寫 API_SECRET 最後加上前綴變成 NUXT_API_SECRET，如此環境變數 NUXT_API_SECRET 的值就覆蓋 runtimeConfig.apiSecret。

而在 public 下的設置，也會先轉為 public_apiBase 再經過蛇行命名成 public_api_base 等步驟，最後變成 NUXT_PUBLIC_API_BASE 來載入環境變數並覆蓋。

最後小提醒，當建構出生產環境的網站，如 .output 目錄後，dotenv 並不會包含在建構的網站內，你需要再自己載入或配置環境變數才能正常運作哦，例如在 PM2 配置 env。

App Config

配置 appConfig

在 nuxt.config.ts 檔案中，可以在 appConfig 屬性內添加設置，例如，通常我們會添加像網站主題的主色等這類可以公開的配置，讓網站可以使用這個設置。

1
2
3
4
5
6
7


export default defineNuxtConfig({
 appConfig: {
 theme: {
 primaryColor: '#0ea5e9'
 }
 }
})

當建立好 appConfig 後，就可以使用組合式函數 useAppConfig() 來取得設置。

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

pages/config.vue

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


<template>
 <div class="my-24 flex flex-col items-center">
 <span class="mt-4 text-2xl text-gray-600">theme.primaryColor:</span>
 <p class="mt-4 text-3xl font-semibold text-blue-500">{{ theme.primaryColor }}</p>
 </div>
</template>

<script setup>
const appConfig = useAppConfig()
const { theme } = appConfig
</script>

app.config 檔案

你也可以在專案目錄下建立 app.config.ts 來配置 App Config，這個檔案的副檔名可以是 .ts、.js 或 .mjs。

app.config.ts

1
2
3
4
5


export default defineAppConfig({
 theme: {
 primaryColor: '#3b82f6'
 }
})

當建立了 app.config.ts 檔案，該設定會與 nuxt.config.ts 檔案中的 appConfig 屬性結合，如果具有相同的命名，則以 app.config.ts 檔案內的設置為主。

具有響應式的設定

當設定好的 App Config 在使用時，解構出的變數是具有響應性的，也就是說在其他頁面修改主題顏色的設定，可以響應至所有使用這個設定的元件。

舉個例子，新增一個 darkMode 的屬性至 app.config.ts 檔案內的 theme：

app.config.ts

1
2
3
4
5
6


export default defineAppConfig({
 theme: {
 primaryColor: '#3b82f6',
 darkMode: false
 }
})

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

pages/index.vue

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


<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 flex-col space-y-4">
 <NuxtLink to="/config">前往 /config</NuxtLink>
 </div>

 <p class="mt-4 text-2xl text-gray-600">theme.darkMode:</p>
 <span class="mt-4 text-3xl font-semibold text-blue-500">{{ theme.darkMode }}</span>
 </div>
 </div>
</template>

<script setup>
const appConfig = useAppConfig()
const { theme } = appConfig
</script>

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

pages/config.vue

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


<template>
 <div class="my-24 flex flex-col items-center">
 <p class="mt-4 text-2xl text-gray-600">theme.primaryColor:</p>
 <span class="mt-4 text-3xl font-semibold text-blue-500">{{ theme.primaryColor }}</span>

 <p class="mt-4 text-2xl text-gray-600">theme.darkMode:</p>
 <span class="mt-4 text-3xl font-semibold text-blue-500">{{ theme.darkMode }}</span>
 <button
 class="mt-6 rounded-sm bg-blue-500 py-2 px-4 text-base font-medium text-white hover:bg-blue-600 focus:outline-none focus:ring-2 focus:ring-blue-400 focus:ring-offset-2"
 @click="theme.darkMode = !theme.darkMode"
 >
 {{ `${theme.darkMode ? '取消' : '啟用'}深色模式` }}
 </button>

 <div class="mt-8">
 <NuxtLink to="/">回首頁</NuxtLink>
 </div>
 </div>
</template>

<script setup>
const appConfig = useAppConfig()
const { theme } = appConfig
</script>

如下圖，我們的首頁取得了 App Config 中的 theme.darkMode 預設為 false，接著我們切換至 /config 頁面，可以將從 useAppConfig() 解構出的 theme 進行變更，我們使用按鈕來設置 theme.darkMode 為 true 或 false 表示啟用或取消深色模式。當變更完成後，回至首頁，可以發現 theme.darkMode 發生了響應。

小結

Nuxt 3 提供了 Runtime Config 及 App Config 來讓我們將常用或預設設定應用在不同的情境，使用時，我們僅需記得，不能公開的金鑰或敏感訊息，僅放置在 runtimeConfig 中而且不在 public 屬性內，runtimeConfig.public 通常放的是前後端會使用到且不常修改的常數。而 App Config 則是當伺服器端與客戶端需要使用的設置，如主題顏色、是否啟用深色模式等這類可以被使用者調整變動的且需要具有響應性，就可以放置在 appConfig 之中。

實作練習

這裡介紹網站的會員系統常會使用到第三方登入，將以 Google OAuth 為例來實際於 Nuxt 3 中做串接。

串接 Google OAuth 登入

首先，我們需要有一組 Google OAuth 使用的 Client ID，你可以到 Google Console 新增一個「OAuth 2.0 用戶端 ID」，這裡我就不再贅述網頁應用程式用的申請過程。

這邊小提醒一下，在建立 OAuth Client ID 時，已授權的 JavaScript 來源，記得填寫上您的正式環境或開發環境的 Domain，且建議使用 HTTPS。

完成後，記得保管好用戶端密碼、用戶端 ID (Client ID) 是我們稍後會需要的，用戶端編號格式大概如：

1

168152363730-b37gnijdpa2rdvvbq0qc29cjh4082t3b.apps.googleusercontent.com

我們將這組 Client ID，放置在 Nuxt 的 Runtime Config 之中。調整 nuxt.config.ts 內容，在 runtimeConfig.public 添加 googleClientId。

nuxt.config.ts

1
2
3
4
5
6
7


export default defineNuxtConfig({
 runtimeConfig: {
 public: {
 googleClientId: '這邊放上你的 Google Client ID'
 }
 }
})

接下來，安裝 Vue 的 Google OAuth 插件，這邊使用的是 vue3-google-login，也有詳細的說明文件可以參考。

安裝 vue3-google-login

1
2
3


npm install -D vue3-google-login
# or
# yarn add -D vue3-google-login

建立 Nuxt 3 插件來使用 vue3-google-login，新增 ./plugins/vue3-google-login.client.js，內容如下：

plugins/vue3-google-login.client.js

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


import vue3GoogleLogin from 'vue3-google-login'

export default defineNuxtPlugin((nuxtApp) => {
 const runtimeConfig = useRuntimeConfig()
 const { googleClientId: GOOGLE_CLIENT_ID } = runtimeConfig.public

 nuxtApp.vueApp.use(vue3GoogleLogin, {
 clientId: GOOGLE_CLIENT_ID
 })
})

接著我們在元件中可以直接使用 <GoogleLogin> 元件，並添加一個 callback 屬性；此外，我使用了 Nuxt 3 提供的 <ClientOnly> 元件，將 <GoogleLogin> 包裹起來，以確保該元件僅在客戶端做渲染，以免登入按鈕在初始化發生問題。

pages/login.vue

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


<template>
 <div>
 <ClientOnly>
 <GoogleLogin :callback="callback" />
 </ClientOnly>
 </div>
</template>

<script setup>
const callback = (response) => {
 console.log(response)
}
</script>

接著我們啟動 Nuxt 伺服器，這邊我會習慣使用 yarn run dev -- --https 來啟用 HTTPS 做測試，就能發現使用 Google 帳號登入成功後，所返回的 Credential。

One Tap prompt

你可以在 <GoogleLogin> 元件添加 prompt 屬性並設為 true，這樣就能同時啟用 Google 一鍵登入 (One Tap prompt) 的功能囉！

1

<GoogleLogin :callback="callback" prompt />

或者也可以在 onMounted 中呼叫 vue3-google-login 的 googleOneTap() 方法，來單獨使用 One Tap prompt。

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


<script setup>
import { googleOneTap } from 'vue3-google-login'

onMounted(() => {
 googleOneTap()
 .then((response) => {
 console.log(response)
 })
 .catch((error) => {
 console.error(error)
 })
})

</script>

自訂按鈕

如果你想自訂登入按鈕的樣式，可以在 <GoogleLogin> 的預設插槽 (Slot) 做建立。

1
2
3
4
5


<template>
 <GoogleLogin :callback="callback">
 <button>使用 Google 進行登入</button>
 </GoogleLogin>
</template>

使用自訂按鈕會讓 OAuth 流程稍微有點不一樣，當你登入成功後預設會回傳 Auth Code。

如果設定屬性 popup-type="TOKEN"，則回傳 Access Token。

1
2
3
4
5


<template>
 <GoogleLogin :callback="callback" popup-type="TOKEN">
 <button>使用 Google 進行登入</button>
 </GoogleLogin>
</template>

使用 googleTokenLogin()

在元件中我們也可以自己建立 handleGoogleLogin 點擊事件，呼叫 googleTokenLogin() 方法並傳入設定在 Runtime Config 中的 Google Client ID，這樣點擊登入按鈕就能處理 Google 登入取得 Access Token。

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


<script setup>
import { googleTokenLogin } from 'vue3-google-login'

const runtimeConfig = useRuntimeConfig()
const { googleClientId: GOOGLE_CLIENT_ID } = runtimeConfig.public

const handleGoogleLogin = () => {
 googleTokenLogin({
 clientId: GOOGLE_CLIENT_ID
 }).then((response) => {
 console.log(response)
 })
}
</script>

建立一個登入按鈕來呼叫 handleGoogleLogin 點擊事件。

1
2
3
4
5
6
7
8
9


<template>
 <div>
 <button
 type="button"
 @click="handleGoogleLogin"
 >
 使用 Google 繼續
 </button>
</template>

使用 vue3-google-login 提供的 googleTokenLogin() 方法，我們就能取得 Google 使用者的 Access Token 囉！

使用 googleAuthCodeLogin()

我們也可以使用 googleAuthCodeLogin() 來取得 Auth Code。

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


<script setup>
import { googleAuthCodeLogin } from 'vue3-google-login'

const runtimeConfig = useRuntimeConfig()
const { googleClientId: GOOGLE_CLIENT_ID } = runtimeConfig.public


const handleGoogleLogin = () => {
 googleAuthCodeLogin({
 clientId: GOOGLE_CLIENT_ID
 }).then((response) => {
 console.log(response)
 })
}
</script>

伺服器端驗證

當使用者於前端成功登入後，通常會傳至後端進行登入或記錄使用者，再產生使用於網站的 Token、Cookie 或 Session 等，以供後續的網站驗證做使用。

我們可使用 google-auth-library 於後端進行一系列的驗證或取得使用者資訊。

安裝 google-auth-library

1
2
3


npm install -D google-auth-library
# or
# yarn add -D google-auth-library

接下來，我們就能依照不同的登入方式取得的 Credential、Access Token 或 Auth Code 送至後端做驗證。

驗證 Access Token

新增一個 Server API，只接受 POST 方法，在 Body 中夾帶 accessToken 發送至後端。

建立 ./server/api/auth/google.post.js，內容如下：

server/api/auth/google.post.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


import { OAuth2Client } from 'google-auth-library'

export default defineEventHandler(async (event) => {
 const body = await readBody(event)
 const oauth2Client = new OAuth2Client()
 oauth2Client.setCredentials({ access_token: body.accessToken })

 const userInfo = await oauth2Client
 .request({
 url: 'https://www.googleapis.com/oauth2/v3/userinfo'
 })
 .then((response) => response.data)
 .catch(() => null)

 oauth2Client.revokeCredentials()

 if (!userInfo) {
 throw createError({
 statusCode: 400,
 statusMessage: 'Invalid token'
 })
 }

 return {
 id: userInfo.sub,
 name: userInfo.name,
 avatar: userInfo.picture,
 email: userInfo.email,
 emailVerified: userInfo.email_verified,
 }
})

調整元件內的登入流程。

 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


<script setup>
import { googleTokenLogin } from 'vue3-google-login'

const runtimeConfig = useRuntimeConfig()
const { googleClientId: GOOGLE_CLIENT_ID } = runtimeConfig.public

const userInfo = ref()

const handleGoogleLogin = async () => {
 const accessToken = await googleTokenLogin({
 clientId: GOOGLE_CLIENT_ID
 }).then((response) => response?.access_token)

 if (!accessToken) {
 return '登入失敗'
 }

 const { data } = await useFetch('/api/auth/google', {
 method: 'POST',
 body: {
 accessToken
 },
 initialCache: false
 })

 userInfo.value = data.value
}
</script>

當我們使用 Google OAuth 登入成功後，會取得 Access Token，並將其傳至 Server API，/api/auth/google 接收 Access Token 並使用 Google API 取得使用者的資訊，最後回傳給前端。

驗證 Credential

在元件中，我們使用的登入方式如果是 Google 渲染的預設按鈕或 One Tap prompt，回傳值就會包含 Credential，我們將就可使用下面修改後的 Server API 進行驗證。

server/api/auth/google.post.js 內容修改為如下：

server/api/auth/google.post.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


import { OAuth2Client } from 'google-auth-library'

export default defineEventHandler(async (event) => {
 const body = await readBody(event)
 const oauth2Client = new OAuth2Client()

 const ticket = await oauth2Client.verifyIdToken({
 idToken: body.credential,
 })

 const payload = ticket.getPayload()

 if (!payload) {
 throw createError({
 statusCode: 400,
 statusMessage: 'Invalid token'
 })
 }

 return {
 id: payload.sub,
 name: payload.name,
 avatar: payload.picture,
 email: payload.email,
 emailVerified: payload.email_verified
 }
})

驗證 Auth Code

我們使用的登入方式如果是呼叫 vue3-google-login 的 googleAuthCodeLogin()，回傳值就會包含 Auth Code，我們就可使用下面修改後的 Server API 進行驗證。

server/api/auth/google.post.js 內容修改為如下：

server/api/auth/google.post.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
33
34
35
36
37


import { OAuth2Client } from 'google-auth-library'

export default defineEventHandler(async (event) => {
 const body = await readBody(event)
 const oauth2Client = new OAuth2Client({
 clientId: '你的 Google Client ID',
 clientSecret: '你的 Google Client Secret',
 redirectUri: '你的 Google Redirect Uri'
 })

 let { tokens } = await oauth2Client.getToken(body.authCode)
 client.setCredentials({ access_token: tokens.access_token })

 const userInfo = await oauth2Client
 .request({
 url: 'https://www.googleapis.com/oauth2/v3/userinfo'
 })
 .then((response) => response.data)
 .catch(() => null)

 oauth2Client.revokeCredentials()

 if (!userInfo) {
 throw createError({
 statusCode: 400,
 statusMessage: 'Invalid token'
 })
 }

 return {
 id: userInfo.sub,
 name: userInfo.name,
 avatar: userInfo.picture,
 email: userInfo.email,
 emailVerified: userInfo.email_verified,
 }
})

以上實現了串接 Google OAuth 登入，並將 Access Token 資訊發送至後端進行驗證，大家可以在依照使用情境自己挑選登入方式及驗證方式，後續也能將使用者資訊儲存到資料庫中，有了資料庫我們就能依照使用者資訊，來比對資料庫進行註冊、驗證登入及產生後續的 Session 或 Cookie 等。

Cookie 在瀏覽網站時多會使用到，不論是用來儲存臨時的資訊或是辨識使用者等，這一個儲存在瀏覽器的一小段文字資料，會在每次發送 HTTP 請求時自動夾帶，所以 Cookie 最常見的用途就包含了登入狀態、驗證身份等。

以下將講述在 Nuxt 3 如何設置 Cookie，並結合 JWT (JSON Web Token) 來做一個實際使用者驗證。

useCookie

Nuxt 3 提供了一個組合式函數 useCookie() 來讓我們可以讀寫 Cookie，並且對於 SSR 也有支援，在頁面、元件或插件中，都可以使用 useCookie() 來建立一個 cookie 具有響應性的參考。

使用方式：

1

const cookie = useCookie(name, options)

name：對應的就是 cookie 的 key。
options：傳入一個物件來設置多個 cookie 屬性：
- maxAge：指定 Max-Age 屬性的值，單位是秒。如果沒有設置，則這個 cookie 將會是 Session Only，意即網頁關閉後就會消失。
- expires：指定一個 Date 物件來作為過期的時間，通常是要相容比較舊的瀏覽器做使用，如果 maxAge 與 expires 屬性都有設定，則過期時間應該要設定為一樣。
- httpOnly：是一個布林值，預設為 false，當設置為 true 時，表示客戶端的 JavaScript 將無法使用 document.cookie 來查看這個 cookie。通常是比較敏感或機密的訊息，如 Token 或 Session Id 會設定為 true，只讓瀏覽器發出請求時自動夾帶。
- secure：是一個布林值，預設為 false，當設置為 true 時瀏覽器得是 HTTPS 的加密傳輸協定的情境下，才會自動夾帶這個 cookie。
- domain：指定 cookie 可以適用的 Domain，通常會保持預設，表示適用於自己的 Domain 之下。
- path：指定 cookie 適用的路徑。
- sameSite：為一個布林值或是字串，用於設定安全策略。
- encode：由於 cookie 的值只能使用有限的字元集，所以這個設置可以將 cookie 編碼成合法的字串值，預設的編碼是使用 JSON.stringify + encodeURIComponent()。
- decode：cookie 會經過一個解碼的過程，預設的解碼是使用 decodeURIComponent + destr。
- default：為一個函數，可以用於回傳 cookie 的預設值，也可以是回傳一個 Ref。

舉個例子，新增 pages/cookie.vue，內容如下：

pages/cookie.vue

 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
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48


<template>
 <div class="flex flex-col items-center justify-center py-12 px-4 sm:px-6 lg:px-8">
 <div class="w-full max-w-md">
 <div class="flex flex-col items-center">
 <h2 class="mt-2 text-center text-3xl font-bold tracking-tight text-gray-700">Cookie</h2>
 </div>
 <div class="mt-2 flex w-full max-w-md flex-col items-center">
 <button
 type="button"
 class="mt-2 w-fit rounded-sm bg-emerald-500 py-2 px-4 text-sm text-white hover:bg-emerald-600 focus:outline-none focus:ring-2 focus:ring-emerald-400 focus:ring-offset-2"
 @click="setNameCookie"
 >
 設置 name
 </button>
 <div class="mt-2 flex">
 <label class="text-lg font-semibold text-emerald-500">name:</label>
 <span class="ml-2 flex text-lg text-slate-700">{{ name }}</span>
 </div>
 </div>
 <div class="mt-2 flex w-full max-w-md flex-col items-center">
 <button
 type="button"
 class="mt-2 w-fit rounded-sm bg-emerald-500 py-2 px-4 text-sm text-white hover:bg-emerald-600 focus:outline-none focus:ring-2 focus:ring-emerald-400 focus:ring-offset-2"
 @click="setCounterCookie"
 >
 設置 counter
 </button>
 <div class="mt-2 flex">
 <label class="text-lg font-semibold text-emerald-500">counter:</label>
 <span class="ml-2 flex text-lg text-slate-700">{{ counter }}</span>
 </div>
 </div>
 </div>
 </div>
</template>

<script setup>
const name = useCookie('name')
const counter = useCookie('counter', { maxAge: 60 })

const setNameCookie = () => {
 name.value = 'Ryan'
}

const setCounterCookie = () => {
 counter.value = Math.round(Math.random() * 1000)
}
</script>

我們就可以設置一個只有目前網頁有效的 cookie 名為 name 及一個過期時間為 60 秒後的 counter。

伺服器端使用 getCookie 與 setCookie

你可以在伺服器端使用 getCookie() 來取得前端夾帶過來的 cookie，也可以使用 setCookie 來設置 cookie 回應給前端。

舉個例子，新增 server/api/coookie.js，內容如下：

server/api/coookie.js

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


export default defineEventHandler((event) => {
 let counter = getCookie(event, 'counter')

 counter = parseInt(counter, 10) || 0
 counter += 1

 setCookie(event, 'counter', counter)

 return { counter }
})

當前端打 /api/cookie 這隻 Server API 時，就會自動夾帶瀏覽器中的 cookie，伺服器端收到請求解析 cookie 後得到 counter，將其轉為數值或預設為 0 後增加 1，再重新設定回去給前端。

我們可以將 Cookie 的運作機制應用在會員系統當中，使用者登入成功後，後端產生的 Token 或 Session 回傳並儲存在使用者的瀏覽器中，之後的請求將會自動夾帶可以辨識出使用者的 cookie，我們就可以在後端解析或比對 cookie 來驗證使用者的資訊，並依照策略給予不同的處理邏輯。

我們延續上述的使用 Google OAuth 登入，我們可以在後端實作產生我們自己系統使用的 Token，並設置在 access_token 這個 cookie 之中，後端可以寫如下程式碼，來設置 httpOnly 及 maxAge 過期時間等參數。

server/api/auth/google.post.js

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


export default defineEventHandler(async (event) => {
 // ...

 setCookie(event, 'access_token', accessToken, {
 httpOnly: true,
 maxAge,
 expires: new Date(expires * 1000),
 secure: process.env.NODE_ENV === 'production',
 path: '/'
 })

 // ...
})

我們使用 jsonwebtoken 產生 JWT，裡面的 Payload 放置了使用者資訊，其中 jwtSignSecret 作為核發 JWT 的簽署金鑰，我們定義在 nuxt.config.ts 中的 runtimeConfig.jwtSignSecret。

安裝 jsonwebtoken

1
2
3


npm install jsonwebtoken
# or
# yarn add jsonwebtoken

完整的 ./server/api/auth/google.post.js 程式碼如下：

server/api/auth/google.post.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
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58


import { OAuth2Client } from 'google-auth-library'
import jwt from 'jsonwebtoken'

const runtimeConfig = useRuntimeConfig()

export default defineEventHandler(async (event) => {
 const body = await readBody(event)
 const oauth2Client = new OAuth2Client()
 oauth2Client.setCredentials({ access_token: body.accessToken })

 const userInfo = await oauth2Client
 .request({
 url: 'https://www.googleapis.com/oauth2/v3/userinfo'
 })
 .then((response) => response.data)
 .catch(() => null)

 oauth2Client.revokeCredentials()

 if (!userInfo) {
 throw createError({
 statusCode: 400,
 statusMessage: 'Invalid token'
 })
 }

 const jwtTokenPayload = {
 id: userInfo.sub,
 nickname: userInfo.name,
 email: userInfo.email
 }

 const maxAge = 60 * 60 * 24 * 7
 const expires = Math.floor(Date.now() / 1000) + maxAge

 const jwtToken = jwt.sign(
 {
 exp: expires,
 data: jwtTokenPayload
 },
 runtimeConfig.jwtSignSecret
 )

 setCookie(event, 'access_token', jwtToken, {
 httpOnly: true,
 maxAge,
 expires: new Date(expires * 1000),
 secure: process.env.NODE_ENV === 'production',
 path: '/'
 })

 return {
 id: userInfo.id,
 nickname: userInfo.name,
 avatar: userInfo.picture,
 email: userInfo.email
 }
})

JWT 在核發時使用的加密金鑰，建議使用非對稱式的金鑰進行加密，這邊僅是為了範例展示方便而使用相同的 Secret 進行加解密。

接著，我們可以實作一個 Server API，./server/api/whoami.js 來從 cookie 得到 access_token，再用 jwt.verify() 方法，來驗證 JTW 後的到使用者資訊。

server/api/whoami.js

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


import jwt from 'jsonwebtoken'

const runtimeConfig = useRuntimeConfig()

export default defineEventHandler((event) => {
 const jwtToken = getCookie(event, 'access_token')

 try {
 const { data: userInfo } = jwt.verify(jwtToken, runtimeConfig.jwtSignSecret)

 return {
 id: userInfo.id,
 nickname: userInfo.nickname,
 email: userInfo.email
 }
 } catch (e) {
 throw createError({
 statusCode: 401,
 statusMessage: 'Unauthorized'
 })
 }
})

我們在前端，就可以使用 /api/whoami 這隻 API 來得到使用者的資訊囉！

上圖的流程如下：

前往登入頁面，並使用 Google 進行登入
登入成功後，打 /api/auth/google API，Body 夾帶 Google OAuth 回傳的 access_token。
/api/auth/google API 回傳後端產生的時效七天的 JWT，並設置於 cookie 的 access_token，並將前端頁面導航至 /whoami 頁面。
在 /whoami 頁面，點擊「打 /api/whoami API」按鈕，送出 /api/whoami API 請求，瀏覽器會自動夾帶 cookie 至後端。
後端 API /api/whoami 收到請求後，從 cookie 中解析出 access_token 的值，並驗證解析出 JWT 內含的使用者資訊，並將其回傳至前端渲染。

pages/whoami.vue 完整程式碼：

pages/whoami.vue

 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
33
34
35


<template>
 <div class="flex flex-col items-center justify-center py-12 px-4 sm:px-6 lg:px-8">
 <div class="w-full max-w-md">
 <div class="flex flex-col items-center">
 <h2 class="mt-6 text-center text-3xl font-bold tracking-tight text-gray-700">我是誰</h2>
 </div>
 </div>

 <div class="mt-6 flex w-full max-w-md flex-col items-center">
 <button
 type="button"
 class="mt-2 w-fit rounded-sm bg-emerald-500 py-2 px-4 text-sm text-white hover:bg-emerald-600 focus:outline-none focus:ring-2 focus:ring-emerald-400 focus:ring-offset-2"
 @click="whoami"
 >
 打 /api/whoami API
 </button>
 </div>

 <div v-if="userInfo" class="mt-8 flex w-full max-w-md flex-col">
 <div v-for="key in Object.keys(userInfo)" :key="key" class="mt-1 flex flex-wrap break-all">
 <label class="text-lg font-semibold text-emerald-500"> {{ key }}:</label>
 <span class="ml-2 flex flex-1 text-lg text-slate-700">{{ userInfo[key] }}</span>
 </div>
 </div>
 </div>
</template>

<script setup>
const userInfo = ref()
const whoami = () => {
 useFetch('/api/whoami').then((response) => {
 userInfo.value = response.data.value
 })
}
</script>

至此，我們就實作出一個 Google OAuth 的登入及驗證機制，後續可以再將這些資訊儲存至資料庫之中做後續的使用。

這個範例的完整程式碼可以參考 Nuxt 3 - 使用 Cookie 與 JWT 做使用者驗證

小提醒，如果是在伺服器端打 API，可以使用 useRequestHeaders 就可以從伺服器端訪問和代理 cookie 到 API。

1
2
3
4
5


<script setup>
const { data: userInfo } = await useFetch('/api/whoami', {
 headers: useRequestHeaders(['cookie'])
})
</script>

Cookie、LocalStorage、Token 與 JWT

在做使用者驗證的時候，Cookie、LocalStorage、Token 與 JWT 是個重要的概念，這邊稍微簡述一下之間的差異與使用情境。

通常採用 Cookie 來驗證使用者時，當使用者登入成功，會由伺服器端產生一組 cookie 來當作後續驗證使用的依據，這個依據會是一個字串形式，瀏覽器每次發送請求時會自動夾帶符合 Domain、路徑設定等的 cookie，伺服器端就可以依據 cookie 來解析驗證這個字串所代表的涵意，例如是不是匹配代表某位使用者字串。

如同前面的例子，我們將一組能夠代表 Ryan 的 JWT 由登入後產生，並在後續請求中夾帶，以達到驗證使用者的效果。

這串字串，不一定是要 JWT，只要伺服器端能回推或從資料庫比對出所代表的使用者或特定資訊，那麼也可以是隨意產生的字串。

LocalStorage

LocalStorage 是現今瀏覽器基本上都支援的一個儲存空間，同樣具有 Domain 的寫入與讀取的概念，在 cookie 我們最多只能儲存 4KB 左右的字串資料，但是在 LocalStorage 通常有 5MB 所以能夠儲存更多的資訊。

也有網站會把驗證使用者的 Token 或憑證依據儲存在 LocalStorage，之後發送請求或需要時再從中拿取出來並手動夾帶出去，同樣也可以實作出驗證使用者的流程。

在瀏覽器的儲存空間，還有一個 SessionStorage，儲存在這裡面的資料，當網頁關閉時，就會自動清除。與 LocalStorage 不同，除非手動或使用 JS 清除，不然資料永遠存在，也不會有過期時間。

Token

用於提供給使用者後續夾帶給後端的憑據，相當於一個身分證，Token 通常由字串組成，且需要夠長不容易被暴力嘗試破解，Token 字串通常不具有任何意義，直至後端與資料庫或其他方式比對後，會對應出 Token 所代表的意義，例如使用者資訊。

通常請求夾帶的 Token，需要每次往快取或資料庫做比對，才能知道 Token 所代表的使用者。

JWT(JSON Web Token)

JWT 是一種開放的標準 RFC 7519，如同名字 JWT 是基於 JSON Object 所編碼出來的，JWT 是由三個部分 Header、Payload 及 Signature 組合而成。

其中最大的特色就是 Payload 這個部分，當後端伺服器收到 JWT 時，可以從 Payload 解析出當初簽發 JWT 所包含的資訊，通常會在 Payload 放置使用者的相關資料，如 Id、姓名或信箱等，因為這個特色我們不需要再比對快取或資料庫，就可以直接解析出使用者資料。

而 Payload 這個欄位，因為可以被解碼出來，再任意的修改後重新編碼，所以我們就會借助 Header 及 Signature 這兩個部分，來確認當初加密的演算法及驗證簽章是否符合，以防止 Payload 被任意的竄改。

Token 或 JWT 選哪一個？

這兩者之間各有優缺點，雖然自產 Token 需要每次比對資料庫，但是能有效的記錄使用者 Token 核發使用的位置及註銷特定的 Token，因為 JWT 在簽發後，一定得等到過期才會失效無法使用，也就導致 JWT 在核發之後是無法註銷的，除非自己在實作一個黑名單或白名單的機制。

可以依據使用的情境來決定 Token 或 JWT，只要記得使用 Token 作為解決方案，要保證 Token 足夠複雜或隨機，不容易被推測或暴力嘗試，如果真的要使用比較短的 Token 也確保過期的時間不要設定太長，要頻繁的更換這組 Token 或添加其他驗證機制。

而 JWT 的利於可以包含 Payload，也切記在後端核發時不要將敏感資料或密鑰夾帶在 Payload 之中，因為 JWT 的 Payload 就算不知道加密的私鑰還是可以被解碼的。而簽發 JWT 選擇加密的方式也盡量採用非對稱式的家姐密，例如使用 ES256 (ECDSA-SHA256) 演算法產生的非對稱金鑰來進行加密。

後端產生的 Token 或 JWT，不管存放在 Cookie 或 LocalStorage 只要注意其特性及安全，那麼想存在哪裡，都是可以被接受的。

放在 Cookie

將 Token 存放在 Cookie 的好處，可以用來控制網站的 Domain 或 SubDomain 進行存取，也可以設定過期時間來控制前端是否要重新問後端產生新的 Token，最大的特點就是自動夾帶在每個請求當中，也因為這項特性，有一些資安風險就需要稍微注意一下。

跨站請求偽造 (Cross Site Request Forgery, CSRF) 就是一個 cookie 使用時所需要注意的資安問題，所以當使用 cookie 作為驗證機制時，建議在敏感的操作上多添加驗證的機制，或使用 CSRF Token 來保護你的 cookie 不被隨意偽造請求的夾帶出去。

將 Token 或敏感資料儲存在 cooike 時，還是可以透過 JavaScript 的 document.cookie 做存取，所以如果網站有存在跨網站指令碼 (Cross-site scripting, XSS) 的弱點，你的 cookie 很可能就會直接被偷走，為了防止 XSS 弱點導致 cookie 外洩，你可以將 cookie 設值時的屬性 httpOnly 設置為 true，讓客戶端瀏覽器無法直接存取，僅有在發送請求時，由瀏覽器自動夾帶至後端，此外，也可以設置 secure 讓 cookie 只在 HTTPS 下傳輸。

放在 LocalStorage

關於 Token 是否儲存在 LocalStorage 其實有不同的看法，因為 cookie 存在著 CSRF 或 XSS 等問題需要解決，而存放在 LocalStorage 不僅有更大的空間，還不自帶免疫 CSRF，難道不香嗎？

但是別忘了 LocalStorage 也是透過 JS 來做儲存與讀取，所以就算使用 LocalStorage 了，但 XSS 弱點如果存在，你的 Token 一樣有外洩的可能性。

而且 LocalStorage 不具有過期自動刪除的特性，除非自己實作或刪除否則將永遠的存在瀏覽器之中。

所以？

網路上有許多使用 Cookie 或 LocalStorage 儲存 Token 說法，有興趣也可以看看兩派各自論述的優缺點，所以，不管是 Cookie 還是 LocalStorage 沒有說一定不能使用誰，而是要依據特性及情境來做使用，並做好定期重新產生及相關的安全配置。

我自己大概會依照這個網站或服務，是相對簡單也比較不會有會造成悲劇的操作或內容管理為主的服務，我可能就會採用 cookie 的方案處理驗證，因為相對來說自動夾帶與有效期限及 httpOnly 來控制客戶端是否能直接存取，對我來說還是挺方便與安全的，可能在適當的時機再添加 CSRF Token 或多道驗證機制，就能安全的使用 cookie。

而在多為內部系統使用或是 API 在 Mobile App 甚至是不支援 Cookie 環境之下需要使用 Token 來驗證，我就會採納將 Token 儲存在 LocalStorage。

搜尋引擎最佳化 (SEO) 與 HTML Meta Tag

選擇使用 Nuxt 3 作為網站開發框架的開發者，多數都是為了要使用 SSR 或 SSG 來加強對 SEO 的優化設置，這篇將會講述 Nuxt 提供的幾個組合式函數，來協助我們設置網頁的標題、內文、Meta 等，以此來設置 SEO 或外部連結可能會解析到的標籤與數值內容。

搜尋引擎最佳化 (SEO) - 網站的標題 (Title) 與描述 (Description)

當網站需要做搜尋引擎最佳化 (SEO) 的時候，Meta Tag 這個名詞你一定不能忽略，Meta Tag 稱之為元標籤或描述標籤，顧名思義，是來額外描述網頁的資料使用；Meta Tag 通常放置在 HTML 的中，雖然 Meta Tag 不會直接顯示在網頁上，但對於搜尋引擎的爬蟲來說，是相當重要的一項識別資訊，也是 Facebook 提出的 Open Graph 放置的位置，讓網頁的標題、描述或縮圖等，能正確的被解析顯示出來。

那麼網頁標題與描述，如果正確設定會有什麼樣子的效果呢？舉例來說，前面的【串接 Google OAuth 登入】我們可以透過網頁原始碼來查看，可以發現 <title> 與 <meta name="description" … /> 都有設定。

搜尋引擎爬蟲在收錄網頁時，就會解析這些標籤來建立索引，我們在使用搜尋資料時，網頁的資訊也就對應著顯示出來，如下圖。

各家的搜尋引擎爬蟲，雖然都有自己解析的規則，不過根據 SEO 的經驗都有大方向能夠依循做建立，此外就是在針對特定的搜尋引擎加強識別標記，遵照官方指引就能讓網站的內容能見度有顯著提升。

網站的 Open Graph (OG)

OG 是由 Facebook 所提出的設定，全名為 Open Graph Protocol，官方翻譯為「開放社交關係圖」，在設定網站的 Meta 時通常也稱 OG Tag，Facebook 提供了網站管理員分享指南，當初設計的目的是，當網頁中設定了 OG Tag，能讓網頁被分享至社群媒體時，能有呈現更為豐富的內容，例如標題、描述及縮圖等。

舉例來說，當網頁設定了 OG Tag，以連結形式被分享至 Facebook，會呈現如下的資訊，Facebook 會解析網頁內的 OG Tag 將對應的如標題及縮圖等資訊顯示出來。

其中縮圖依照 Facebook 的指引，即是對應網頁中的 <meta property="og:image" ... />。

不只是在 Facebook 上分享連結會有連結預覽的效果，也因為大家都遵循著 OG Tag 進行設定，所以在其他主流的社群媒體或通訊軟體等也都有跟進解析。例如，我們使用 LINE 傳送一條連結，也會因為設置了 OG Tag 也有成功解析出連結預覽的效果。

LINE 開發者也有提供一些問答指引可以做參考，連結預覽與 og:title、og:description 和 og:image 有著相應的設定關係。

useHead

我們可以使用 Nuxt 3 提供的 useHead() 組合式函數，來設定網站的一些標籤或標記，使用方式如下：

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


<script setup>
useHead({
 title: 'Nuxt 3 Blog',
 viewport: 'width=device-width, initial-scale=1, maximum-scale=1',
 charset: 'utf-8',
 meta: [
 { name: 'description', content: '這裡是 Nuxt 3 學習筆記 實戰部落格' }
 ],
 bodyAttrs: {
 class: 'test'
 }
})
</script>

useHead() 函數接受參數的類型如下：

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


useHead(meta: Computable<MetaObject>): void

interface MetaObject extends Record<string, any> {
 charset?: string
 viewport?: string
 meta?: Array<Record<string, any>>
 link?: Array<Record<string, any>>
 style?: Array<Record<string, any>>
 script?: Array<Record<string, any>>
 noscript?: Array<Record<string, any>>
 titleTemplate?: string | ((title: string) => string)
 title?: string
 bodyAttrs?: Record<string, any>
 htmlAttrs?: Record<string, any>
}

charset：指定 HTML 的字元編碼，預設為 utf-8。
viewport：設定網頁的可見區域，預設為 width=device-width, initial-scale=1。
meta：接受一個陣列，陣列中的每個元素，都將會建立一個 <meta> 標記，元素中物件的屬性將對應至的屬性。
link：接受一個陣列，陣列中的每個元素，都將會建立一個 <link> 標記，元素中物件的屬性將對應至的屬性。
style：接受一個陣列，陣列中的每個元素，都將會建立一個 <style> 標記，元素中物件的屬性將對應至的屬性。
script：接受一個陣列，陣列中的每個元素，都將會建立一個 <script> 標記，元素中物件的屬性將對應至的屬性。
noscript：接受一個陣列，陣列中的每個元素，都將會建立一個 <noscript> 標記，元素中物件的屬性將對應至的屬性。
titleTemplage：接受一個字串或函數，用來動態的設定該頁面元件的網頁標題。
title：在頁面元件設置靜態的網頁標題。
bodyAttrs：接受一個物件，設置網頁中標籤的屬性，物件中的屬性將對應至的屬性。
htmlAttrs：接受一個物件，設置網頁中標籤的屬性，物件中的屬性將對應至的屬性。

自訂 Metadata

使用 useHead() 函數設定屬性所傳入的字串或物件可以是具有響應性的變數，當數值變動時，相對應的數值也會一同響應，例如下面的程式碼，可以動態的變更標題或描述。

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


<script setup>
 const title = ref('Nuxt 3 Blog')
 const description = ref('這裡是 Nuxt 3 學習筆記 實戰部落格')

 useHead({
 title,
 meta: [
 {
 name: 'description',
 content: description
 }
 ]
 })
</script>

添加動態網頁的標題

我們可以在 app.vue 添加如下程式碼，titleTemplage 中的 %s 將會帶入目前頁面 title 或更上層頁面的 title 屬性：

app.vue

1
2
3
4
5
6
7
8


<script setup>
const title = ref('Nuxt 3 Blog')

useHead({
 title,
 titleTemplate: '%s - 首頁',
})
</script>

可以看到網頁的標題變為「Nuxt 3 Blog - 首頁」。

你也可以傳入一個函數來動態的添加網頁的標題。

app.vue

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


<script setup>
const title = ref('Nuxt 3 Blog')

useHead({
 title,
 titleTemplate: (title) => {
 return title ? `${title} - 首頁` : '首頁'
 }
})
</script>

添加外部 CSS

我可以使用 useHead() 來添加 Google 字體至 link 屬性之中。

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


<script setup>
 useHead({
 link: [
 {
 rel: 'preconnect',
 href: 'https://fonts.googleapis.com'
 },
 {
 rel: 'stylesheet',
 href: 'https://fonts.googleapis.com/css2?family=Roboto&display=swap',
 crossorigin: ''
 }
 ]
 })
</script>

添加第三方的 JavaScript

你也可以使用 useHead() 來插入第三方的 JS。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


<script setup>
 useHead({
 script: [
 {
 src: 'https://third-party-script.com',
 body: true
 }
 ]
 })
</script>

在模板中使用相對應的元件設置屬性及標籤

Nuxt 提供 <Title>、<Base>、<Script>、<NoScript>、<Style>、<Meta>、<Link>、<Body>、<Html> 和 <Head>，我們可以直接在元件中模板 (Template) 使用這些元件進行設定網頁的屬性及標籤。

因為這些元件名稱與原生 HTML 標記相似，所以記得在模板中使用要開頭為大寫。

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


<template>
 <div>
 <Head>
 <Title>{{ title }}</Title>
 <Meta name="description" :content="description" />
 <Style type="text/css" children="body { background-color: green; }"></Style>
 </Head>
 <h1>{{ title }}</h1>
 </div>
</template>

<script setup>
const title = ref('Nuxt 3 Blog')
const description = ref('這裡是 Nuxt 3 學習筆記 實戰部落格')
</script>

definePageMeta()

我們其實在前面就有使用過 definePageMeta() 來設置頁面的布局或中間件，在各個頁面之中，我們也可以使用 definePageMeta() 來設置一些屬性與 useHead() 進行搭配。

例如，我們的 app.vue 使用 useHead 設定的一個 meta，並且是根據 route.meta.title 所動態的設定。

app.vue

1
2
3
4
5
6
7


<script setup>
const route = useRoute()

useHead({
 meta: [{ name: 'og:title', content: `${route.meta.title} | Nuxt 3 Blog` }]
})
</script>

我們在 pages/articles.vue 添加如下程式碼：

pages/articles.vue

1
2
3
4
5


<script setup>
definePageMeta({
 title: '所有文章'
})
</script>

當我們瀏覽 /articles 頁面時，Nuxt 在伺服器端就幫我們渲染好 og:title 的 meta 了。我們可以透過檢視原始碼的方式來看看效果。

在 Nuxt 3 提供了一些可以設置網頁屬性與 Meta 的組合式函數，更能動態的調整與響應，結合 SSR 讓這些標記在伺服器端就能渲染出來，對網站做搜尋引擎最佳化 (SEO) 非常得友善，也是多數人選擇 Nuxt 3 來處理 SSR 與 SEO 的原因。除了 SEO 可能會使用到的標記外，也有 OG Tag 可以加強網頁的連結預覽效果，雖然 OG Tag 與 SEO 沒有絕對的關係，但是透過伺服器端渲染調整這些 Meta 對搜尋引擎或網站都非常的方便，我們只要根據需求及指引做設定，就能對網站的能見度有所提升。

Public 與 Assets 資源目錄(Nuxt 3 的靜態資源)

在網站的開發過程中，多少會使用到圖片、樣式或設定字體，而當這些檔案若沒有外部連結或某些需求下需要包含在專案內做使用，最後連帶這些檔案一起部署。在使用 create-vue 建立的 Vue 的專案下包含了 public 與 src 內的 assets 目錄，這兩個目錄都是可以放置這類不常變動的靜態資源，但這兩個目錄各自因為一些特性，建議放置的檔案類型依據使用目的有所區別。

Nuxt 3 使用專案下的兩個目錄來提供使用者處理圖片、樣式或字體，這兩個目錄分別為 public 與 assets。

public 目錄

在 Nuxt 3 的專案根目錄下，存在一個名為 public 的目錄，這個目錄如同 Vue 中的 public 目錄或 Nuxt 2 中的 static 目錄。這個目錄下的檔案，將會由 Nuxt 直接於網站的根路徑，例如 / 提供存取。

例如建立 public/robots.txt 將可以使用 http://localhost:3000/robots.txt 存取。

通常我們會在 public 目錄放置不常更動的檔案，或是需要保留檔案的名稱，例如 robots.txt 就需要一個固定的名稱，才能正確的被搜尋引擎的爬蟲所解析再決定檢索的規則，抑或 sitemap.xml 與 favicon.ico 檔案等，都很適合放置在 public 目錄。

你可能也會想，那圖片或 CSS 樣式，我也不常變動，難道就不能放置在 public 目錄嗎？

行，當然行，哪次不行！

舉個例子，我們將這張圖片放置於 public 目錄下並命名為 bg.png，專案目錄下其他檔案就先不列，整個結構大概長的像下面這樣。

1
2
3
4


nuxt-app/
├── public/
│ └── bg.png
└── app.vue

根據規則，我可以使用 http://localhost:3000/bg.png 存取，如下圖我們確實成功的能存取到圖片。

所以，我們在 app.vue 新增如下程式碼，使用 /bg.png 來等同訪問 public/bg.png 檔案：

app.vue

1
2
3
4
5


<template>
 <div>
 <img src="/bg.png" />
 </div>
</template>

也確實能在網頁中使用 <img src="/bg.png" /> 來顯示圖片。

既然 public 目錄已經能提供靜態資源的連結，那麼為什麼還有一個名為 assets 的目錄呢？接下來我們先介紹 assets 目錄，最後再來總結一下差異。

assets 目錄

Nuxt 3 使用 Vite 或 Webpack 來建構專案進行打包，這些建構工具主要功能是用來處理 JavaScript 檔案將其編譯、轉換或壓縮等，但它們可以透過各自的插件或 Loader 來處理其他檔案類型的資源，例如樣式、字體或 SVG 等。

舉例來說，我們在 assets 下建立一個 Sass 的樣式，當這個 Sass 檔案被載入使用，就會經過插件或 Loader 來進行 CSS 的預處理及編譯，最終產生一個 CSS 檔案，也可以針對單純的 CSS 檔案進行壓縮。又或者說，當使用 <img> 的 src 屬性設定載入我們放置在 assets 的圖片或圖示，最終需要轉換為 Base64 編碼而不是產生一個連結，我們也需要依賴建構工具插件的擴展來幫助。

其主要的目的，不外乎就是為了效能與解決瀏覽器的快取。放置在 assets 目錄下的檔案，可能會被插件或 Loader 進行轉換或壓縮，最終產生出來的檔案也具備連結可以進行存取。

如果使用 public 目錄下導出的 /bg.png，就算我們替換了 bg.png 圖片，可能就會因為檔案根據檔案名稱被瀏覽器快取住，導致前端還是看到舊的檔案。我們在使用 assets 目錄下的檔案時雖然檔名都是 bg.png，但在建構時產生的檔案通常會夾帶 Hash，例如：bg.16a2f98c.png，如此一來我們每次更新圖片，都都會隨機的產生一組 Hash 就能防止瀏覽器快取，導致好像網站更新失效的錯覺。

舉例來說，我們以相同的圖片，改放置於 assets/bg.png：

1
2
3
4


nuxt-app/
├── assets/
│ └── bg.png
└── app.vue

app.vue

1
2
3
4
5


<template>
 <div>
 <img src="~/assets/bg.png" />
 </div>
</template>

在開發環境 ~/assets/bg.png 會轉換為 /_nuxt/assets/bg.png，實際上也能使用 http://localhost:3000/_nuxt/assets/bg.png 進行訪問。

除了 ~/assets 可以對應 assets 目錄外，也可以參考官方的 alias 更多或自訂別名來使用相對路徑。

但當你的網站部署完成或啟動建構出來的專案，會發現圖片檔名包含了 Hash，例如 /_nuxt/bg.0a299ea1.png。

最後我們以最終建構出來的專案結構對比如下圖，在 public 目錄下的檔案，會原封不動的照搬至 .output/public 下，也就可以使用 /bg.png 存取；而放置在 assets 下的檔案，可能會被處理加工，最後檔案名稱會加上一個 Hash 並放置在 .output/public/_nuxt 下，也就需要使用 /_nuxt/bg.0a299ea1.png 存取。

總結來說多數情況建議把靜態資源放置在 assets，也因為靜態資源多為 SFC 所使用，通常也會放置最多檔案，最後建構時也會因為建構工具的設定來進行轉換或壓縮，最後添加 Hash 來提供存取，也因為每次建構產生的檔案都不一樣，所以不適合直接以完整的 URL 供外部連結使用。而當有些例外情況不適合，例如 robots.txt 或 sitemap.xml 這類的檔案不需要經過額外處理且需要絕對路徑保持檔案名稱，那就得放置在 public 目錄下提供存取。

發布網站前的建構打包 (Build) 與靜態網站生成 (Static Site Generation)

當網站開發完成或有導入 CI/CD，在準備發布網站前，我們會將 Nuxt 網站的開發專案透過 Nuxt 提供的指令，我們可以來建構出正式環境所需要的版本，這個建構的過程你可以理解為專案將會打包需要的依賴套件、編譯與轉換相關的 Vue SFC 與樣式等，甚至幫你壓縮這些檔案等許多步驟，這些繁瑣的過程都透過 Nuxt 的建構指令來幫你完成，你可以結合一些設定參數與指令，來幫助你建構出正式環境所需要的網站專案，最後再進行部署的動作。

Nuxt 3 專案如何建構正式環境版本？

當我們建立一個乾淨的 Nuxt 3 專案，可以使用 package.json 中 scripts 內的指令來進行建構或預渲染產生靜態頁面：

1
2
3
4
5


npm run build
npm run generate
# or
# yarn run build
# yarn run generate

或者你也可以使用 Nuxt CLI 來達到一樣的效果：

1
2


npx nuxi build
npx nuxi generate

generate 指令會觸發 build 的指令並帶有 prerender 為 true 的參數，最終產生出來的目錄可以直接進行部署，不需要再執行一次 build 的指令。

使用預設配置進行建構 - 建構通用渲染 (Universal Rendering) 的網站

這邊我們以【Nuxt3】實戰練習 - 實作部落格所建立的部落格作為範例，來嘗試以預設的配置進行建構，目前 Nuxt 3 預設 nuxt.config.ts 中 ssr 屬性為 true，也就使用通用渲染 (Universal Rendering)。

我們進入專案目錄，執行下列指令：

1
2
3


npm run build
# or
# yarn run build

不需要在額外的配置或步驟，Nuxt 就會自動幫我們打包並建構出可以部署的網站。

建構完成後會在專案目錄下多出一個 .output 目錄，public 就是在網站根目錄直接公開打包後的 JS、CSS 圖片等相關檔案。由於通用渲染使用 Nitro 作為服務引擎，所以會需要使用 Node.js 來啟動我們的服務，所以 server 則是會放置伺服器端的 Nitro、Server API 處理邏輯等。

我們可以先在本地執行下列指令來預覽建構出來的網站與 Nitro 是否能運作正常。

1

node .output/server/index.mjs

當確認沒問題後，就能以 .output 目錄進行網站部署。

使用預渲染建置全靜態頁面網站

我們可以在 Nuxt 3 建構時期來進行預渲染 (pre-rendering)，將專案內需要打 API 請求及動態渲染元件的地方，先渲染生成出 HTML 網頁，這個過程也稱之為靜態網站生成 (Static Site Generation)，進而建構出全靜態頁面的網站。

執行下列指令進行靜態頁面生成：

1
2
3


npm run generate
# or
# yarn run generate

generate 指令會觸發 build 的指令並帶有 prerender 為 true 的參數，最終會提示產生的目錄 .output/public 可以用來部署至靜態託管伺服器。

當建構完成後，會在專案目錄下多出一個 .output 目錄同時也會有 dist 目錄，可以發現 .output/public 目錄內容與 dist 目錄相同。

靜態頁面的生成因為 Nuxt 使用基於爬蟲的技術為每個頁面產生 HTML 與 Payload 檔案，可以發現產生的靜態頁面目錄結構，也對應著我們專案的路由頁面，而頁面元件資料夾內會由一個 index.html 與 _payload.js 組成。

下圖所產生的結構，是因為我們的部落格資料庫內已經有三筆文章資料，/articles 頁面會取得所有的文章，並列出對應著 /articles/1、/articles/2 與 /articles/3 目錄，每個頁面內也都包含預先從 Server API 請求好的文章資料並存於 _payload.js 之中。

至此我們就可以將 .output 目錄部署至伺服器或靜態託管服務，而且也不需要在使用 Node.js 伺服器來服務這些靜態檔案。

手動設定預渲染的路由規則

我們使用 generate 指令所產生的全靜態頁面網站，是基於 Nuxt 的爬蟲技術來分析頁面，如同前個例子文章頁面的產生所描述，如果我們的資料庫存在著 200 筆資料，但 /articles 頁面所打的 API 總是只回傳最新的 10 筆，那麼那些沒有路由連結可以連結過去的文章頁面，就無法被 Nuxt 的爬蟲所分析到，也就無法產生對應的靜態頁面。

為了解決這個問題，我們可以藉由配置 Nitro 的預渲染路由，來手動的設定哪些頁面要進行預渲染產生靜態頁面，或者忽略產生靜態頁面。

nuxt.config.ts

1
2
3
4
5
6
7
8
9


export default defineNuxtConfig({
 nitro: {
 prerender: {
 ignore: [], // 忽略特定路由不進行預渲染
 routes: [], // 指定路由進行預渲染
 crawlLinks: true // 啟用 Nuxt 爬蟲蒐集頁面連結來進行預渲染
 }
 }
})

當然，也可以搭配 build 或 generate 指令做使用，但會稍微有些不一樣。

build

例如：設置如下，並使用 npm run build 指令。

1
2
3
4
5
6
7


export default defineNuxtConfig({
 nitro: {
 prerender: {
 routes: ['/articles', '/articles/2']
 }
 }
})

那麼建構出來的通用渲染網站，就會包含部分頁面是已經預渲染好的靜態頁面。

generate

當我們使用 generate 時，因為是進行全站的靜態頁面生成，所以基本上涵蓋了所有路由頁面，並且 nitro.prerender.crawlLinks 屬性預設為 true 會啟用 Nuxt 爬蟲來蒐集整的網站的路由頁面，進而開始預渲染產生靜態頁面。

例如：設置如下，並使用 npm run generate 指令。

1
2
3
4
5
6
7
8
9


export default defineNuxtConfig({
 nitro: {
 prerender: {
 ignore: ['/login', '/register'],
 routes: ['/articles/2'],
 crawlLinks: true
 }
 },
})

那麼建構出來的 .output 目錄，就會因為設置了 nitro.prerender.ignore 而忽略 /login 與 /register 頁面的靜態生成，而 /articles/2 在網站中因為沒有任何頁面能連結到此，所以 Nuxy 爬蟲無法蒐集到，所以可以手動添加進 nitro.prerender.routes 之中。

如果我們將 nitro.prerender.crawlLinks 屬性設為 false，那麼在產生靜態頁面的時候，就算 /articles 包含了所有文章的連結，Nuxt 爬蟲也就不會蒐集連結來產生靜態頁面，而是僅依照專案目錄下的 pages 所產生出的路由但不包含 [id].vue 這類動態匹配的路由來產生靜態頁面。

建構僅在客戶端渲染的網站

同樣的使用部落格作為範例，來嘗試將 nuxt.config.ts 中 ssr 屬性設為 false，也就讓網站僅在客戶端渲染 (Client-side Only Rendering)。

執行下列指令進行建構：

1
2
3


npm run build
# or
# yarn run build

建構完成後，會在專案目錄下多出一個 .output 目錄，可以發現 public 目錄結構與通用渲染建構出的不大一樣，多出了像 Vue 專案建構完成後的 index.html 檔案，來作為顯示的容器。

這邊比較需要留意的地方是，當我們將 ssr 屬性設為 false，也還是會在 .output 建構出 server 目錄，也擁有著 .output/server/index.mjs。

那這不就意謂著我還是得有 Node.js 服務才能部署嗎？其實你可以這麼理解，當我們設定 Nuxt 僅在客戶端進行渲染，但 Nuxt 專案中仍然可能有 Server API，這個屬於伺服器端的 API，總不可能一同打包至前端去做架設吧！所以使用 npm run build 建構出來的專案，都會使用 Nitro 引擎來啟動服務，若有 Server API 的處理邏輯，則會連帶打包進 .output/server 目錄之下。

如果你確定 Nuxt 的專案內沒有自己實作的 Server API，全部是依賴非專案內的 Server API，那麼你可以直接將 public 目錄，視為 Vue 建構出的 dist 目錄來進行部署，因為選擇不再需要 Nitro 引擎來為我們提供 Web Server 的服務，且專案內的前端也都打包完在 public 下可以視為 SPA 網站。

整理這些排列建構參數的組合

相信看到這裡，可能對建構與產生靜態頁面有一點混亂了，這邊稍微整理了一下，大家可以再依據需求來啟用相對應的配置：

npm run build + ssr: true

build + ssr: true

Nuxt 3 預設的建構參數，使用通用渲染 (Universal Rendering) 模式。

build + ssr: true + nitro.prerender.crawlLinks: true

使用通用渲染模式，頁面中需要打 API 動態產生的連結而被 Nuxt 爬蟲所蒐集到的頁面將被預渲染成靜態頁面。

build + ssr: true + nitro.prerender.routes + nitro.prerender.crawlLinks: false

使用通用渲染模式，但指定頁面預渲染成靜態頁面。

npm run build + ssr: false

build + ssr: false

僅在客戶端渲染 (Client-side Only Rendering) 的模式，部署時同樣需要使用 server 中的 index.mjs 來啟動 Nitro 伺服器，這樣才能正確的運作 Server API；除非確認專案內完全無依賴專案內的 Server API，則可以直接將 .output/public 視為 Vue 的 dist 目錄進行部署。

npm run generate + ssr: true

generate + ssr: true

使用預渲染產生靜態頁面，預設產生全站靜態頁面，generate 下 nitro.prerender.crawlLinks 屬性預設變為 true，整個網站包含 Nuxt 爬蟲所蒐集到的頁面將被預渲染成靜態頁面。

generate + ssr: true + nitro.prerender.ignore

使用 generate 已經包含整個網站，如果想要忽略某些頁面進行預渲染，可以添加路由至 nitro.prerender.ignore 中。但是需要注意，這些被忽略的頁面如果有使用專案內的 Server API 需求，可能就無法正確的在靜態託管平台運作，而外部的倒是不受影響。

generate + ssr: true + nitro.prerender.routes

雖然使用 generate 已經包含整個網站，但 Nuxt 爬蟲所蒐集到的頁面僅為頁面中產生的，如果連結不存在這些頁面內，只能直接從瀏覽器網址列輸入進入，那麼我們可以將路由添加至 nitro.prerender.routes 來額外補充需要預渲染的頁面。

generate + ssr: true + nitro.prerender.routes + nitro.prerender.crawlLinks: false

同樣會產生全站靜態頁面，但不使用 Nuxt 爬蟲所蒐集到的連結頁面，所以這些動態匹配或需要打 API 獲取資料再渲染的頁面，將不會是靜態頁面，因此也需要注意，如果這些頁面有使用專案內的 Server API 需求，可能就無法正確的在靜態託管平台運作，而外部的倒是不受影響。

其它跟建構有關的參數屬性可以再參考官方文件、Vite 與 webpack 建構工具也都能額外設定參數屬性。

Nuxt 的建構指令 build 與產生靜態頁面的 generate 指令，讓我們可以依據不同的情境來決定渲染模式與預渲染的頁面，最終產生的 .output 目錄也會有不一樣的結構。預渲染的頁面與單純的 SPA 也要注意使否有使用到 Nuxt 專案建立的 Server API，再決定是否需要 Nitro 伺服器來啟動正式環境的網站服務。當一切就緒之後最後就能將輸出的目錄打包進行部署。

就剩最後一步了 - 部署 (Deployment)

Nuxt 3 的專案應用程式，可以部署在 Node.js 的伺服器上面，也可以將預渲染的靜態網站由靜態託管平台來服務，或這部署至無伺服器 (serverless) 或 CDN 環境上。

使用 Node.js 伺服器

Nuxt 3 的專案預設使用 Nitro 來作為服務引擎，所以我們在任何 Node.js 伺服器環境之下，基本上都可以啟動 Nuxt 建置出來的 Nitro Server。

當我們使用 npm run build 建構專案後，輸出的 .output/server/index.mjs 檔案，即是一個準備啟動 Node 伺服器的入口點。

我們可以透過下列指令來啟動我們建構好的專案。

1

node .output/server/index.mjs

執行後如下面圖示顯示，網站將於 Prot: 3000 進行服務監聽。

你可以設定下列環境變數來調整預設監聽的 Port 或 Host。

NITRO_PORT 或 PORT：監聽的 Port (預設為 3000)
NITRO_HOST 或 HOST：服務的 Host (沒有預設值，但預設監聽所有的網路介面包含 IPv4 與 IPv6 的位址 )
NITRO_SSL_CERT 與 NITRO_SSL_KEY：如果兩者皆設定，將以 HTTPS 模式下啟動伺服器，通常僅作為測試用途，因為建議將 SSL 憑證等設定於提供反向代理的服務，例如 NGINX 或 CloudFlare，Nitro 伺服器則執行在反向代理後面。

部署時，你可以將整個 .output 上傳至正式環境的機器上，並使用 Node.js 做執行，但為了防止我們的服務因為異常，導致 Node.js 服務意外崩潰，我們需要一個 Process 的 Daemon，來將服務常駐，意外崩潰時能自動重啟，來維持整個網站的正常服務。

通常我們會在正式環境使用 PM2 來管理 Node.js 的服務，PM2 是維持一個 Process 執行的管理器，我們可以藉由 PM2 來啟動我們的 Nitro Server，當服務崩潰時能自動的重新啟動，以維持服務的正常運作，除此之外 PM2 可以啟用叢集 (Cluster) 的功能結合請求的附載平衡，來讓多核心的機器提升資源的利用率與效能，更還有監測多項數據等功能可供正式環境做使用。

使用 PM2

使用的方式也很簡單，首先使用 NPM 安裝 PM2，可以執行下列指令：

1

npm install -g pm2

在 Nuxt 專案目錄下建立 ecosystem.config.js 檔案，內容如下：

ecosystem.config.js

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


module.exports = {
 apps: [
 {
 name: 'NuxtAppName',
 exec_mode: 'cluster',
 instances: 'max',
 script: './.output/server/index.mjs'
 }
 ]
}

接著我們就能使用 PM2 來執行我們的服務：

1

pm2 start ecosystem.config.js

你也可以在 ecosystem.config.js 中添加環境變數。

ecosystem.config.js

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


module.exports = {
 apps: [
 {
 name: 'NuxtAppName',
 exec_mode: 'cluster',
 instances: 'max',
 script: './.output/server/index.mjs',
 env: {
 NITRO_PORT: 3001,
 NITRO_HOST: '127.0.0.1'
 }
 }
 ]
}

製作 Docker Image

目前使用 Docker 來部署服務的也不在少數，個人也是採用容器化來啟動網站服務並整合 CI/CD 自動化的流程來建構與部署 Nuxt 3 專案，以下將列出自己使用的 Dockerfile，有興趣的可以再參考看看。

專案目錄下建立 Dockerfile 檔案，內容如下：

Dockerfile

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


FROM node:16-alpine AS builder

RUN mkdir -p /nuxt-app
WORKDIR /nuxt-app
COPY . .

RUN npm ci && npm cache clean --force
RUN npm run build


FROM keymetrics/pm2:16-alpine

RUN mkdir -p /nuxt-app/.output
WORKDIR /nuxt-app/.output

COPY --from=builder /nuxt-app/.output .
COPY ./ecosystem.config.js /nuxt-app

ENV NUXT_HOST=0.0.0.0
ENV NUXT_PORT=3000

EXPOSE 3000 

ENTRYPOINT ["pm2-runtime", "start", "/nuxt-app/ecosystem.config.js"]

打開終端機 (Terminal)，並於專案目錄下執行下列指令：

1

docker build -t nuxt-app .

當開始製作 Docker Image 時，會依照 Dockerfile 來建置，主要分成兩個部分，首先我會先在 node:16-alpine 容器環境中執行建構 (build) 的指令，並將需要部署的目錄 .output 複製至 keymetrics/pm2:16-alpine 容器環境中，這樣最終使用 PM2 執行服務的 Image 大小就會稍微小一些。

當 Docker Image 製作完畢後，可以再藉由 docker run 或 docker compose 甚至 k8s 來啟動服務後，再由如 NGINX 提供反向代理服務連接到內部的 Nitro Server。

部署至 CloudFlare Workers

我們也可以將 Nuxt 部署到無伺服器 (Serverless) 的環境，官方提供了多種的預設部署可以做使用，我們就簡單以一個乾淨的 Nuxt 3 專案來做範例，嘗試部署到 CloudFlare Workers。

首先，我們先準備一個 Nuxt 3 專案，在此我使用下列指令建立一個乾淨的 Nuxt 3 專案，並進入專案目錄安裝套件：

1
2
3


npx nuxi init nuxt-app
cd nuxt-app
npm install

使用 NPM 安裝 wrangler，它是用於建構 Cloudflare Workers 的命令列工具 (command line tool)。

1

npm install -g wrangler

你可能需要註冊一個 CloudFlare 的帳號，並使用下列指令來登入 CloudFlare 帳號並授權 Wrangler 來建立 CloudFlare Workers，我們選擇允許 (Allow) 即可。

1

wrangler login

於專案目錄下建立 wrangler.toml 內容如下：

wrangler.toml

1
2
3
4
5
6
7


name = "nuxt-app-hello"
main = "./.output/server/index.mjs"
workers_dev = true
compatibility_date = "2022-10-15"

[site]
bucket = ".output/public"

我們將 NITRO_PRESET 環境變數，設置為 cloudflare 並開始建構我們的專案。

1

NITRO_PRESET=cloudflare npm run build

接下來，可以選擇執行終端機提示的指令來啟動伺服器進行相關測試。

1

npx wrangler dev .output/server/index.mjs --site .output/public --local

當確認專案服務運作上沒問題後，可以執行下列指令進行發布。

1

npx wrangler publish

完成發布後，就會提示我們發布完成及服務的網址，例如 https://nuxt-app-hello.ryanchien8125.workers.dev，我們就可以瀏覽我們部署好的網站囉。

靜態的網站部署至 CloudFlare Pages

我們使用 Nuxt 3 可以預渲染全靜態的網站，因此也可以將專案部署至靜態託管平台，以 CloudFlare Pages 為例，部署的步驟如下：

首先，先執行下列指令進行全站的預渲染：

1
2
3


npm run generate
# or
# yarn run generate

使用 NPM 安裝 wrangler。

1

npm install -g wrangler

你可能需要註冊一個 CloudFlare 的帳號，並使用下列指令來登入 CloudFlare 帳號並授權 Wrangler，我們選擇允許 (Allow) 即可。

1

wrangler login

建立一個 CloudFlare Pages 名為 nuxt-app-blog。

1

wrangler pages project create nuxt-app-blog

使用下列指令，將預渲染的網站目錄進行部署，並指定專案名稱為 nuxt-app-blog：

1

wrangler pages publish ./.output/public --project-name nuxt-app-blog

當部署完成後，就會得到一個連結來查看部署的靜態網頁，你也可以從 CloudFlare Pages 後台，看見網站網址的別名 Aliases 來使用自訂的網址。

以上是介紹 Nuxt 3 的幾個部署方式的例子，更多雲端平台上面的部署，也可以參考 Nuxt 與 Nitro 官方文件。

上線前的測試項目

最後與大家分享一下網站專案上線前的幾個我會特別注意的幾個小細節，也歡迎大家一起來交流。

前端細節

網頁的標題 (Title)
使用之資源授權 (使用權、智財權)
圖片替代文字
Favicon
HTML Meta data
Google Analytics

瀏覽器相容性測試

RWD
跨瀏覽器
- BrowserStack
- Comparium
- TestingBot

API 測試

單元測試
不同場景測試 (測試環境、正式環境)
效能測試
- JMeter
- k6
安全性測試

壓力測試

模擬使用者或連線數
觀察機器資源使用量
資料庫連線數觀察
持續提高模擬數量觀察分析
分析每個請求於併發的平均響應時間
是否請求中夾雜非預期之狀態碼 (HTTP Status Code)

API 或網站安全性

參考 OWASP Top 10
SQL 參數化查詢
資安公司滲透測試、紅隊演練

開發或除錯用的訊息

警告訊息或異常訊息移除（console.log 或警告訊息等）
JavaScript Source Maps 記得移除
敏感資訊記得移除 (開發用 Key、帳號密碼等)

網站相依性檢查

使用到第三方網站資源及穩定性
檢查所有網址皆能正常運作
當第三方網站異常時應對措施

部署相關

是否有高可用性 (HA)
Docker 或 Kubernetes 整合
網域時效
SSL 證書日期
防火牆或 WAF 設定
內網或外網區隔

備份機制

靜態有狀態資料 (使用者上傳的)
資料庫資料

這邊主要與大家分享幾種 Nuxt 的部署方式，不管是部署在自己的機房主機或雲端，大家可以在挑選合適的解決方案，Nitro 也支援無伺服器 (Serverless) 等部署方式非常的方便，只是要特別注意到 Serverless 執行一些 binary 的問題，再挑選自己適合的部署與服務方式。

經過本篇文章，大家應該都對於 Nuxt 3 有初步的理解，接下來下一篇文章我們將會進入實戰練習，將會以 Nuxt 3 來實作一個部落格網站！

闡述單元測試、元件測試，並學習在自己的 Vue3 專案中加入 Vitest！

Thu, 29 Dec 2022 00:00:00 +0000

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

網站建置不是件簡單的事，我們都知道網站做好之後，有好多細節需要兼顧，所以許多公司花了大量的時間與金錢，耗用人力對維護中的網站進行不斷的、重複的人工測試，想達到的目的不外乎是希望網站不要出錯，可以給客戶/使用者最好的網站使用體驗。本篇章說明使用 Vue3 開發的專案，導入 Vitest 進行極速單元測試的體驗！

測試的種類

在不同的測試類型中，所需要保護的面向不太相同，以下是不同測試類型的大致介紹：

單元測試 (Unit testing)

以程式碼的最小單位進行測試，保護程式邏輯不會在系統維護的過程中遭到破壞，也進一步確保維護中的程式碼品質。

這種測試類型通常由開發人員自行撰寫，自己寫的 Code 自己寫測試，有經驗的開發人員可以用非常有效率的方式撰寫單元測試，因為測試範圍小，這種類型的測試通常不需要設立測試環境，因此可以得到較高的撰寫效率，也是所有測試類型中最容易撰寫的測試類型。不過，對於一個沒有經驗的開發者來說，撰寫單元測試可能會耗用大量時間，寫測試程式的時間很有可能會遠大於實際撰寫程式碼的時間，有蠻多人會因為這樣而放棄撰寫單元測試。

整合測試 (Integration testing)

整合多方資源進行測試，確保模組與模組之間的互動行為正確無誤，也讓不同模組在各自開發維護的過程中不會因為功能調整而遭到破壞。

這種類型的測試通常介於單元測試與端對端測試之間，有時候會由專職的測試人員進行開發，但大部分還是由開發團隊中負責特定模組的人來撰寫。有時候單一模組即便完全通過單元測試，獨立運作也正常，但是當需要與其他模組互動時，也是有可能發生錯誤，這時就是整合測試的主要負責領域。

以下是未通過整合測試的案例：(兩個元件在整合時發現問題)

端對端測試 (End-to-end testing) (E2E testing)

所謂的「端對端」(E2E) 是指從使用者的角度出發(一端)，對真實系統(另一端)進行測試。

這種類型的測試對許多公司來說，就是「人工測試」的主要範圍，因為你可以透過人工對已經完整部屬的網站進行測試，因此可以驗證出系統是否符合客戶的實際需求。這部分也可以透過撰寫 E2E 測試程式來進行自動化，增加測試效率。

這裡有個未通過 E2E 測試的案例相當有趣，雖然每個整套系統每個模組都通過所有單元測試與整合測試，但最後組裝起來後，從使用者的角度無法接受！

測試案例中的 3A 模式

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


describe('貓咪', () => {
 it('摸摸，應該會發出「呼嚕嚕」聲', () => {
 // ...
 })
 it('餵食，應該會發出「呼嚕嚕」聲', () => {
 // ...
 })
 it('拿玩具逗，應該會發出「呼嚕嚕」聲', () => {
 // ...
 })
 it('什麼都不做，應該推倒眼前看到的所有東西', () => {
 // ...
 })
})

當我們設立好測試情境與測試案例的敘述結構之後，要開始撰寫測試案例內部的實作時就可以利用所謂的 3A 模式來安排。

3A 模式主要是為(Arrange-Act-Assert)三個英文字的縮寫，而他們分別代表了：

準備(Arrange)：準備好受測目標需要的一切，包含依賴的隔離等
操作(Act)：操作受測物目標
斷言(Assert)：預期受測物的某個狀態是否為我們所預期

以上方第一項測試案例來套用 3A 模式的話就會像是：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


it('摸摸，應該會發出「呼嚕嚕」聲', () => {
 // Arrange: 準備好一隻貓
 const target = new Cat()

 // Act: 摸摸那隻貓咪
 target.touch()

 // Assert: 觀察那隻貓是否發出呼嚕嚕叫聲
 expect(target.speaking).toBe('呼嚕嚕')
})

那如果這時候你可能會想到每個測試案例都要準備一隻貓貓，對於測試案例來說就會一直不斷地去做「準備(Arrange)」這個行為，因此你可能會很直覺的這麼處理：

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


describe('貓咪', () => {
 const target = new Cat()
 it('摸摸，應該會發出「呼嚕嚕」聲', () => {
 target.touch()
 expect(target.speaking).toBe('呼嚕嚕')
 })
 it('餵食，應該會發出「呼嚕嚕」聲', () => {
 target.feed('乾乾')
 expect(target.speaking).toBe('呼嚕嚕')
 })
 it('拿玩具逗，應該會發出「呼嚕嚕」聲', () => {
 target.play()
 expect(target.speaking).toBe('呼嚕嚕')
 })
})

但這樣的後果就是每個測試案例之間就會有關聯了，比方貓貓其實摸太多下他也會覺得厭煩，從而導致測試失敗：

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


describe('貓咪', () => {
 const target = new Cat()
 it('摸摸下巴，應該會發出「呼嚕嚕」聲', () => {
 target.touch()
 expect(target.speaking).toBe('呼嚕嚕')
 })
 it('再摸一次下巴，應該會發出「呼嚕嚕」聲', () => {
 target.touch()
 expect(target.speaking).toBe('呼嚕嚕')
 })
 it('再摸一次下巴，應該會發出「呼嚕嚕」聲', () => {
 target.touch()
 expect(target.speaking).toBe('呼嚕嚕') // 預期呼嚕嚕，結果貓咪生氣了
 })
})

而要寫好測試案例的其中幾個概念就是要盡量讓每個測試案例之間「不受順序影響測試結果」與「保持獨立」。

因此大多數的「測試環境」的工具都會提供類似相關的 API 來協助處理測試開始前的「Setup」與結束後的「Teardown」環節。

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


describe('貓咪', () => {
 const target = new Cat()
 beforeEach(() => {
 // 每個測試案例開始前要做的事情
 target.init() // 初始化貓貓的各種狀態
 })
 afterEach(() => {
 // 每個測試案例結束後要做的事情
 })
 it('摸摸，應該會發出「呼嚕嚕」聲', () => {
 target.touch() // 這時候的 target 已經是經過 init() 的版本了
 expect(target.speaking).toBe('呼嚕嚕')
 })
 it('餵食，應該會發出「呼嚕嚕」聲', () => {
 target.feed('乾乾') // 這時候的 target 已經是經過 init() 的版本了
 expect(target.speaking).toBe('呼嚕嚕')
 })
 it('拿玩具逗，應該會發出「呼嚕嚕」聲', () => {
 target.play() // 這時候的 target 已經是經過 init() 的版本了
 expect(target.speaking).toBe('呼嚕嚕')
 })
})

綜合上述 3A 與處理 Setup & Teardown 的觀念，之後再寫測試案例時，我們可以先從基礎的 3A 模式開始撰寫，而到有需要處理重複的事前準備(Setup)與後續清理時(Teardown)，就可以藉由工具來替我們統一處理。

看到這邊讀者應該會發現，測試的基本概念其實不難懂，而在瞭解測試的概念後，剩下的就是把概念轉換為測試工具可讀懂測試程式碼就好了！

專案加入 Vitest

在初始化專案過程加入 Vitest

建立專案時若要加入單元測試要注意到的是：Node.js 版本必須為 14 以上，否則 Vitest 會無法順利執行！

確認 Node.js 版本後，在要建立專案的父層路徑底下透過終端機指令輸入 npm create vite@latest 來建立一個基於 Vite 所建構的專案，接著終端機會出現一些問題，視專案需求選擇：

Project name ⇒ 輸入自訂的專案名稱後按下 Enter
Select a framework ⇒ 選擇 Vue 後按下 Enter
Select a variant ⇒ 選擇 Customize with create-vue 後按下 Enter
中間可能還會有 TypeScript, ESLint⋯⋯等等問題，請視專案需要加入
Add Vitest for Unit Testing(y/n) ⇒ 選擇 Yes 後按下 Enter (最重要的部分

回答完上面的問題後，建構工具就會依據剛才答覆的內容，自動生成需要的部分。

比方在 Add Vitest for Unit Testing 問題回答 Yes 的話，這時建構工具就會在專案中生成單元測試所需要的相關內容如下：

一個位於 ~專案根目錄/src/components/__test__/HelloWorld.spec.js 的測試範例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


import { describe, it, expect } from 'vitest'

import { mount } from '@vue/test-utils'
import HelloWorld from '../HelloWorld.vue'

describe('HelloWorld', () => {
 it('renders properly', () => {
 const wrapper = mount(HelloWorld, { props: { msg: 'Hello Vitest' } })
 expect(wrapper.text()).toContain('Hello Vitest')
 })
})

在 ~專案根目錄/package.json 自動新增一個啟動單元測試的 scripts 指令

1
2
3
4
5


{
 "scripts": {
 "test:unit": "vitest --environment jsdom"
 },
}

在 ~專案根目錄/package.json 自動新增單元測試所需要的工具們

1
2
3
4
5
6
7


{
 "devDependencies": {
 "@vue/test-utils": "^2.0.2",
 "jsdom": "^20.0.0",
 "vitest": "^0.23.0"
 }
}

接著如剛剛終端機後方的提示：

執行 cd {剛才專案名稱} 切換到專案目錄底下
執行 npm install 安裝專案所需要的內容

安裝完畢後，接著就可以執行 npm run dev 確認環境，後續要執行測試的話，執行 npm run test:unit 就能立即運作了。

在既有專案中加入 Vitest

在既有專案中加入 Vitest 來作為執行測試的環境時，需確認專案本身是由 Vite(2.7.10 版本以上)所建構的之外，其 Node.js 版本也必須為 14 以上，否則會無法順利執行測試！

確認好必要條件後就可以開始安裝測試工具：

vitest：單元測試框架(提供了執行測試的環境、斷言、隔離庫⋯⋯等等功能與 API)
@vue/test-utils：測試 Vue 元件的工具
jsdom：讓我們可以在 Node 環境模擬出瀏覽器中的 DOM 環境(方便測試)

1

npm install -D vitest @vue/test-utils jsdom

新增 npm 執行單元測試的指令：

package.json

1
2
3
4
5


{
 "scripts": {
 "test:unit": "vitest --environment jsdom"
 },
}

這時若心急的執行 npm run test:unit 會發現終端機告訴你 No test files found, exiting with code 1，原因是你尚未加入任何一個測試案例。

而一開始 Vitest 預設測試的比對規則是 */*.{test,spec}.{js,mjs,cjs,ts,mts,cts,jsx,tsx}，簡單來說你在專案底下使用 A.test.js 或是 B.spec.ts 的方式都會被 Vitest 認為是測試程式檔。

這時，我們可以在 ~專案根目錄/src/components/__test__/ 底下新建 HelloWorld.spec.js：

src/components/test/HelloWorld.spec.js

1
2
3
4
5
6
7


import { describe, it, expect } from 'vitest'

describe('HelloWorld', () => {
 it('1 + 1 should be 2', () => {
 expect(1 + 1).toBe(2)
 })
})

再次執行 npm run test:unit 終端機就會顯示：

到這裡就算是成功安裝好囉，接下來我們會再把 Vitest Config 初期需要設定的部分調整好後，建置的部分就完成了。

Vitest Config 設定方式

Vitest 測試在執行的時候預設會基於原先專案中的 vite.config.js 設定檔，所以沒有需要調整的話不太需要另外設置，需要調整的話 Vitest 也提供了三種方法讓你在不同開發情境下選擇調整方式：

執行 npm 指令時帶參數指定設定檔案路徑
直接在原先 vite.config.js 中調整
透過 vitest.config.js 檔案調整測試設定

執行 npm 指令時帶參數指定設定檔案路徑

若想要在執行的時候去引入不同的設定檔案，則可以在 package.json 指令中透過 --config 加上設定檔案的路徑(e.g. vitest --config ./src/scripts/vitest.config.js )：

package.json

1
2
3
4
5
6
7


{
 //...
 "scripts": {
 "test:unit": "vitest --config ./src/__test__/config/vitest.config.js",
 }
 //...
}

接著該檔案就如設定 vitest.config.js 一樣調整就可以了：

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


import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

// https://vitejs.dev/config/
export default defineConfig({
 plugins: [
 vue(),
 ],
 test: {
 // 在這邊加入設定
 },
})

在專案中的 vite.config.js 中調整測試設定

若想在原先的 vite.config.js 中調整測試設定，有兩種方式可以使用：

第一種是直接在最上方加入 /// <reference types="vitest" /> 後，在 test 屬性中加入設定：

vite.config.js

1
2
3
4
5
6
7
8


/// <reference types="vitest" />
import { defineConfig } from 'vite'

export default defineConfig({
 test: {
 // 在這邊加入設定
 },
})

第二種，把原先的 defineConfig 改由 vitest/config 傳入後，在 test 屬性中加入設定：

vite.config.js

1
2
3
4
5
6
7


import { defineConfig } from 'vitest/config'

export default defineConfig({
 test: {
 // 在這邊加入設定
 },
})

透過 vitest.config.js 檔案調整測試設定

若想區隔開發與測試用的設定時，可以在專案根目錄中新增 vitest.config.js 檔案，這會比原先參考的 vite.config.js 擁有更高的優先權。

不想將原先在 vite.config.js 設定都重新全寫一次的話，也可以在 vitest.config.js 中，使用 mergeConfig 來融合 vite.config.js 的設定：

1
2
3
4
5
6
7
8
9


import { mergeConfig } from 'vite'
import { defineConfig } from 'vitest/config'
import viteConfig from './vite.config' // 原先的 vite 設定檔案

export default mergeConfig(viteConfig, defineConfig({
 test: {
 // 在這裡加入測試設定
 },
}))

Vitest config option

至於 Vitest config 能調整什麼內容呢，這裡列了幾個常見的調整選項：

include
exclude
globals
environment

註：以下部分資料引用 Vitest Config Option 並翻譯與補充。

include

Type： string[]
預設值： [’**/*.{test,spec}.{js,mjs,cjs,ts,mts,cts,jsx,tsx}']

藉由這個欄位我們可以提供 glob 格式讓 vitest 去比對哪些是測試檔案，也可以放入多個條件在陣列中。

vitest.config.js

1
2
3
4
5
6
7


import { defineConfig } from 'vitest/config'

export default defineConfig({
 test: {
 include: ['**/*.spec.js'],
 },
})

這個設定主要會影響到後續我們要如何擺放測試程式碼，因此做規劃時可以按需求考量調整。

exclude

Type： string[]
預設值： [’/node_modules/’, ‘/dist/’, ‘/cypress/’, ‘/.{idea,git,cache,output,temp}/’]

藉由這個欄位我們可以提供 glob 格式讓 vitest 去排除哪些不是測試檔案，也可以放入多個條件在陣列中。

vitest.config.js

1
2
3
4
5
6
7


import { defineConfig } from 'vitest/config'

export default defineConfig({
 test: {
 exclude: ['**/node_modules/**', '**/dist/**', '**/cypress/**', '**/.{idea,git,cache,output,temp}/**'],
 },
})

與 include 相反，這次則是要排除哪些路徑不需要尋找是否有測試檔案，其中如果有用到 cypress 做 E2E 測試的話，預設規則中就已經有另外排除了，所以沒必要的話不必特別設置，但可以先記得有這個方便的欄位。

Globals

Type： boolean
預設值： false

由於在撰寫測試時，Vitest 預設是需要自己按需要引入對應的方法等等，如果要類似像 Jest 以全域的方式注入到測試中，就可以透過在執行時加上 --globals 選項，或是在 vitest config 選項中加入 globals: true。

vitest.config.js

1
2
3
4
5
6
7


import { defineConfig } from 'vitest/config'

export default defineConfig({
 test: {
 globals: true,
 },
})

原先設定前，測試程式碼需要如下方引入：

1
2
3
4
5
6
7


import { describe, it, expect } from 'vitest'

describe('HelloWorld', () => {
 it('1 + 1 should be 2', () => {
 expect(1 + 1).toBe('2')
 })
})

加入 Globals: true 後，就不需要顯示引入 vitest 測試相關的 API，讓測試看起來更乾淨：

1
2
3
4
5


describe('HelloWorld', () => {
 it('1 + 1 should be 2', () => {
 expect(1 + 1).toBe('2')
 })
})

environment

Type： ’node’ | ‘jsdom’ | ‘happy-dom’ | ’edge-runtime’ | string
預設值： ’node’

由於 Vitest 本身默認環境 Node.js，因此若要在測試中仿造瀏覽器的應用程式，可以透過類似 jsdom 等工具來取代，而已經介紹過的 npm 指令的寫法之外 -environment jsdom ，還可以在測試檔案上以 docblock 或 comment 風格的方式註記。

Docblock 風格：

1
2
3
4
5
6
7
8
9


/**
 * @vitest-environment jsdom
**/

it('use jsdom in this test file', () => {
 const element = document.createElement('div')
 element.innerHTML = '<p>Hello, HTML!</p>'
 expect(element.innerHTML).toBe('<p>Hello, HTML!</p>')
})

Comment 風格：

1
2
3
4
5
6
7


// @vitest-environment jsdom

it('use jsdom in this test file', () => {
 const element = document.createElement('div')
 element.innerHTML = '<p>Hello, HTML!</p>'
 expect(element.innerHTML).toBe('<p>Hello, HTML!</p>')
})

寫在 vitest config 中：

1
2
3
4
5
6
7


import { defineConfig } from 'vitest/config'

export default defineConfig({
 test: {
 environment: 'jsdom',
 },
})

如此一來在測試中我們就可以模擬 Web 端環境來操作了。

以上是 Vitest 幾個比較常見的設定，其餘的設定後續也會按需求陸續提到，若對於其他設定選項有興趣的，也可以直接到官方文件中的 config 分頁查看。

測試的本質

測試的本質究竟是什麼？測試簡單的來說主要就是藉由操控受測物(SUT, System Under Test)，觀察由受測物產生的最終狀態是否如我們所預期的樣子：

若最終狀態符合我們的預期，對於開發者的含義來說，就是受測物符合了我們的期待。

但這點好處看似沒有做「測試」的必要，畢竟我們平時開發能驗收完成不就是符合了規格書的期待嗎？

因此為了能夠更加體會測試背後的價值，我們接下來將實際做一個測試工具來來檢驗我們自己所寫的函式。

情境舉例

首先，情境假設在專案中有一處邏輯判斷需要檢測傳進來資料的是否為數值(Numeric)，而傳進來的資料可能有 1, null, '100', NaN 等。

我們希望當 1 和 '100' 時，該判斷應該要為 true，而 null 與 NaN 則是要為 false。

接下來的目標我們要做的就是：

製作一個簡易的測試工具
寫測試案例
寫受測程式碼的實作

簡易的測試工具

首先規劃一下工具我最後希望用起來像是這個樣子：

expect(受測物).toBe(預期狀態)

回傳 true 表示測試成功 (即為最終狀態與預期狀態相同)
回傳 false 表示測試失敗 (即為最終狀態與預期狀態不同)，然後加上 error 提示預期狀態應該要是什麼，最終狀態目前是什麼。

接著按照上面的設想，先定義了一個宣告函式 expect，參數則是預計輸入受測物(input)與：

1
2
3


const expect = (input) => {
 // ...
}

再來工具本身呼叫時需回傳了一個叫做 toBe 的驗證方法，該驗證方法的參數為預期目標(expected)：

1
2
3
4
5
6


const expect = (input) => {
 const toBe = (expected) => {}
 return {
 toBe
 }
}

接著設計該驗證的方法，使其能夠回應測試的結果：

1
2
3
4
5
6


const expect = (input) => {
 const toBe = (expected) => input === expected
 return {
 toBe
 }
}

現在我們透過網頁瀏覽器的 devtool console 控制台，就可以透過該測試工具做簡易的測試案例了：

1
2
3
4
5
6
7
8


const expect = (input) => {
 const toBe = (expected) => input === expected
 return {
 toBe
 }
}
expect(1 === 1).toBe(true)
expect(2 !== 1).toBe(true)

但我們希望他能夠在測試案例失敗的時候回應一下當下預期與結果的狀況，後續我們才能針對紀錄的結果做修正。因此我們再修改一下測試方法：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


const expect = (input) => {
 const handleOnError = (result, expected) => {
 console.error(`測試失敗：預期應該為 ${expected}，結果現在為 ${result}`)
 return false
 }
 const toBe = (expected) => input === expected ? true : handleOnError(input, expected)
 return {
 toBe
 }
}

再執行一個故意寫錯的測試案例：

1

expect(2 === 1).toBe(true)

現在可以看到當測試案例發生錯誤的時候，除了會回傳測試結果之外，還會多個錯誤提醒目前錯誤的原因了！

寫測試案例

在完成測試工具後，現在我們要來寫測試案例，首先我們先寫一個還沒有寫實作部分的判斷函式(isNumeric)：

1

const isNumeric = (val) => {}

接著按照題目所設定的條件，來撰寫測試案例：

題目設定：
當 1 和 '100' 時，該判斷應該要為 true，
而 null 與 NaN 則是要為 false。

1
2
3
4
5
6


const isNumeric = (val) => {}

expect(isNumeric(1)).toBe(true)
expect(isNumeric('100')).toBe(true)
expect(isNumeric(null)).toBe(false)
expect(isNumeric(NaN)).toBe(false)

此時執行後會發現會發現四個案例都報錯，因為目前我們還沒撰寫 isNumeric 的判斷實作，但到這一步測試案例就已經算是寫好了，因為我們的目的是要寫對的測試案例，讓實作去符合。

寫受測程式碼的實作

完成測試案例後，我們將要來寫測試程式碼的實作部分：

1

const isNumeric = (value) => !isNaN(value - parseFloat(value))

最後，將整個測試與實作合併起來就會像這樣子：

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


// 測試工具程式碼部分
const expect = (input) => {
 const handleOnError = (result, expected) => {
 console.error(`測試失敗：預期應該為 ${expected}，結果現在為 ${result}`)
 return false
 }
 const toBe = (expected) => input === expected ? true : handleOnError(input, expected)
 return {
 toBe
 }
}
// 實作程式碼部分
const isNumeric = (value) => !isNaN(value - parseFloat(value))

// 測試案例部分
expect(isNumeric(1)).toBe(true) // true，即為通過測試
expect(isNumeric('100')).toBe(true) // true，即為通過測試
expect(isNumeric(null)).toBe(false) // true，即為通過測試
expect(isNumeric(NaN)).toBe(false) // true，即為通過測試

完成！現在已經不會顯示測試失敗的訊息了，也就表示 isNumeric 方法符合我們的預期囉。

而現在假使我想使實作程式碼的部分更加的完善，只要增加合適的測試案例進去就可以增添受測物本身的信賴與穩定度：

1
2
3
4
5
6
7


expect(isNumeric(1)).toBe(true)
expect(isNumeric(1.123)).toBe(true)
expect(isNumeric(0xFFF)).toBe(true)
expect(isNumeric('100')).toBe(true)
expect(isNumeric(undefined)).toBe(false)
expect(isNumeric(null)).toBe(false)
expect(isNumeric(NaN)).toBe(false)

甚至將來改寫實作(isNumeric)的時候，既有的測試內容就會提醒你是否違反了之前所寫的測試案例。

測試工具的選擇

上面有提到簡易的測試工具是如何手刻出來的，也稍微談到了手刻測試工具的困難，因此選擇一個適當的測試工具來輔助我們進行測試是有必要性的。

但測試工具百百種，許多工具在提供的功能上又重疊，那麼我們該如何選擇工具呢？

若是以「單元測試」來說的話，我們在撰寫測試程式碼時可能至少就會有以下的需求：

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


/* 引入相關檔案 */

describe('測試情境描述', () => {
 it('測試案例描述', () => {
 const wrapper = mount(component)
 expect(wrapper.text()).toBe('Hello, World')
 })
 it('另一個測試案例描述', () => {
 const wrapper = mount(component, {
 props: {
 content: 'Unit-test!'
 }
 })
 expect(wrapper.text()).toBe('Unit-test!')
 })
})

測試環境(test runner)：提供上方測試程式碼執行的環境。
測試情境(test suite)：如上方的 describe，用來包裹多個測試案例，以及描述測試情境⋯⋯等功能。
測試案例(test case)：如上方的 it，用來包裹該測試案例的實際情況，若有錯誤時需讓我們能夠輕易找到是哪個案例發生的⋯⋯等等功能。
斷言(Assertion)：如上方的 expect，主要是用來判斷受測物與預期結果是否一致的方法，甚至依據不同判斷方式內部也提供了多種判斷方式，如 .toBe 可用來判斷選取的目標與預期結果是否相等。

除此之外，在必要的情況下甚至會需要：

測試替身(test double)：用來模仿依賴工具或函式原先的功能狀況
解析或模擬元件容器
模擬瀏覽器中 DOM 的環境

而根據上述需求，就能夠列出一個需求表，來評估各個測試工具是否符合我們測試需要的部分：

測試工具列表可參考個框架中的測試建議指南，比方 Vue 的測試建議指南

需求	Vitest	Jest	Mocha	Chai.js	Sinon.js	Vue-test-utils	jsdom
測試環境(test runner)	✔(註1)	✔	✔
測試情境(test suite)	✔	✔	✔
測試案例(test case)	✔	✔	✔
斷言(Assertion)	✔	✔		✔
測試替身(test double)	✔	✔			✔
解析或模擬元件容器						✔
提供模擬 DOM 環境							✔

註1：Vitest 本身基於 Vite 環境，因此專案若非透過 Vite 所構建的話就無法使用。

現在透過這個表我們可以很清楚的看見，假設專案是基於 Vite 所建立的那麼我可以選擇下列這個組合：

Vitest + Vue-test-utils + jsdom

如果專案是基於 Vue-cli 所建立的，那麼就無法使用了 Vitest 作為測試運行的環境了，此時根據表中我們就可以替換為：

方案一：Jest + Vue-test-utils + jsdom
方案二：Mocha + Chai.js + Sinon.js + Vue-test-utils + jsdom

而在做工具替換時，需要注意到的是，不同的測試環境(test runner)可能會對於引入(import)檔案時發生解析上的問題，比方若用到 Vue 中的 SFC 類型檔案作為開發，那在 Jest 做為測試環境時我們就需要另外安裝 vue-jest 來做轉換 SFC 上的處理。

當然，上述的需求表只是一個簡單的範例，而隨著撰寫測試的經驗越多，後續慢慢就會瞭解到專案中會需要哪些測試工具來協助我們進行測試，甚至比較各種測試工具的優缺點從而選出最適合團隊的測試工具！

現在我們已經了解要如何挑選測試工具了，接下來要開始聊聊撰寫測試案例時應該要如何思考！

決定測試情境與測試案例

再來談談在選擇這些工具後，我們要如何來思考針對「單元測試」的部分，測試情境與測試案例要怎麼撰寫以及需要注意的地方。

測試情境(test suite)測試案例(test case)

提供測試環境的工具一般會給予測試情境與測試案例的相關 API，而測試情境與案例最主要的用意是用來幫助我們規劃與整理整個測試邏輯，並且在我們測試案例錯誤的時候同時提供相對應的資訊。

接下來我們以「貓咪作為元件」為故事主軸來談談單元測試的思路會是怎麼撰寫。

首先我們假設「貓咪」元件會提供下列功能：

發出呼嚕嚕叫聲
推倒眼前看到的所有東西

而以使用者角度上來看，我們會對「貓咪」做出這些事情：

摸摸
餵食
拿玩具逗

接著我們就可以以元件作為情境來定義出各種使用上的測試案例：

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


describe('貓咪', () => {
 it('摸摸，應該會發出「呼嚕嚕」聲', () => {
 // ...
 })
 it('餵食，應該會發出「呼嚕嚕」聲', () => {
 // ...
 })
 it('拿玩具逗，應該會發出「呼嚕嚕」聲', () => {
 // ...
 })
 it('什麼都不做，應該推倒眼前看到的所有東西', () => {
 // ...
 })
})

但真實的測試案例不會這麼簡單，總會有一些例外狀況，那麼測試案例應該要包含哪些要素比較好？

案例路徑(happy path、sad path、bad path)

在設定測試案例時，總會有百百種情況，但是我們不可能每個都寫出來，而根據測試案例的類型主要可以分為三種路徑：

Happy Path：在我們定義所謂「正常的使用狀況」下，針對「正確的內容」，我們預期應該要做出的反應。
Sad Path：在我們定義所謂「正常的使用狀況」下，針對「錯誤的內容」，我們預期應該要做出的反應。
Bad Path：在我們定義所謂「錯誤」的使用狀況下，我們預期應該要做出的反應。

同樣以貓被摸摸作為例子來看，假設對於貓來說能夠接受摸摸的情況只限於「頭與下巴」，而喜歡被摸的部分只有「下巴」，那麼測試案例路徑就可以這麼定義：

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


describe('貓咪', () => {
 // Happy Path
 it('摸摸下巴，應該會發出「呼嚕嚕」聲', () => {
 // ...
 })
 // Sad Path
 it('摸摸頭，應該沒反應', () => {
 // ...
 })
 // Bad Path
 it('摸摸肚子，應該拋出錯誤', () => {
 // ...
 })
})

路徑優先度

而以各個路徑優先度來說，我們應當盡可能的先完善 Happy Path 與 Sad Path 的各種案例，因為對於實際專案上來說，這些內容是我們預期元件或函式本身應提供的內容。

然而 Bad Path 通常是建立已知哪些情況會是「不正確的使用」，我們只能就已知的狀況來預防。然而，這一部分其實再怎麼縝密，都還是會有極其例外的事情發生：

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


describe('貓咪', () => {
 // ...
 // Bad Path
 it('摸摸肚子，應該拋出錯誤', () => {
 // ...
 })
 it('摸摸尾巴，應該拋出錯誤', () => {
 // ...
 })
 it('摸摸手，應該拋出錯誤', () => {
 // ...
 })
 it('摸摸腳，應該拋出錯誤', () => {
 // ...
 })
 // 舉不完
})

因此透過測試來作防禦所有不合理的行為是不治本的行為，我應該從受測物本身提供的操作或是產品規劃上來去考量相對治本的方式；比方在「貓咪」元件上透過程式設計的部分，規劃「摸摸」行為只開放「**頭」**與「下巴」的部位，從開發階段就阻止其他開發者誤用「摸摸」方法，到最後真的有其必要特別拋出時才針對這一部分寫 Bad Path 案例。

最後，再用一個實際一點的例子說明，假設今天有個登入的表單元件，那麼最簡單預期會有的案例就會是：

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


describe('登入元件', () => {
 // Happy Path
 it('輸入正確帳號密碼，應登入到ＯＯ頁面', () => {
 // ...
 })
 // Sad Path
 it('只輸入帳號，應該顯示請輸入密碼', () => {
 // ...
 })
 it('只輸入密碼，應該顯示請輸入帳號', () => {
 // ...
 })
 it('輸入錯誤帳號密碼，應該顯示登入資訊錯誤', () => {
 // ...
 })
})

以上就是測試情境與測試案例最基本需要瞭解的部分，接著我們來關注於測試案例中內部應該要如何來撰寫。

撰寫測試程式碼的前言

撰寫測試程式碼需保持的心境

談到撰寫測試，不得不提到 Robert Cecil Martin 有本經典的《無瑕的程式碼：敏捷軟體開發技巧守則》，作者在其中針對了程式碼的部分提了很多優良的建議，不論是撰寫程式碼中的命名、函式參數等等做探討，也在實際的案例中做一些討論與重構，最後回顧那些程式碼中的氣味、清理程式碼，一氣呵成。

而其中有一個章節最主要就是在講有關「單元測試」的部分，也就是系列文前言提到「被推坑」的部分，我把裡面的概念結合我的經驗來重新闡述一次：

若帶著單純學習的心態來看待測試程式碼，其實很容易把它當作一項輔助工具在處理，覺得沒有也沒什麼關係，甚至礙手礙腳的，甚至可能覺得還要特地花了不少心力來瞭解它，但這是一體兩面的。

若你把它當作產品中的一部分就會發現，雖然開發時會受到測試程式碼的「限制」，但同時他其實也是在做「守護」產品程式碼這件事情；甚至因為有了「可信賴的測試」，所以當我們在進行「重構」等等調整時也才能更有信心地去處理。

因此只要確保我們在適當的時機加入它，那麼它就能夠帶來可觀的後續效益，而既然他能夠替我們帶來效益，那我們對待測試程式碼的態度其實也應該要同理產品程式碼，可是除了讓測試程式碼如同產品程式碼一樣保持「整潔」與「可讀性」之外，我們還有什麼辦法呢？

對於這個問題 Martin 給了一個撰寫測試碼的優良準則，那就是 F.I.R.S.T 法則。

F.I.R.S.T 法則

F.I.R.S.T 法則顧名思義其實就是五個英文單字的縮寫，他們分別是：

Fast
Independent
Repeatable
Self-Validating
Timely

Fast(快)

簡單來說就是快，因為快才能讓我們快速重複大量地檢驗產品程式碼；這意味著我們在測試程式碼中有可能會遇到要 call API 的情況，那麼我們可以將其隔離並立刻回傳我們預定好的資料來減少等待回應的時間。

Independent(獨立)

如我們上一篇文章所提到的，每個測試案例應該要互相獨立，彼此不受干擾之外，甚至連執行順序上都不會影響到最終結果。

Repeatable(可重複)

可重複性主要提的就是不論在什麼設備狀況下，應該都要保持著一致的結果，這樣我們才能排除掉其他不必要的原因，專注在發生問題的程式碼上。

Self-Validating(能自我驗證)

測試的最終狀態應該要能夠顯示「通過與否」，而這一部分測試工具或框架都會幫我們處理好，甚至都還有提供額外的 diff 差異讓我們快速查看錯誤的地方。

Timely(即時)

測試程式碼要盡可能的與產品程式碼同進退，如果測試程式碼落後產品程式碼太多，測試程式碼會越來越難跟上產品程式碼的步調。

而根據對待測試程式碼心態的優良法則，在撰寫測試程式碼時就能更容易體會到他的魅力。

describe & it 與輔助 API

describe & it 基礎用法

稍早有提到的測試情境與測試案例在 Vitest 工具中主要便是透過 describe 與 it(或 test) 來撰寫，而他們的用意除了規劃測試的脈絡之外，最主要是用來包裝斷言結果的資訊：

1
2
3
4
5
6
7
8


import {describe, it} from 'vitest'

describe('測試情境的描述', () => {
 it('第一個測試案例的描述', () => {
 const add = (x, y) => x + y
 expect(add(1, 2)).toBe(2)
 })
})

假設在終端機執行上方的測試程式碼時，依據工具預設設定會在終端機顯示「錯誤的相關資訊」與「綜合結果」。

錯誤的相關資訊：

FAIL：發生斷言錯誤檔案路徑 + 情境描述 + 案例描述(視當下錯誤所屬的情境與案例)。
AssertionError：發生斷言錯誤的原因，與發生錯誤的段落。
Expected：預期結果。
Received：實際結果。

綜合結果：

Test Files：總共測試了幾隻測試檔案，並顯示成功、失敗與跳過的數量。
Tests：總共測了幾個測試案例，並顯示成功、失敗與跳過的數量。
Start：測試開始時間。
Duration：測試過程總共耗費時間。

而除了上述基本用法之外，在同一個測試情境中也能容納數個測試案例。

1
2
3
4
5
6
7
8


describe('測試情境的描述' , () => {
 it('第一個測試案例的描述', () => {
 // ...
 })
 it('第二個測試案例的描述', () => {
 // ...
 })
})

甚至測試情境較為複雜的情況，測試情境(describe)也允許巢狀的方式來建構測試：

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


describe('父層情境', () => {
 describe('基於父層情境的情境一', () => {
 it('測試案例', () => {
 // ...
 })
 })
 describe('基於父層情境的情境二', () => {
 it('測試案例', () => {
 // ...
 })
 it('出現提示寄件者姓名與電話將直接註冊成會員', () => {
 // ...
 })
 })
})

相反地，若在簡單的情境的之下，只有測試案例也是允許的方式之一：

1
2
3
4
5
6
7
8
9


it('測試案例', () => {
 // ...
})
it('測試案例', () => {
 // ...
})
it('測試案例', () => {
 // ...
})

describe & it 輔助 API

除了上述的基本用法之外，透過 describe 與 it 撰寫測試的過程中也能透過輔助的 API 來整理測試程式碼：

.only：測試情境、測試案例皆可使用
.skip：測試情境、測試案例皆可使用
.todo：測試情境、測試案例皆可使用
.fails：測試案例才能使用

only

若在測試情境用了此指令，則在同個測試檔案中只會執行帶有 .only 的測試情境，而其餘測試情境底下所有的測試案例將會被跳過(skipped)：

1
2
3


describe.only('測試情境 1', () => { /* */ })
describe('測試情境 2', () => { /* */ }) // skipped
describe('測試情境 3', () => { /* */ }) // skipped

若在測試案例中使用，則除了帶有 .only 之外的測試案例都將會被跳過：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


describe('測試情境 1', () => {
 it.only('測試案例', () => { /* */ })
 it('測試案例', () => { /* */ }) // skipped
})

describe('測試情境 2', () => {
 it.only('測試案例', () => { /* */ })
 it('測試案例', () => { /* */ }) // skipped
})

describe('測試情境 3', () => { /* */ }) // skipped

skip

測試情境或測試案例被標注時，將自動跳過該範疇內的測試案例：

1
2
3
4
5
6
7
8
9


describe.skip('測試情境 1', () => {
 it('測試案例', () => { /* */ }) // skipped
 it('測試案例', () => { /* */ }) // skipped
})

describe('測試情境 2', () => {
 it('測試案例', () => { /* */ })
 it.skip('測試案例', () => { /* */ }) // skipped
})

todo

測試情境或測試案例被標注時，同樣將自動跳過該範疇內的測試案例，但 todo 含義比較接近待加入測試的區塊，並且將來若產出報告時也會特別整理出還有哪些地方需要補上測試。

fails

最後一個介紹的是測試案例才能使用的輔助 API，還記得列測試案例時的 sad path 嗎？當測試案例應該要失敗的時候就可以透過 fails 顯性標註他們：

1
2
3
4


it.fails(`'1' + '1' should not to be '11'`, () => {
 const add = (x, y) => Number(x) + Number(y)
 expect(add('1', '1')).toBe('11')
})

當然你也可以單純藉由斷言中的 .not 達到同樣的效果：

1
2
3
4


it(`'1' + '1' should not to be '11'`, () => {
 const add = (x, y) => Number(x) + Number(y)
 expect(add('1', '1')).not.toBe('11')
})

以上便是測試程式碼中測試情境與測試案例的部分，有關於輔助 API 的部分有些內容不一定會使用的到，若想更加瞭解所有可用的部分可以參考 Vitest 測試情境與測試案例的文件囉。

準備(Setup)與清理(Teardown)

經過了基本的測試情境與測試案例語法，加上簡單的斷言語法 expect().toBe() 就能夠測試許多簡單的東西了，然而在測試過程中有時會遇到大量重複的「前置操作」或是每次測試後「需要清理測試中的環境」，這時我們可以透過 Vitest 提供的 Setup & Teardown API 來處理：

beforeEach：在每個測試案例執行前呼叫一次。
beforeAll：在所有測試案例執行前呼叫一次。
afterEach：在每個測試案例執行後呼叫一次。
afterAll：在所有測試案例執行後呼叫一次。

1
2
3
4


beforeEach(() => {
 // 針對測試案例重新初始化
 initTestEnv()
})

Setup & Teardown API 的範疇

Setup & Teardown API 「所有」的定義是根據當下的範疇(context)來決定，除了測試檔案本身之外，使用 describe 來定義測試情境也會形成一個 context，因此假如測試情境有巢狀的情況如下：

 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
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55


const history = []
describe('父層情境', () => {
 beforeAll(() => {
 history.push('beforeAll - 父層情境')
 })
 beforeEach(() => {
 history.push('beforeEach - 父層情境')
 })
 afterAll(() => {
 history.push('afterAll - 父層情境')
 })
 afterEach(() => {
 history.push('afterEach - 父層情境')
 })
 describe('子層情境 A', () => {
 beforeAll(() => {
 history.push('beforeAll - 子層情境 A')
 })
 beforeEach(() => {
 history.push('beforeEach - 子層情境 A')
 })
 afterAll(() => {
 history.push('afterAll - 子層情境 A')
 })
 afterEach(() => {
 history.push('afterEach - 子層情境 A')
 })
 it('案例 1', () => {
 history.push('子層情境 A 案例 1')
 })
 it('案例 2', () => {
 history.push('子層情境 A 案例 2')
 })
 })
 describe('子層情境 B', () => {
 beforeAll(() => {
 history.push('beforeAll - 子層情境 B')
 })
 beforeEach(() => {
 history.push('beforeEach - 子層情境 B')
 })
 afterAll(() => {
 history.push('afterAll - 子層情境 B')
 })
 afterEach(() => {
 history.push('afterEach - 子層情境 B')
 })
 it('案例 1', () => {
 history.push('子層情境 B 案例 1')
 })
 it('案例 2', () => {
 history.push('子層情境 B 案例 2')
 })
 })
})

此時將透過 console.log(history) 查看並歸納整理就能得到以下結果：

 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
33
34
35


--- 進入測試程式碼本身的 Context
--- 進入父層情境的 Context
beforeAll - 父層情境
--- 進入子層情境 A 的 Context
beforeAll - 子層情境 A
beforeEach - 父層情境
beforeEach - 子層情境 A
子層情境 A 案例 1 // 執行 情境 A 案例 1 的時間點
afterEach - 子層情境 A
afterEach - 父層情境
beforeEach - 父層情境
beforeEach - 子層情境 A
子層情境 A 案例 2 // 執行 情境 A 案例 2 的時間點
afterEach - 子層情境 A
afterEach - 父層情境
afterAll - 子層情境 A
--- 離開子層情境 A 的 Context

--- 進入子層情境 B 的 Context
beforeAll - 子層情境 B
beforeEach - 父層情境
beforeEach - 子層情境 B
子層情境 B 案例 1 // 執行 情境 B 案例 1 的時間點
afterEach - 子層情境 B
afterEach - 父層情境
beforeEach - 父層情境
beforeEach - 子層情境 B
子層情境 B 案例 2 // 執行 情境 B 案例 2 的時間點
afterEach - 子層情境 B
afterEach - 父層情境
afterAll - 子層情境 B
--- 離開子層情境 B 的 Context
afterAll - 父層情境
--- 離開父層情境的 Context
--- 離開測試程式碼本身的 Context

因此我們在使用這類 API 時要注意當下 context 所包含的範圍。

避免誤區：在 expect 後做清掃處理

除了上面的用法，有時候你可能會認為既然要清掃，那我何不在斷言後處理就好呢：

1
2
3
4
5
6
7


describe('', () => {
 it('', () => {
 expect().toBe()
 // 在這裡做清除
 resetTestingEnv()
 })
})

這麼做當你在測試案例都是通過的情況下都沒有問題，但是一但某個測試案例發生了錯誤，由於測試案例就會在斷言時拋出 AssertionError 後停止，因此很有可能因為一個測試案例壞了導致接下來所有測試都受到影響：

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


describe('', () => {
 it('', () => {
 expect().toBe() // AssertionError，這個測試案例就停在這了
 resetTestingEnv()
 })
 it('', () => {
 // 在沒有經過 `resetTestingEnv()` 下進行測試
 })
 it('', () => {
 // 在沒有經過 `resetTestingEnv()` 下進行測試
 })
 it('', () => {
 // 在沒有經過 `resetTestingEnv()` 下進行測試
 })
 it('', () => {
 // 在沒有經過 `resetTestingEnv()` 下進行測試
 })
})

因此較佳的作法還是使用 Setup & Teardown API 來處理會比較好：

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


describe('', () => {
 beforeEach('', () => {
 setupTestingEnv()
 })
 afterEach('', () => {
 resetTestingEnv()
 })
 it('', () => {})
 it('', () => {})
 it('', () => {})
 it('', () => {})
 it('', () => {})
})

避免過度使用 Setup & Teardown API

一名對於測試領域頗有研究的 Kent C. Dodds 在 twitter 上發表：

許多人一看了紛紛表示中槍，心想這不就是我在寫的東西嗎？因此發文一出不少人就好奇那麼到底為什麼上方的用法會比較好呢？且讓我們從抽象光譜介紹起。

抽象光譜(The Spectrum of Abstraction)

Kent C. Dodds 提出在抽象光譜中主要分成了三種概念：

ANA：Absolutely No Abstraction
AHA：Avoid Hasty Abstraction
DRY：Don’t Repeat Yourself

而後並將此概念應用在 Testing 身上並分別解說了三種抽象型態下的測試的優劣分析。

其中我們往往一開始學習可能因為對語法不熟稔，因此可能會寫出 ANA Testing 形式：

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


describe('', () => {
 it('' , () => {
 // 準備
 // 操作
 // 斷言
 })
 it('' , () => {
 // 準備：重複的準備類似的內容
 // 操作
 // 斷言
 })
 it('' , () => {
 // 準備：重複的準備類似的內容
 // 操作
 // 斷言
 })
})

而隨著測試經驗越來越熟稔之後，我們可能會想盡各種方法來「節省」撰寫測試上的時間，甚至參考 DRY 心法寫出這樣的測試：

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


describe('', () => {
 // 統一的事前準備
 const testEnv = new TestEnv()
 beforeEach(() => {
 testEnv.init()
 })
 it('' , () => {
 // 直接操作事先準備好的內容
 // 斷言
 })
 it('' , () => {
 // 直接操作事先準備好的內容
 // 斷言
 })
})

而這樣的下場將會在複雜的巢狀測試情境下越來越難以閱讀與調整：

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


describe('', () => {
 const testEnv = new TestEnv()
 beforeEach(() => {
 testEnv.init()
 })
 describe('', () => {
 const testEnv = new TestEnv()
 beforeEach(() => {
 testEnv.init()
 })
 // ...
 })
 describe('', () => {
 const testEnv = new TestEnv()
 beforeEach(() => {
 testEnv.init()
 })
 // ... 等等 這裡的初始準備有什麼 ？？？
 })
 // ...
})

而除了巢狀情境本身是個議題之外，Kent C. Dodds 認為我們應該兼容的方式去看待他，也就是說他不排斥我們去做抽象這件事情，但是首先要做的應該是先保持單純，直到我們看到足夠多共同的案例來分析能抽取出的部分，如果不夠多那甚至原先 inline 的測試案例版本也比過多抽象的版本要好得多。

避免過度巢狀情境

最後，共用的部分除非真的有必要透過 setup & teardown 實作處理，否則共用的部分大多也可以透過諸如工廠模式(factory pattern)的形式產生。

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


/* 擷取自我某個專案內的元件測試 */
const factory = (
 options = {
 createSpy: vi.fn,
 },
) => {
 const wrapper = mount(component, {
 global: {
 plugins: [createTestingPinia(options)],
 },
 })
 const store = useMainStore()
 return { wrapper, store }
}

所以往後若有使用到這類 API 時不仿先思考一下我們真的需要嗎，還是有更加優雅的方式能夠解決重複的問題呢？

斷言語法與 Matchers

斷言(Assertion)在程式設計領域中主要指的是「針對一個結果指出為真(true)或假(false)」的邏輯判斷式。

而在測試中斷言主要指的部分如先前提到的 3A 模式中的(Assert)步驟：

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


describe('', () => {
 it('', () => {
 // 準備：Arrange
 const wrapper = mount(component, {
 props: {
 content: 'Hello, Unit-test!'
 }
 })
 // 操作：Act
 wrapper.find('[data-test="button"]').click()
 // 斷言：Assert
 expect(wrapper.find('[data-test="content"]')).toBe('Hello, Unit-test!')
 })
})

其中斷言(Assert)階段中在語法的部分則會使用到所謂的「Matchers」，以上方程式碼為例的話就會是 expect() 後方的 toBe() 這個語法，而不同的「Matchers」能比對的東西也不太一樣，瞭解什麼時候該選什麼 Matchers 基本上寫斷言的時候就能信手捻來。

斷言語法

依據不同工具或框架所提供的斷言語法(Assertion)，對於 Matchers 來說就會有不同的寫法，所以首先我們要先來簡單認識一下不同工具之間的斷言語法風格上的差異，挑選能接受的斷言風格後再來看該風格的 Matcher 用法，而風格的部分以下將依序介紹：

Chai 斷言庫
Jest 框架中的斷言語法
Vitest 中所能用的部分

Chai Assertion

Chai.js 本身是一個專注在提供斷言語法的工具庫，它提供了三種寫法：

Assert(TDD style)

1
2
3
4
5


it('Chai/Assert', () => {
 const x = 'Orange tabby cat'
 const y = 'fat'
 assert(x !== y, 'Orange tabby cat is not fat')
})

Expect(BDD style)

1
2
3


it('Chai/Expect', () => {
 expect([1, 2]).to.be.an('array').that.does.not.include(3)
})

Should(BDD style)：透過擴充物件 prototype 給予 should 屬性的方式使我們可以直接鏈式加入 Matchers 在定義好的變數後。

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


// 選擇一：在斷言前需要呼叫 `chai.should` 方法，
import chai from 'chai'
chai.should()
// 選擇二：直接引入下方
import 'chai/register-should'

// 底下的測試案例就能直接鏈式加上 Matchers
it('Chai/Assert', () => {
 const foo = 'bar'
 const beverages = { tea: ['chai', 'matcha', 'oolong'] }

 foo.should.be.a('string')
 foo.should.equal('bar')
 foo.should.have.lengthOf(3)
 beverages.should.have.property('tea').with.lengthOf(3)
})

Jest Assertion

以 Jest 測試框架中所提供的斷言方法則只有：

Expect(BDD style)：

1
2
3


it('expect/ BDD style', () => {
 expect(1).toBe(1)
})

需特別注意的是 Jest 中的 expect 與 Chai 的 expect 所提供的 Matchers 是不一樣的。

Vitest

以 Vitest 測試工具來說，斷言(Assertion)語法的部分他內建了 Chai 斷言庫與兼容了 Jest 中的斷言語法，因此主要就是在以上介紹的四種寫法中選擇一種使用！

而接下來主要著重介紹 Jest Assertion 中的 expect 語法的 Matchers 要如何使用！

Vitest(Jest expect Matchers)

要學習這類 Matchers 除了把 API doc 翻一輪之外，最快的方式之一就是針對不同的測試結果目標類型去歸納，而依照經驗常見種類有：

常用：toBe, not
純值比對(Primitive)類型：String, Number, Boolean…, etc.
陣列比對與檢查
物件比對與檢查
監聽函式
快照
Error

由於 Matchers 繁多，所以從常用跟概念容易搞混的幾個開始先介紹起：

常用

toBe：對資料類型為純值(Primitive Value)來說就是比對值相等

1
2


expect(1).toBe(1) // passed
expect('1').toBe(1) // failed

對非純值(Non-Primitive Value)來說就是比記憶體位置(reference)是否相等

1
2
3
4
5
6
7
8
9


const obj = {}
const obj2 = obj
expect(obj).toBe(obj2) // passed
expect({}).toBe({}) // failed

// `not`：用於反轉斷言的邏輯
expect(1).toBe(1) // passed
expect(1).not.toBe(1) // failed
expect(1).not.toBe(2) // passed

純值資料類型比對

toBeCloseTo：處理浮點數運算時

1
2


expect(0.1 + 0.2).toBe(0.3) // failed 符點溢出，結果應該會為 0.30000000000000004
expect(0.1 + 0.2).toBeCloseTo(0.3) // passed

toBeGreaterThan、toBeGreaterThanOrEqual、toBeLessThan、toBeLessThanOrEqual

1
2
3
4


expect(5).toBeGreaterThan(1) // passed
expect(5).toBeGreaterThanOrEqual(5) // passed
expect(6).toBeLessThan(7) // passed
expect(6).toBeLessThanOrEqual(6) // passed

toBeDefined、toBeUndefined

1
2
3
4


var a = ''
var b
expect(a).toBeDefined() // passed
expect(b).toBeUndefined() // passed

toBeTruthy、toBeFalsy

1
2


expect(1).toBeTruthy() // passed
expect(0).toBeFalsy() // passed

toBeNull、toBeNaN

1

expect(null).toBeNull() // passed

toMatch：字串或正則比對

1

expect('0912345678').toMatch(/^09[0-9]{8}$/) // passed

陣列比對與檢查

toContain：陣列是否含有目標值

1
2


expect(['1', '2']).toContain('1') // passed
expect(['1', '2']).toContain('4') // failed

toContainEqual：陣列是否含有該值(類型為純值時檢驗是否相等，類型為物件時檢驗結構是否全等)

1
2
3
4
5
6


// passed
expect(['1', '2']).toContainEqual('1') // passed
expect([{ val: '1' }, { val: '2' }]).toContainEqual({ val: '1' })

// failed
expect([{ val: '1', something: 'other' }]).toContainEqual({ val: '1' })

toHaveLength：確認其屬性的長度是否相等

1
2
3


expect('12').toHaveLength(2) // passed
expect([1, 2]).toHaveLength(2) // passed
expect({ length: 2 }).toHaveLength(2) // passed

物件比對與檢查

toEqual：比對物件結構是否相同，而非比對參照來源(reference)，而結構中若值為 undefined 會忽略

1
2
3


const A = { num: 100 }
const B = { num: 100, secret: undefined }
expect(A).toEqual(B) // passed

toStrictEqual：與 toEqual 類似，但 undefined 不會被忽略

1
2
3
4
5


const A = { num: 100 }
const B = { num: 100 }
const C = { num: 100, secret: undefined }
expect(A).toStrictEqual(B) // passed
expect(A).toStrictEqual(C) // failed

甚至 Class 所創造的物件與物件實字(Object Literals)相比也視為不同。

1
2
3
4
5
6
7


class MockClass {
 constructor(num) {
 this.num = num
 }
}
expect({num: 1}).toStrictEqual({num: 1}) // passed
expect(new MockClass(1)).toStrictEqual({num: 1}) // failed

toHaveProperty：檢查物件含有屬性與其屬性值

1
2
3
4
5


const obj = { num: 100 }

expect(obj).toHaveProperty('num') // passed
expect(obj).toHaveProperty('num', 100) // passed
expect(obj).toHaveProperty('num', 200) // failed

toMatchObject：檢查物件的子層

1
2
3
4
5
6


const obj = { nested: { num: 200 }, num: 100 }

expect(obj).toMatchObject({ num: 100 }) // passed
expect(obj).toMatchObject({ num: 200 }) // failed
expect(obj).toMatchObject({ nested: { num: 100 } }) // failed
expect(obj).toMatchObject({ nested: { num: 200 } }) // passed

繼續講解下列幾個比較特別的 Matcher

監聽函式

在測試的過程中，有時候我們不僅只是斷言受測物(SUT, System Under Test)的狀態，有時候可能會對受測目標的「依賴物」(DOC, Depended-on Component)狀態有興趣，而這時我們就無法單純以 Matchers 來斷言，因為我們需要監聽依賴物前後的變化。

而在程式測試領域中，測試替身(test double)主要就是負責處理這一類非受測物本身所做的事情，並且在需要時還能幫我們紀錄必要的資訊。

假若我們今天測試案例受測物本身會去呼叫到的依賴目標是個「函式」時，這時我們可以透過 Vitest 所提供的 vi.fn() 來模仿(spy)函式。

vi.fn() 本身會回傳一個實體(CallableMockInstance)，在這個實體中會記錄著有關測試函式時會需要的資料與方法：

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


console.log(vi.fn())

/*
 called: false,
 callCount: 0,
 results: [],
 calls: [],
 impl: [Function (anonymous)],
 reset: [Function: i],
 nextError: [Function (anonymous)],
 nextResult: [Function (anonymous)],
 restore: [Function: w],
 ...
*/

因此將受測的目標函式放入 vi.fn 中，後續只要測試過程中如果測試目標去調用了已被 Spy 過的函式時，CallableMockInstance 就會幫我們紀錄相關的資訊，接著我們就可以使用斷言語法相關的 Matcher 去比對我們預期的結果，比方說：

toHaveBeenCalled：斷言函式有被呼叫過

1
2
3
4
5


const sayHi = (something) => something
const spyOnSayHi = vi.fn(sayHi)

spyOnSayHi()
expect(spyOnSayHi).toHaveBeenCalled()

toHaveBeenCalledTimes：斷言函式被呼叫過幾次

1
2
3
4
5
6
7
8


const sayHi = (something) => something
const spyOnSayHi = vi.fn(sayHi)

spyOnSayHi()
spyOnSayHi()
spyOnSayHi()

expect(spyOnSayHi).toHaveBeenCalledTimes(3)

toHaveBeenCalledWith：斷言函式被呼叫時所帶的參數

1
2
3
4
5
6


const sayHi = (something) => something
const spyOnSayHi = vi.fn(sayHi)

spyOnSayHi('Hello, Unit-Test!')

expect(spyOnSayHi).toHaveBeenCalledWith('Hello, Unit-Test!')

toHaveReturned：斷言函式呼叫後應該至少要返回值一次

1
2
3
4
5
6


const sayHi = (something) => something + ' Hello, Spy!'
const spyOnSayHi = vi.fn((val) => sayHi(val))

spyOnSayHi('Hello, Unit-Test!')

expect(spyOnSayHi).toHaveReturned()

toHaveReturnedTimes：斷言函式經過操作後應該要返回值幾次

1
2
3
4
5
6
7


const sayHi = (something) => something
const spyOnSayHi = vi.fn((val) => sayHi(val))

spyOnSayHi('Nice to meet you!')
spyOnSayHi('See you again!')

expect(spyOnSayHi).toHaveReturnedTimes(2)

toHaveLastReturnedWith：斷言函式經過操作後最後應該要返回的值

1
2
3
4
5
6
7


const sayHi = (something) => something
const spyOnSayHi = vi.fn((val) => sayHi(val))

spyOnSayHi('Nice to meet you!')
spyOnSayHi('See you again!')

expect(spyOnSayHi).toHaveLastReturnedWith('See you again!')

toHaveNthReturnedWith：斷言函式經過操作後第 N 次應該要返回的值

1
2
3
4
5
6
7


const sayHi = (something) => something
const spyOnSayHi = vi.fn((val) => sayHi(val))

spyOnSayHi('Nice to meet you!')
spyOnSayHi('See you again!')

expect(spyOnSayHi).toHaveNthReturnedWith(1, 'Nice to meet you!')

toHaveReturnedWith：斷言函式呼叫後返回的值

1
2
3
4
5
6


const sayHi = (something) => something + ' Hello, Spy!'
const spyOnSayHi = vi.fn((val) => sayHi(val))

spyOnSayHi('Hello, Unit-Test!')

expect(spyOnSayHi).toHaveReturnedWith('Hello, Unit-Test! Hello, Spy!')

而測試替身(test double)除了像是 vi.fn() 這類間諜類型(Spy)之外，還有許多不同的測試替身，它們在測試中都有各自的用途來協助我們更好的測試。

快照測試(Snapshot Testing)與快照 matchers

Jest Snapshot

在 Jest 的 Snapshot Testing 說明文件的定義中主要指的是用來防止 UI 出現尚未預期的變化：

1
2
3


<template>
 <a data-test="link" href="http://ithelp.ithome.com.tw"> Ithelp </a>
</template>

1
2
3
4
5


import { mount } from '@vue/test-utils'
it('渲染連結', () => {
 const wrapper = mount(component)
 expect(wrapper.find([data-test="link"])).toMatchSnapshot();
});

然而這邊的變化，並非你所想像的把視覺畫面給照相下來比對像素或比例的那種視覺回歸測試(Visual Regression Testing)，而是藉由將目標元件透過渲染(Render)元件產生了一個 DOM 結構的文字，並在測試程式檔路徑底下的 __snapshots__ 資料夾生成一個 .snap 檔案來做紀錄：

1
2
3
4
5
6
7
8


exports[`渲染連結`] = `
<a
 data-test="link"
 href="http://ithelp.ithome.com.tw"
>
 Ithelp
</a>
`;

截至 Jest Snapshot 頁面中的程式碼

在第二次執行測試的時候，就會再次做一次同樣的流程，而這次所產生的結果會與先前的 .snap 紀錄做比對。

假設比對上有落差就會拋出錯誤：

1
2
3
4
5
6
7
8


- Snapshot - 1
+ Received + 1

<a
- href="http://ithelp.ithome.com.tw"
+ href="https://ithelp.ithome.com.tw"
> Ithelp
</a>

藉由這個比對機制從而實現「防止 UI 出現尚未預期的變化」的功能。

Vitest Snapshot

而前面有提到 Vitest 本身兼容了 Jest 的斷言(assertion)語法，所以快照(Snapshot)的 matcher 自然也是不能放過。

在 Vitest 中主要兼容的 matcher 部分有：

toMatchSnapshot
toMatchInlineSnapshot

基本上概念與 Jest Snapshot 相似，都是在做結構快照這件事情，然而 Vitest 文件部分則是沒有特地強調 UI 的部分，而是關注在值(value)的比對。

因此我們單純放入一個陣列物件

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


it('cat snapshot', () => {
 const target = [
 {
 name: 'Orange',
 age: 4,
 },
 {
 name: 'Blank',
 age: 6,
 },
 ]
 expect(target).toMatchSnapshot()
})

.snap 的結果：

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


exports[`component > cat snapshot 1`] = `
 [
 {
 "age": 4,
 "name": "Orange",
 },
 {
 "age": 6,
 "name": "Blank",
 },
 ]
`;

甚至也可以引入 JSON 檔案來做快照：

1
2
3
4
5


import Area from './area.json'

it('static json snapshot', () => {
 expect(Area).toMatchSnapshot()
})

當然元件快照也是能做的：

1
2
3
4
5
6
7


import { mount } from '@vue/test-utils'

it('snapshot', () => {
 const wrapper = mount(component)
 const target = wrapper.find('[data-test="content"]')
 expect(target).toMatchSnapshot()
})

而以上快照部分如果你覺得要生成一個檔案來管理有點囉唆，那麼你可以透過 toMatchInlineSnapshot 來處理這類的需求，其差別在於生成的位置會是在 toMatchInlineSnapshot() 函式本身裡面：

 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


it('cat snapshot', () => {
 const target = [
 {
 name: 'Orange',
 age: 4,
 },
 {
 name: 'Blank',
 age: 6,
 },
 ]

 // 原先 toMatchInlineSnapshot 內沒有任何東西
 // 在執行測試後就會將快照內容自動生成在 toMatchInlineSnapshot 裡
 expect(target).toMatchInlineSnapshot(`
 [
 {
 "age": 4,
 "name": "Orange",
 },
 {
 "age": 6,
 "name": "Blank",
 },
 ]
 `)
})

最後，如果遇到變更的部分是我們所預期的時候，此時就需要更新快照的部分，可以在執行測試的 watch 模式時按下 u 鍵，就將新的快照保存起來，或是透過新增 npm scripts 指令來執行命令：

1
2
3
4
5


{
 "scripts": {
 "test:update": "vitest -u",
 },
}

Error

最後介紹到的則是錯誤類型的 Matcher：

toThrowError
toThrowErrorMatchingSnapshot
toThrowErrorMatchingInlineSnapshot

先前我們有提到測試案例預想的三個路徑(Happy path、sad Path、Bad Path)，Bad Path 從產品角度上來說 End-User 使用上的錯誤，應該考慮從產品使用角度上去思考要怎麼協助他們去使用，所以不應該為了拋出錯誤而拋出。

但假設今天拋出錯誤的情境是較為合理的部分，比方是針對開發人員在開發時期誤用導致的錯誤⋯⋯等等情況，這時我們就可以透過這一類 Matcher 來處理。

而使用上要比較小心的是，受測目標若會拋出錯誤則要透過 wrap function 的形式來處理，否則拋出的錯誤會造成測試案例的斷言錯誤：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


it('', ()=>{
 const food = (name) => {
 // ...
 if(name === '小黃瓜'){
 throw new Error('我不吃小黃瓜')
 }
 }
 expect(food('小黃瓜')).toThrowError('我不吃小黃瓜') // 若這樣寫的話裡頭的 Error 會導致測試案例失敗
 expect(() => food('小黃瓜')).toThrowError('我不吃小黃瓜') // 需要透過這種方式才能正確斷言
})

元件測試

Vue Test Utils 與元件測試

接著，若我們想進一步在專案中測試 Vue 元件的話，我們除了基於前面的概念與語法之外，還得依靠能夠幫助能夠解析 Vue 元件並與其模擬互動的工具：

Vue Test Utils
Cypress
Vue Testing Library

而本篇將著重在介紹要怎麼透過 Vue Test Utils 來進行與 Vue 元件有關的「元件測試」，因此本文要來介紹一下 Vue Test Utils 與元件測試是在做什麼，又這又跟單元測試有什麼關係呢。

Vue-Test-Utils

首先區辨一下他與我們目前用到的測試工具的各自用處，才能更瞭解接下學的內容是由哪個工具負責的，將來有必要查閱資料時就能更清楚的區別他們。

Vue Test Utils 主要是作為提供測試 Vue 元件的相關工具集，讓我們能更輕易的模擬操作元件來進行測試，但本身並沒有運行測試環境(test runner)的功能，因此我們會需要藉由 Vitest 來作為測試環境以及相關的測試情境案例與斷言 Matcher；除此之外我們還需要用來在 Node 環境中模擬瀏覽器環境的 jsdom 來協助處理有關 DOM 上的操作，如此一來才能順利地使用 Vue Test Utils。

而版本的部分要特別注意到，由於 Vue Test Utils 為了相容 Vue 不同版本之間的 API 因此我們要安裝對應的版本未來才不會出錯：

Vue 2：安裝 Vue Test Utils 1
Vue 3：安裝 Vue Test Utils 2

確認版本沒問題後，模擬元件的部分交給 Vue Test Utils 基本上就沒問題了，但關於「元件測試」目標主要是要測試什麼東西呢？

元件測試的目標

測試本質主要是在預期結果與實際是否相等，而在元件測試中作為受測物的元件，其本身主要是負責 UI 上的一切內容，因此我們測試目標在著重於它的「畫面」與「行為」上是否如我們所預期。

因此，在測試案例的操作過程中(也就是 3A 中的 Action 階段)，我們主要是藉由操作對元件介面中的：

data
props
slot
provide
directive
Event(瀏覽器中的互動行為)
API response(模擬回應)

來判斷下列是否如我們所預期：

DOM 渲染結果
emit 行為

好的元件測試

當然，做到上面的事項基本上已經可以算是個元件測試了，若我們想讓元件測試寫得更好，除了先前在單元測試提過的一些概念之外，還有一些值得注意的事項：

首先，在撰寫元件測試時的角度，我們並沒有要當個全能全知的神，而是作為「使用者的角度」關注元件介面上來預期結果，所以在測試的過程中我們要「避免又寫了一次實作」。

另外，如果內部邏輯過於複雜時，我們則應該先抽取(extract)其邏輯，透過 composables 的寫法來引入，如此一來我們就能「專注於在元件本身的行為上」，另外也能「針對 composable 的邏輯單獨做測試」。

最後，若元件中有使用到 API 的部分，同樣的我們應該把它當作成是他提供給元件去使用，而元件主要是「接收回應」後就能自行處理後續的內容了，所以在測試上我們應該專注在 API 提供了什麼給元件，透過模擬資料的部分來達成先前提過的 FIRST 原則中的 Fast，最後斷言元件最終的行為是否如預期即可。

現在我們知道 Vue Test Utils 在做什麼了，也知道「元件測試」在做什麼了，但這跟單元測試又有什麼關係呢？

元件測試與單元測試的關係

在官方文件中測試章節有提到，元件測試(component testing)在顆粒度上其實是高於單元測試(unit testing)的，甚至可以被視為是整合測試(integration testing)的一種形式。

而坊間有不少文章習慣以單元測試來統稱這一類測試，最主要原因是單元測試的定義為「軟體設計」中最小單位的程式或行為，在 Vue 專案中，若以 Vue SFC 類型檔案(.vue)來看其實測試元件也算是最小單位沒錯。

所以從意義上來劃分單元測試與元件測試，某方面來說很容易出現歧異(甚至單元測試本身就已經有分為獨立型與社交型寫法了)。

然而為了接下來在本系列文中方便區分指的測試對象是哪部分，我將名稱含義分為：

元件測試：針對 Vue 元件所進行的測試
單元測試：針對元件引入函式、類別等 utils、helper 與 composable 的測試。
工具本身：Pinia 測試、Vue Router 測試。

元件測試：容器(Wrapper)

mount

當我們需要在測試案例中引入元件時，我們可以透過 Vue Test Utils 提供的方法 mount 來包裹 Vue 元件。而 mount 所返回的內容除了 Vue 實體之外，還包含了一些方法（Wrapper methods）可以讓我們操作元件：

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


import component from '@/component/BaseButton.vue'

it('should emit clicked event after clicking button', () => {
 // Arrange
 const wrapper = mount(component)

 // Act
 wrapper.trigger('click')

 // Assert
 export(wrapper.emitted()).toHaveProperty('clicked')
})

假若我們希望在渲染元件的時候同時帶著預設參數與狀態時（如 props、slots…等），就能夠透過 mount 方法的第二個參數傳入設定：

1
2
3
4
5
6
7


const options = {
 props: {
 content: 'Hello, Props!'
 }
}
const wrapper = mounted(component, options)
expect(wrapper.text()).toBe('Hello, Props!')

而關於方法（Wrapper methods）與選項（Wrapper options）的部分，會根據元件使用 Options API / Composition API / setup script 語法糖而有不同的用法與限制，因此使用方法與差異的部分將在後續測試各種元件時陸續會提到。

shallowMount

在正常的專案開發下，元件時常會嵌入了另一個元件：

RootComponent.vue

1

<ParentComponent></ParentComponent>

ParentComponent.vue

1
2
3


<ChildComponent></ChildComponent>
<ChildComponent></ChildComponent>
<ChildComponent></ChildComponent>

ChildComponent.vue

1

<p>baby</p>

RootComponent 的元件測試：

1
2
3
4
5
6
7
8
9


import component from './RootComponent.vue'
it('should render corrent content', async () => {
 const wrapper = mount(component)
 expect(wrapper.html()).toBe(`
 <p>baby</p>
 <p>baby</p>
 <p>baby</p>
 `)
})

但如此一來若我們在測試 RootComponent 元件的時候，就有可能因為底下的 ChildComponent 元件更改了內容導致 RootComponent 測試案例也跟著失敗：

1

<p>baby</p>

若「有意」想要避免這種情況發生，此時就可以將 mount 替換掉，改使用 shallowMount 來作為容器使用：

1
2
3
4
5


import component from './RootComponent.vue'
it('should render corrent content', async () => {
 const wrapper = shallowMount(component)
 // ...
})

shallowMount 與 mount 在使用上幾乎大同小異，而唯一有差別在於他會將原先內部有用到元件的部分以替換為一個模擬元件（stub component），並且命名改以烤肉串命名法（Kebab case）並且在最末端加上 -stub 供辨識：

RootComponent.vue

1

<ParentComponent></ParentComponent>

經 shallowMount 渲染結果變成：

RootComponent.vue

1

<parent-component-stub></parent-component-stub>

如此一來在撰寫測試案例時，就可以關注在當下「父層元件」與「子層元件」的之間的內容，而不管「子層元件」底下所發生的事情：

1
2
3
4
5
6


import component from './RootComponent.vue'
it('should render corrent content', async () => {
 const wrapper = shallowMount(component)
 // ...
 expect(wrapper.html()).toBe(`<parent-component-stub></parent-component-stub>`)
})

容器的方法（Wrapper methods） - 選擇器

在進行測試時，前面章節有提到我們會使用 mount 或 shallowMount 來包裹元件，從而得到一個 VueWrapper，而在這個 VueWrapper 裡頭有許多實用的容器方法（Wrapper methods），雖然官方文件中並沒有特意分類，但大意上可分為幾種方法：

查詢、選擇指定的元素、元件等選擇器
取得目標屬性或內容（class, attribute）
觸發 DOM 事件（如滑鼠點擊、鍵盤輸入與按鍵⋯⋯等）
取得 emit 事件、設置 data 或 prop、甚至觸發元件 unmmount 等 Vue API 相關的方法

這邊著重在於介紹選擇器的方法使用與測試應用，最後補上相關的討論：

元素、元件選擇器
判斷目標是否存在：exists 與 isVisible
使用 data-* attribute

選擇器

在進行元件測試（component testing）的過程中，有時我們可能只想關注在某個特定 DOM 或元件的相關資訊時，這時我們就可以透過容器中的選擇器方法來尋找，而選擇器根據選取對象的不同，主要分為：

元素（element）選擇器
元件（component）選擇器

元素選擇器

元素選擇器語法基本上有兩種寫法，一種是基於元素的 refs，另一種則是 querySelector：

1
2
3
4
5
6


<template>
 <p ref="dogcat">???</p>
 <p id="dog">科基</p>
 <p class="cat">橘貓</p>
 <p class="cat">黑黑</p>
</template>

1
2
3
4
5
6


/* ref */
wrapper.find({ ref: 'span' })

/* querySelector */
wrapper.find('#dog')
wrapper.find('.cat')

而容器方法有關選取元素的選擇器一共分為三種：

find
findAll
get

這三種選擇器在選取到目標後主要都是返回 DOMWrapper，此時我們就可以在串連其他容器方法（Wrapper methods）如 classes 或 text 等等來取得屬性或內容資訊，只是返回的結果內容會有些差異。

比方 find、findAll 的部分主要差別在於 findAll 返回的內容會被放置於陣列當中：

1
2
3
4
5


<template>
 <p id="dog">科基</p>
 <p class="cat">橘貓</p>
 <p class="cat">黑黑</p>
</template>

而我們可以透過像這樣的方式取得陣列內的資訊：

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


it('should be display correct content', () => {
 const wrapper = mount(component)
 const target= wrapper.find('#dog') // <DOMWrapper>
 expect(target.text()).toBe('科基')
})
it('should be display correct content', () => {
 const wrapper = mount(component)
 const target= wrapper.findAll('.cat') // <DOMWrapper>[]

 expect(target[0].text()).toBe('橘貓')
 expect(target[1].text()).toBe('黑黑')
})

注意：透過 findAll 斷言時是「有序」的，很容易受到順序改變而導致測試案例失敗，除非撰寫測試案例目標之一就是要確保順序不會調動，否則改用 find 斷言會比較不容易受影響。

而 find 與 get 的差別在於 find 找不到目標時返回的是 {} 後續若仍繼續操作、斷言時才會由拋出錯誤（由 ErrorWrapper 提供）；然而 get 一開始若找不到目標時就直接拋出錯誤（throw Error）了。

根據 ErrorWrapper 原始碼，可以看見他主要是針對容器方法中的 exists() 會返回 false。

因此在針對找不到元素的測試案例合法的寫法可以這麼做：

1
2


expect(() => wrapper.get('.something-that-does-not-exist')).toThrowError()
expect(wrapper.find('.something-that-does-not-exist').exists()).toBeFalsy()

find 判斷元素陷阱

魔鬼藏在細節裡，或許你可能會想說為什麼不直接用 find 還要再另外透過 exists 判斷呢，讓我們看看一個案例：

1

<p>無關緊要的東西</p>

如果這時你這麼寫了：

1
2


expect(wrapper.find('.something-that-does-not-exist')).toBeTruthy()
// 通過 ！？

原因在於 find 在找不到的情況下目標的情況所返回的值會是 ErrorWrapper 物件，所以透過 toBeTruthy 斷言就會通過。

而為了避免這種情況發生，官方文件其實只有輕描淡述地說道：

As a rule of thumb, always use get except when you are asserting something doesn’t exist. In that case use find.
但上方經驗考量在哪，只有在追了他們相關的 issue 才會逐漸明白考量的根據，而關於這部分，甚至開發團隊未來可能也會考慮將 find 方法給拔掉，剩下 exists 本身，但礙於這會是個 breaking change 的做法，所以在 vue-test-utils 跳大版本號之前應該都會暫時維持原樣。

元件（component）選擇器

findComponent
findAllfindComponents (注意有個 s）
getComponent

原則上使用方式與元素選擇器差不多，只是選取語法上除了 refs 與 querySelector 語法之外，還多了：

Component name： findComponent({name: '元件名稱'})
將 import SFC 直接放入方法中： findComponent(Component)

但由於使用 querySelector 上也有一些小陷阱，所以個人建議以 SFC 方式引入或是乾脆透過 shallowMount 將子層元件 stub 掉也是一種方式。

判斷目標存在

經由剛剛陷阱的部分大家應該都很清楚 exists() 的存在了，而判斷選取目標其實他還有個好朋友就是 isVisible()，但他們判斷存在的定義上有一些差別：

exists()：主要判斷的是該目標存不存在 DOM 上：

1

<p>Hello</p>

1
2
3
4
5


it(exist, () => {
 const wrapper = mount(Component)
 expect(wrapper.find('p').exists()).toBe(true)
 expect(wrapper.find('span').exists()).toBe(false)
})

isVisable()：主要判斷的是該目標存在 DOM 上之外，視覺上有無顯示在畫面中：

1
2
3
4
5


<template>
 <p v-if="false" class="dog">科基</p>
 <p v-show="true" class="orange-cat">橘貓</p>
 <p v-show="false" class="black-cat">黑黑</p>
</template>

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


it('v-if false', () => {
 const wrapper = mount(component)
 expect(wrapper.find('.dog').isVisible()).toBeFalsy() // Error： 直接噴錯
})
it('v-show true', () => {
 const wrapper = mount(component)
 expect(wrapper.find('.orange-cat').isVisible()).toBeTruthy() // 測試通過
})
it('v-show false', () => {
 const wrapper = mount(component)
 expect(wrapper.find('.black-cat').isVisible()).toBeFalsy() // 測試通過
})

關於 isVibile 更為詳細的判斷如下：

CSS style 中含有 display: none => false
CSS style 中含有 visibility: hidden => false
CSS style 中含有 opacity :0 => false
元素中 hidden 屬性為 true => false

綜合結論上方陷阱與判斷方法：

若要判斷元素是否存在或 v-if：使用 get 方法是最保險的，真的要用 find 則一定要搭配 exists
若要判斷 v-show：使用 find().isVisible()

使用 data-* attribute

在撰寫測試情境時，若依照上面的 querySelector 選了元素、id 或 class 時，初期一定會很開心，因為不會遇到太多困難，但往後在開發的過程執行測試時就很容易有機會遇到各種問題。

原先：

1
2
3


<template>
 <p class="content">content</p>
</template>

改成：

1
2
3


<template>
 <p class="content" data-test="content">content</p>
</template>

使用 data-* 作為選擇目標好處最主要在於顯著標記測試內容，而這影響到的範圍有：

開發期，過程不用擔心會影響到測試，如上方所見，我只要變更 data-test 以外的內容，預期應該不會影響到測試選擇的目標，使測試案例錯誤能更專注在斷言的目標上，而非選擇目標被替換導致的錯誤。
重構（refactor）過程，能清楚比較範圍，若將來調整結構，只要將屬性轉移到對應的位置即可。
生產期，能夠針對特定的屬性移除，避免留下各種測試痕跡，對於像是輔助閱讀裝置等技術來說就不會被影響到。

在生產環境刪除 data-* attribute

若想在 vitest 中移除 data-* 也非常的簡單，我們只需要在 vite.config.js 設定中，針對 Vue 底下的編譯選項做一些調整即可（底下示範的版本為移除 data-test，若使用其他命名請自行調整囉）：

vite.config.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


const isProd = process.env.NODE_ENV === 'production'
const removeDataTestAttrs = (node) => {
 const NodeTypes = Object.freeze({
 ELEMENT: 1,
 ATTRIBUTE: 6,
 })
 if (node.type === NodeTypes['ELEMENT']) {
 node.props = node.props.filter((prop) => (prop.type === NodeTypes['ATTRIBUTE'] ? prop.name !== 'data-test' : true)) // 請自行替換命名 data-test
 }
}

export default defineConfig(() => {
 return {
 plugins: [
 vue({
 template: {
 compilerOptions: {
 nodeTransforms: isProd ? [removeDataTestAttrs] : [],
 },
 },
 }),
 ]
 }
})

容器的方法(Wrapper methods) - 取得目標資訊

判斷屬性

attributes

當你想要確認 <a> 中的 href 是否帶有指定的連結或是檢查 <img> 上的屬性時，這時就可以透過 attributes 取得屬性。

而 attributes 用法主要有兩種，直接使用時會獲取目標：

1

<a data-test="link" href="https://ithelp.ithome.com.tw/" target="_blank">ithelp</a>

1

wrapper.find('[data-test="link"]').attributes() // { href: 'https://ithelp.ithome.com.tw/', 'target': '_blank' }

當想要直接取得特定屬性值時也可以直接將屬性名稱帶入參數中：

1

wrapper.find('a').attributes('target') // '_blank'

classes

同樣的，若想要尋找 class 屬性的話可以透過 classes 語法取得資訊。你可能會直覺地想到 class 也是屬性的一種那應該用 attributes('class') 查詢，然而這兩者的差別最主要在於產出的結果會有所不同。

1
2
3


<section data-test="wrap" class="container w-full h-full">
 <p>Title</p>
</section>

若使用 attributes('class') 查詢結果將會是字串形式的資料，後續要處理比對上的問題會稍微麻煩一點：

1

wrapper.find('[data-test="wrap"]').attributes('class') // "container w-full h-full"

若是使用 classes 語法查詢的話將得到一個陣列的結果：

1

wrapper.find('[data-test="wrap"]').classes() // ["container", "w-full", "h-full"]

此時就可以配合 toContain 等陣列的斷言 Matcher 快速處理測試案例：

1

expect(wrapper.find('[data-test="wrap"]').classes()).toContain('container')

這對於測試樣式採用原子化設計的工具（Tailwind CSS、Windi CSS 等）有奇效，我們可以將視覺層的邏輯透過 classes 的結果斷言。

因為這類原子化設計工具往往依賴 class 屬性來做樣式上的調整與擴充，通常為了美觀與管理方便會順便在使用這類工具時加裝自動排序（sorting） class 屬性等擴充工具，因此 class 的順序將變成不穩定的狀態。

因此元素若從：

1

<p data-test="content" class="A B C">content</p>

變成：

1

<p data-test="content" class="A C B">content</p>

對於快照測試等 Matcher (toMatchSnapshot、toMatchInlineSnapshot)來說將會顯示測試失敗：

1

expect(wrapper.find('.content')).toMatchSnapshot()

快照比對結果：

1
2


- class="A B C"
+ class="A C B"

而以陣列比對是否「包含」的方式，將不受影響：

1
2
3


expect(wrapper.find('.content').classes()).toContain('A')
expect(wrapper.find('.content').classes()).toContain('B')
expect(wrapper.find('.content').classes()).toContain('C')

判斷內容物

text

text 主要是取得目標元素節點後代的所有文字：

RootComponent.vue

1
2
3
4
5
6


<div data-test="target">
 Root
 <child-component />
 <child-component />
 <child-component />
</div>

ChildComponent.vue

1

<p>child</p>

使用 mount 包裝元件時 wrapper.find('[data-test="target"]').text() 的結果將會是：

1

Rootchildchildchild

使用 shallowMount 包裝元件時 wrapper.find('[data-test="target"]').text() 的結果將會是：

1

Root

html

與 text 類似，但 html 會將目標元素後代所有元素都記錄下來：

RootComponent.vue

1
2
3
4
5
6


<div data-test="target">
 Root
 <child-component />
 <child-component />
 <child-component />
</div>

ChildComponent.vue

1

<p>child</p>

使用 mount 包裝元件時 wrapper.find('[data-test="target"]').html() 的結果將會是：

1
2
3
4


Root
<p>child</p>
<p>child</p>
<p>child</p>

使用 shallowMount 包裝元件時 wrapper.find('[data-test="target"]').html() 的結果將會是：

1
2
3
4


Root
<child-component-stub></child-component-stub>
<child-component-stub></child-component-stub>
<child-component-stub></child-component-stub>

因此在使用 text 與 html 來進行斷言時，要注意到「測試所需包含的範圍」以及「元件容器」應採用 mount 還是 shallowMount 等議題，才能讓測試更加強韌且不會讓後續開發無相關的內容時一直被測試攔住。

容器的方法(Wrapper methods) - 模擬事件

滑鼠事件

常見的 DOM 事件有下列幾種：

滑鼠事件：點擊（click）
鍵盤事件：按下某鍵（keydown）、鬆開某鍵（keyup）
表單事件：針對 <input> 輸入內容、checkbox 與 radio 勾選或 <select> 中的選擇內容

首先，語法方面除了表單事件之外，要模擬大部分的事件我們可以透過容器方法中的 trigger 方法即可觸發事件：

1

wrapper.trigger(event, options)

用法是在第一個參數中傳入要觸發的 DOM 事件名稱（e.g. click、drag），如果有需要補充觸發事件的條件，比方像是按下哪個鍵盤，就可以透過第二個參數帶入資訊（e.g. { keyCode: 65 }）。

而要注意到的是由於這些事件基本上都會是非同步的用法，所以在撰寫測試案例時可以使用 async/await 來讓斷言（Assertion）保持正確的結果：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


it('...', async () => {
 // Arrange
 const wrapper = mount(component)

 // Act
 await wrapper.trigger(event, options)

 // Assert
 expect(/* ... */).toBe(/* ... */)
})

有了這個概念之後，接下來便可以快速來看看實際上各個事件觸發的實際案例與事件名稱，並且著重關注要特別注意的地方。

滑鼠事件

點擊： click
雙擊： dblclick
指定點擊： click.left、click.middle、click.right

點擊與雙擊

點擊與雙擊的部分最主要需要注意的部分是，以事件來說的概念「雙擊（dblclick）」是一個事件，並非「兩個」「點擊（click）」事件：

元件

1
2
3
4
5
6
7
8


<script setup>
import { ref } from 'vue'
const count = ref(0)
</script>
<template>
 <p data-test="content">{{ count }}</p>
 <button data-test="button" @click="count++">Add</button>
</template>

測試程式碼

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


it('after click button should display correct content', async () => {
 const wrapper = mount(component)

 await wrapper.find('[data-test="button"]').trigger('click')
 expect(wrapper.find('[data-test="content"]').text()).toBe('1')
 await wrapper.find('[data-test="button"]').trigger('click')
 expect(wrapper.find('[data-test="content"]').text()).toBe('2')
 await wrapper.find('[data-test="button"]').trigger('dblclick') // 觸發不到 @click 事件
 expect(wrapper.find('[data-test="content"]').text()).toBe('4') // AssertionError
})

指定按鍵點擊

有時候你可以會想要指定滑鼠的按鍵來觸發事件，這時就可以使用類似修飾符（modifier）一樣的方式來觸發事件：

click.left
click.middle
click.right

元件

1
2
3
4
5
6
7
8


<script>
 const result = ref('')
</script>

<template>
 <button data-test="button" @click.right="result = 'here we go!'">Are You ready?</button>
 <p data-test="target">{{ result }}</p>
</template>

測試程式碼

1
2
3
4
5


it('should be display correct text', async () => {
 const wrapper = mount(component)
 await wrapper.find('[data-test="button"]').trigger('click.right')
 expect(wrapper.find('[data-test="target"]').text()).toBe('here we go!')
})

除此之外，鍵盤與滑鼠的操作也可以融合再一起：

1
2


trigger('click.ctrl.left') // 左鍵點擊時同時按著 ctrl 鍵
trigger('click.alt.right') // 右鍵點擊時同時按著 alt 鍵

鍵盤事件

鍵盤最常見的核心事件主要為：

按下某個按鈕 keydown
鬆開某個按鈕 keyup

上述事件如同指定滑鼠按鍵的寫法，一樣擁有修飾符的相關語法，而後方帶的修飾符主要為按鍵的名稱：

1
2


trigger('keydown.enter') // 按下 enter 鍵
trigger('keyup.up') // 鬆開 上方向鍵

同樣地，鍵盤事件也支援多重的組合修飾符寫法：

1

trigger('keydown.ctrl.tab') // 按下 ctrl 鍵 + tab 鍵

若你想要更靈活的使用鍵盤事件，也可以用 trigger 方法的第二個參數帶入鍵盤的名稱，而目前有支援的寫法主要有下列三種：

1
2
3
4
5


trigger('事件名稱', {
 code?: event.code;
 key?: event.key;
 keyCode?: event.keycode;
})

若不清楚鍵盤對應的代號也沒有關係，有不少網站專門提供類似的服務供查詢，比方像這個網站只要按下任一按鍵就會即時顯示鍵盤對應的代號、名稱等等相關資訊。

在查到代號後我們就可以將其帶入剛才的方法中：

1

trigger('keydown', { keyCode: 13 })

至於要選擇哪種寫法就看場景本身的需求來做決定囉！

表單事件

input 輸入
checkbox / radio 勾選
<select> 中的選擇內容

原先為了針對不同表單類型，Vue Test Utils 1 版（for Vue2）工具提供了一個專屬的 setChecked 的來對應 checkbox / radio 勾選狀態（checked）；除此之外替 <select> 元素的選擇提供了 setSelected 方法來模擬選擇行為。

而在 Vue Test utils 2 版時，我們將只要統一使用 setValue 即可自動對應所有表單的行為！

模擬 input 輸入

輸入表單或是操作日期選擇器：

1
2
3
4
5
6


<template>
 <input v-model="textResult" type="text" data-test="text"/>
 <p data-test="result_text">{{textResult}}</p>
 <input v-model="dateResult" type="date" data-test="date"/>
 <p data-test="result_date">{{dateResult}}</p>
</template>

文字輸入：

1
2
3
4
5


it('模擬 input 輸入', async () => {
 const wrapper = mount(component)
 await wrapper.find([data-test="text"]).setValue('Hello, World!')
 expect(wrapper.find([data-test="result_text"]).text()).toBe('Hello, World!')
})

選擇日期：

1
2
3
4
5


it('模擬 日期 輸入', async () => {
 const wrapper = mount(component)
 await wrapper.find([data-test="date"]).setValue('2022/10/06')
 expect(wrapper.find([data-test="result_date"]).text()).toBe('2022/10/06')
})

模擬 radio 勾選

元件

1
2
3
4
5


<template>
 <input data-test="radio_1" type="radio" v-model="radioResult" value="1" />
 <input data-test="radio_2" type="radio" v-model="radioResult" value="2" />
 <p data-test="result">{{ radioResult }}</p>
</template>

測試程式碼

1
2
3
4
5
6
7


it('模擬 radio 勾選行為', async () => {
 const wrapper = mount(component)
 await wrapper.find('[data-test="radio_1"]').setValue(true)
 expect(wrapper.find('[data-test="result"]').text()).toEqual('1')
 await wrapper.find('[data-test="radio_2"]').setValue(true)
 expect(wrapper.find('[data-test="result"]').text()).toEqual('2')
})

模擬 checkbox 勾選

元件

1
2
3
4
5


<template>
 <input data-test="checkbox_1" type="checkbox" v-model="checkboxResult" value="1" />
 <input data-test="checkbox_2" type="checkbox" v-model="checkboxResult" value="2" />
 <p data-test="result">{{ checkboxResult.join(',') }}</p>
</template>

測試程式碼

1
2
3
4
5
6
7
8
9


it('模擬 checkbox 勾選行為', async () => {
 const wrapper = mount(component)
 await wrapper.find('[data-test="checkbox_1"]').setValue(true)
 expect(wrapper.find('[data-test="result"]').text()).toBe('1')
 await wrapper.find('[data-test="checkbox_2"]').setValue(true)
 expect(wrapper.find('[data-test="result"]').text()).toEqual('1,2')
 await wrapper.find('[data-test="checkbox_1"]').setValue(false)
 expect(wrapper.find('[data-test="result"]').text()).toEqual('2')
})

模擬 select 選擇

元件

1
2
3
4
5
6
7


<template>
 <select data-test="target" v-model="result">
 <option value="orange">Orange</option>
 <option value="black">Black</option>
 </select>
 <p data-test="result">{{ result }}</p>
</template>

測試程式碼

1
2
3
4
5


it('模擬 select 選擇', async () => {
 const wrapper = mount(component)
 await wrapper.find('[data-test="target"]').setValue('orange')
 expect(wrapper.find('[data-test="result"]').text()).toEqual('orange')
})

模擬 Vue APIs

data

注意：在模擬 data 之前需要注意的是，在大部分的測試時我們通常不必特意去模擬 data，應該讓其與元件本身的私有方法（private method）自然互動即可，若會需要透過模擬 data 來操作元件則要觀察是否資料與元件本身耦合了，這種情況下可能造成元件本身無法高度重複利用。

私有方法（private method）

封閉在元件、物件…等等中的函式，在外部無法存取得到，e.g：

1
2
3
4
5
6


function add5(x){
 const add = (x,y,) => x + y
 return add5(5, x)
}

// 裡頭的 add 函式即為私有方法。

若是真的有需要用到模擬 data 屬性時，首先要注意元件是用何種方式（options API /composition API 與 <script setup>）來使用 data，因為寫法上將會有所不同；且依照設定的時機還可分為「初始狀態」與「後續操作」。

data（options API）

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


<template>
 <p data-test="target">{{ content }}</p>
</template>
<script>
export default {
 data() {
 return {
 content: ''
 }
 }
}
</script>

data（option API）初始狀態模擬，可透過容器（wrapper）的第二個參數帶入：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


/* 測試程式碼 */
const wrapper = mount(component, {
 data(){
 return {
 content: 'test'
 }
 }
})

expect(wrapper.find('[data-test="target"]').text()).toEqual('test')

若要模擬後續才設定 data（option API），則可以透過容器方法中的 setData() 設置，此外由於是非同步的方法，要記得 async/await 才能確保斷言正確：

1
2
3
4
5
6
7
8


it('...', async () => {
 const wrapper = mount(component)

 await wrapper.setData({
 content: 'test'
 })
 expect(wrapper.find('[data-test="target"]').text()).toEqual('test')
})

data（composition API, `<script setup>` 語法糖）

composition API：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


<script>
export default {
 setup() {
 const content = ref('')
 return {
 content
 }
 }
}
</script>

`<script setup>` 語法糖：

1
2
3
4


<script setup>
 import { ref } from 'vue'
 const content = ref('')
</script>

這一類透過 setup() 所處理的資料，若要模擬會遇到不少問題。

在容器方法中的第二個參數所提供的方式，原先是供應給 options API 中的 data 屬性所使用，所以我們必須改以注入的方式嵌入 setup()：

1
2
3
4
5
6
7
8


/* 測試程式碼 */
const wrapper = monut(component, {
 setup(){
 return {
 content:''
 }
 }
})

但如此一來，元件中原先其他寫在 setup() 內的狀態等就必須一起模擬，還記得好的元件測試守則之一嗎？沒錯，就是不要重複實踐實作。

那比較好的方式之一就是透過容器方法中（wrapper）取得實體來設置變數，並且透過 nextTick 方法確保渲染結果：

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


it('...' , async () => {
 /* 測試程式碼 */
 const wrapper = monut(component)
 wrapper.vm.content = 'text'

 // 版本1: 直接使用 vm 內的 $nextTick
 await wrapper.vm.$nextTick()

 // 版本2: 使用 vue 的 nextTick
 // import { nextTick } from 'vue'
 // await nextTick()

 expect(wrapper.find('[data-test="target"]').text()).toEqual('test')
})

而關於私有方法或變數的模擬，或許將來 Vue Test Utils 開發團隊會對此有些改觀提供一些逃生艙的方法，不過目前比較一致的角度是盡量別對這一類的私有環境才有的變數與方法去做模擬，即時的相關討論可見於這裡。

props

在不模擬私有情境的前提之下，prop 相較起來單純多了，而關於測試 props 的部分主要有：

模擬 props 傳入後，斷言「後續的狀態」。
斷言「是否傳入對的參數給子元件」。

模擬 props 傳入

要模擬 props 傳入的方法依照時機可分為「初始狀態」與「後續操作」：

1
2
3


<template>
 <p data-test="target">{{ content }}</p>
</template>

初始狀態同樣是藉由容器（Wrapper）中的第二個參數傳入：

1
2
3
4
5
6
7
8


it('', () => {
 const wrapper = mount(component, {
 props: {
 content: 'Hello'
 }
 })
 expect(wrapper.find('[data-test="target"]').text()).toEqual('Hello')
})

若想要後續才傳入 props 則可以透過容器方法 setProps 模擬，並且一樣要小心非同步的問題，記得補上 async / await ：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


it('...', async () => {
 const wrapper = mount(component, {
 props: {
 content: 'Hello'
 }
 })
 expect(wrapper.find('[data-test="target"]').text()).toEqual('Hello')
 await wrapper.setProps({ content: 'Good bye' })
 expect(wrapper.find('[data-test="target"]').text()).toEqual('Good bye')
})

斷言是否傳入對 props 參數給子元件

既然有接收的一方，那就至少會有給予的一方。

在 props 驗證中的另一種方式就是驗證給予其他元件的參數是否正確：

1
2
3


<template>
 <BaseLightbox content"Hello" enableMask="true" />
</template>

首先我們要做的是透過之前學的選擇器方法選到特定的元件，接著透過容器方法底下的 props() 來取的傳送資訊，接著就可以透過斷言 Matcher 來比對 props 給元件的資訊是否正確：

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


import { BaseLightbox } from './BaseLightbox.vue'
it('', async () => {
 const wrapper = mount(component)
 const target = wrapper.get(BaseLightbox)

 expect(target.props(content)).toEqual('Hello')
 expect(target.props(enableMask)).toEqual(true)
 expect(target.props()).toEqual({
 content: 'Hello',
 enableMask: true,
 })
})

emit

在斷言中我們要測試 emit 主要是試圖捕獲元件所發生的事件，並斷言事件與值是否如我們所預期，而這時可以透過容器方法中的 emitted() 來取得事件發送所有的紀錄。

而 emitted 中所紀錄的格式如下：

1
2
3
4
5
6
7


{
 '事件名稱': [
 [/* 第一次發送的值 */],
 [/* 第二次發送的值 */],
 [/* 第 n 次發送的值 */]
 ]
}

因此假設我們有一個 pagination 元件如下所示：

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


<template>
 <div>
 <div data-test="first" @click="$emit('changePage', 'first')">
 第一頁
 </div>
 <div data-test="prev" @click="$emit('changePage', 'prev')">
 上一頁
 </div>
 <div data-test="next" @click="$emit('changePage', 'next')">
 下一頁
 </div>
 <div data-test="last" @click="$emit('changePage', 'last')">
 最後一頁
 </div>
 </div>
</template>

在斷言的時候我們可以透過下列方式檢查是否發送對應的 emit 事件：

透過 toHaveProperty 確認 emitted 屬性確認是否發送「預期事件名稱」
透過 emitted().事件名稱 確認該事件名稱「發生次數」
透過 emitted().事件名稱[index] 確認該事件名稱，第幾次送出的「值」

1
2
3
4
5
6
7
8
9


it('...', async () => {
 const wrapper = mount(Component)

 await wrapper.find('[data-test="first"]').trigger('click')

 expect(wrapper.emitted()).toHaveProperty('changePage')
 expect(wrapper.emitted().changePage).toHaveLength(1)
 expect(wrapper.emitted().changePage[0]).toEqual(['first'])
})

provide

對於有使用到 provide 的元件來說，我們需要確保他提供預期的 inject 內容，因此我們要建立一個用來接收 provide 的元件，接著才能透過斷言來測試傳遞的內容是否如預期。

接下來我們以這個元件為例：

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


<template>
 <div>
 <ChildComponent />
 </div>
</template>

<script>
import { ref, provide, readonly } from 'vue'
export default {
 setup() {
 const count = ref(1)
 provide('count', readonly(count))
 },
}
</script>

然而我們為了讓測試案例保持獨立性，因此我們要透過造假的元件來測試 inject 所接收到的是否如預期。

透過元件容器中的 global.stubs 模擬假元件

透過元件容器（Wrapper）中的第二個參數 global.stubs 我們可以將子元件渲染成我們想要的樣子，而模擬的方式一共分為兩種：

渲染成 <-stub> 元件

當 global.stub[目標元件名稱] 為 true 時：

1
2
3
4
5
6
7


const wrapper = mount(TargetComponent, {
 global: {
 stubs: {
 ChildComponent: true,
 },
 },
})

我們的目標元件將會被渲染為帶有 -stub 後綴的元素：

1
2
3
4
5


<template>
 <div>
 <ChildComponent /> <!-- 會變成 <child-component-stub></child-component-stub> -->
 </div>
</template>

然而這對於我們要測試 provide 來說沒有幫助，因為他沒有辦法接收 inject 資訊，因此我們要採用下面第二種方法。

渲染成特定元件

要渲染成特定元件的方式，就是先製作一個假元件，接著再提供給 global.stubs 來當作原先應該要渲染的元件。

首先，我們可以透過 Vue 提供的 defineComponent 建造元件：

1
2
3
4
5
6
7
8
9


import { defineComponent } from 'vue'

const TestComponent = defineComponent({
 template: '<p data-test="target">{{ count }}</p>',
 setup() {
 const value = inject('count')
 return { value }
 },
})

接著在測試案例就可以透過 global.stubs 中直接使用這個測試元件：

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


import { defineComponent } from 'vue'

const TestComponent = defineComponent({
 template: '<p data-test="target">{{ count }}</p>',
 setup() {
 const value = inject('count')
 return { value }
 },
})

it('...' , () => {
 const wrapper = mount(TargetComponent, {
 global: {
 stubs: {
 ChildComponent: TestComponent,
 },
 },
 })
})

如此一來元件 ChildComponent 在測試案例中的渲染結果將變成我們指定的樣子。

1
2
3


<div>
 <p data-test="target">1</p>
</div>

因此我們現在就可以斷言 provide 提供的內容是否正確了：

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


const TestComponent = defineComponent({
 template: '<p data-test="target">{{ count }}</p>',
 setup() {
 const count = inject('count')
 return { count }
 },
})
it('...', async () => {
 const wrapper = mount(TargetComponent, {
 global: {
 stubs: {
 ChildComponent: TestComponent,
 },
 },
 })

 expect(wrapper.find('[data-test="target"]').text()).toBe('1')
})

inject

對於有使用到 inject 的元件來說，我們在意的是提供 provide 特定的值之後，畫面上渲染的結果是否正確。

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


<template>
 <div data-test="target">{{ count }}</div>
</template>

<script>
import { inject } from 'vue'
export default {
 setup() {
 const count = inject('count')

 return { count }
 },
}
</script>

此時我們可以透過元件容器（Wrapper）中的第二個參數 global 來指定要提供的 provide 值：

1
2
3
4
5
6
7


const wrapper = mount(TargetComponent, {
 global: {
 provide: {
 count: 1,
 },
 },
})

最後我們就可以直接斷言渲染的結果是否如預期：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


it('should be render correct content after providing count', async () => {
 const wrapper = mount(TargetComponent, {
 global: {
 provide: {
 count: 1,
 },
 },
 })

 expect(wrapper.find('[data-test="target"]').text()).toBe('1')
})

slots

而在針對 slots 撰寫測試時，要注意的地方有：

slots 至少會有預設未傳入的狀態與傳入資料後的狀態兩種，斷言時應該至少包含這兩種狀態。
以 slots 行為作為案例斷言時，斷言內容要專注在 slots 所影響範圍內，否則可能會受其他因素干擾。

預設插槽（Default slots）

1
2
3
4
5


<template>
 <div>
 <slot></slot>
 </div>
</template>

要針對最基本的預設插槽做斷言時，我們可以透過容器中第二個參數帶入 slots 欄位來模擬帶入內容並透過 default 屬性傳入指定的範圍內。

未傳入測試案例：

1
2
3
4


it('default slot', async () => {
 const wrapper = mount(Component)
 expect(wrapper.html()).toMatchInlineSnapshot()
})

傳入時測試案例：

1
2
3
4
5
6
7
8
9


it('default slot', async () => {
 const wrapper = mount(Component, {
 slots: {
 default: 'Slot Content',
 },
 })

 expect(wrapper.html()).toContain('Slot Content')
})

具名插槽（Named slots）

1
2
3
4
5
6
7


<template>
 <div>
 <slot name="header"></slot>
 <slot name="body"></slot>
 <slot name="footer"></slot>
 </div>
</template>

若在插槽的型態為具名插槽，在撰寫測試案例時的容器選項 slots 就可以依據插槽名稱 name 指定要傳入的內容。

未傳入測試案例：

1
2
3
4


it('named slot', async () => {
 const wrapper = mount(Component)
 expect(wrapper.html()).toMatchInlineSnapshot()
})

傳入時測試案例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


it('named slot', async () => {
 const wrapper = mount(Component, {
 slots: {
 header: 'ithelp 2022 鐵人賽',
 body: 'vue3 單元測試',
 footer: 'by Shawn',
 },
 })

 expect(wrapper.html()).toMatchInlineSnapshot()
})

作用域插槽（Scoped slots）

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


<template>
 <div>
 <p>貓咪咖啡廳：</p>
 <p>店長：Shawn</p>
 <slot :staffInfo="staffInfo"></slot>
 </div>
</template>

<script setup>
const staffInfo = {
 'black-cat': {
 name: '黑黑',
 'signature-dish': '拿鐵',
 },
 'orange-cat': {
 name: '阿橘',
 'signature-dish': '焦糖瑪奇朵',
 },
}
</script>

有時候我們可能想要給予更高度的彈性，使元件透過 <slot> 傳遞資料給父層時，這時候就會用到作用域插槽。

未傳入測試案例：

1
2
3
4
5
6
7
8
9


it('scoped slots', async () => {
 const wrapper = mount(Component)
 expect(wrapper.html()).toMatchInlineSnapshot(`
 "<div>
 <p>貓咪咖啡廳：</p>
 <p>店長：Shawn</p>
 </div>"
 `)
})

傳入時測試案例：

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


it('scoped slots', async () => {
 const wrapper = mount(Component, {
 slots: {
 default: `
 <template #staffInfo>
 <p>店員：{{ staffInfo['orange-cat']['name'] }}</p>
 <p>限定項目：{{ staffInfo['black-cat']['signature-dish'] }}</p>
 </template>
 `,
 },
 })

 expect(wrapper.html()).toMatchInlineSnapshot(`
 "<div>
 <p>貓咪咖啡廳：</p>
 <p>店長：Shawn</p>
 <p>店員：阿橘</p>
 <p>限定項目：拿鐵</p>
 </div>"
 `)
})

插槽載入選項（Mounting options）

若想在測試案例中用不同的方式來模擬 slots，可以透過下面四種語法：

傳入 SFC 檔案
render function
包含 template 屬性的物件
直接傳入一個字串

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


it('should render same layout', () => {
 const wrapper = mount(Layout, {
 slots: {
 default: Component
 // default: h('div', '相同內容'),
 // default: { template: '<div>相同內容</div>' },
 // default: '<div>相同內容</div>',
 }
 })
 expect(wrapper.html()).toContain('<div>相同內容</div>')
})

custom directives

客製化指令本身搭配了類似元件生命週期的 Hooks，而我們可以在那些 Hook 中任意對我們所綁定的元素做開發，讓繁複的邏輯透過簡單的指令就能夠重複利用，使我們在開發過程中的開發者體驗（Developer experience, DX）有非常良好的體驗。

但相對的來說，要測試客製化指令就有機會運用到各種我們至今學過的許多技巧來斷言，從而使難度大大提升，但我們只要熟悉之前的模擬技巧後，最後只需要關注的一個地方就是，預期指令放入後應達成什麼目標，接著再去尋找要從什麼角度或可取得的資訊去比對來作為我們斷言的內容即可。

而接下來我們以一個 v-foucs 的客製化指令來介紹如何斷言客製化指令與尋找比對資訊：

1
2
3


const vFocus = {
 mounted: (el) => el.focus(),
}

註冊指令

首先，要進行斷言我們可以透過容器中第二個參數的 global.directives 來註冊我們的客製化指令：

1
2
3
4
5
6
7


const wrapper = mount(..., {
 global: {
 directives: {
 Focus: vFocus, // 屬性匹配的名稱規則 Abc 會 match 到 v-abc
 },
 },
})

仿造元件並放入指令

接著我們要使用到仿造元件的技巧，讓容器一開始就載入一個假的元件，並且放入指令與 data-test 屬性供捕獲：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


const Component = {
 template: '<input v-focus data-test="target" type="text"/>',
}
const wrapper = mount(..., {
 global: {
 directives: {
 Focus: vFocus,
 },
 },
})

尋找比對目標

再來，由於目標是為了驗證是否該元素為瀏覽器中的 focus 元素，因此要利用到瀏覽器物件 Document 中的 activeElement 屬性，若有被聚焦的情況下那應該要能夠比對到同個元素。（由 jsdom 提供模擬的瀏覽器環境）

斷言

最後在斷言的部分，為了取得目標元素，我們可以透過 wrapper.find().element 取得目標的元素實體，最後就可以拿他與 document.activeElement 做比對：

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


it('v-focus', async () => {
 const Component = {
 template: '<input v-focus data-test="target" type="text"/>',
 }
 const wrapper = mount(Component, {
 attachTo: document.body,
 global: {
 directives: {
 Focus: vFocus,
 },
 },
 })

 expect(wrapper.find('[data-test="target"]').element).toBe(document.activeElement)
})

如此一來我們就可以確保將來在使用 v-focus 指令時，該元素在 mounted 後會是聚焦的元素。

Vitest UI

Vitest UI 簡單來說，是另一種供我們查看測試與編寫測試的方式，它的特色在於基於 Vite 的 dev server 環境，讓我們可以直接在瀏覽器上直接觀看測試案例的測試結果，甚至支援直接在瀏覽器中編寫測試案例後同步更新測試檔案。

而在使用這項酷酷的功能之前，我們需要另外安裝 @vitest/ui：

1

npm i -D @vitest/ui

接著就可以在 package.json 中新增一個 vitest 指令，並帶上參數 --ui：

1
2
3
4
5


{
 "scripts": {
 "vitest:ui": "vitest --ui"
 }
}

如此一來後們只要執行 npm run vitest:ui，就可以在啟動這項功能，並看到下列畫面：

介面

在 Vitest UI 中，左側是所有測試案例的測試結果（Pass / Fail / Skip），我們可以透過上方的搜尋欄輸入檔名或路徑找到我們要觀察的測試。

點擊左側的測試路徑後，右側會出現測試情境與測試案例的描述讓我們更好觀察當下檔案中的所有案例

除此之外，再往右側會看到四項資訊，分別為：

Report（預設顯示項目）
Module Graph
Console
Code

Report

點擊 Report 頁籤時，會在右側顯示該測試檔案中的所有測試案例結果。

若為全通過的情況會顯示 All tests passed in this file：

若有錯誤會顯示是哪一條測試案例發生錯誤：

我們甚至能點擊錯誤訊息右方的開啟視窗 Icon，Vitest UI 將會直接啟動系統預設的程式碼編輯器，開啟測試檔案後將輸入游標聚焦在錯誤的行數與位置。（e.g. 圖中的 toEqual Assertion Matcher）

Module Graph

接著是第二個頁籤的 Module Graph，這頁的內容主要是透過檢測行內引入模組，呈現檔案之間依賴關係。

點擊圖中的節點可以看到該模組的 Source 檔與經由 Transformed 後的程式碼。

而這個圖表最大的用處在於，透過可視化的方式呈現出測試程式碼中受測物（SUT）與依賴物（DOC）的依賴狀況。

Console

Console 頁籤主要是顯示在測試程式碼中的 console.log 資訊，由於與測試結果分離的情況下，相較於在終端機中觀察 Console，這裡會顯示得更加清楚。

Code

最後壓軸介紹的部分，則是 Code 頁籤，你可能會覺得這有什麼特別的，不就是顯示測試檔案程式碼嗎？

然而，這裡的測試程式碼除了預覽之外，還能夠直接在瀏覽器中直接編寫並執行測試查看結果，更重要的是寫完的當下按下儲存它還能夠同步調整到實際的程式碼中！

比方在瀏覽器中的測試程式碼中加個註解，並儲存：

實際測試程式碼檔案也加上了註解！

如此一來，我們就可以直接在這個視窗內撰寫我們的測試案例，並且在瀏覽器中即時看到測試結果。

不過這裡有個小小缺點是，若在專案中有設定 eslint + prettier 的話，在程式編輯器撰寫測試時可以設定儲存當下的自動做格式化，但是瀏覽器中的編輯器環境不同，所以寫測試時會收到格式錯誤的警告，但在不考慮這點的情況下，這個工具是個用來檢視測試結果與依賴關係的好工具。

程式碼覆蓋率（Code Coverage）

在測試領域中，覆蓋率（Coverage）一詞泛指的是以百分比表示測試程式碼能夠涵蓋多少產品程式碼的範圍，而依據不同的覆蓋率種類，其細微的定義也會有所不同。

接下來我們以覆蓋率工具庫 c8 來說明覆蓋率的概念與如何透過 c8 在 Vitest 測試環境中檢視當下的測試覆蓋率，最後再來談談有關於覆蓋率的相關議題。

c8

要在 Vitest 測試環境中使用 c8 產生覆蓋率報告，我們首先需要安裝 @vitest/coverage-c8：

1

npm i -D @vitest/coverage-c8

接著就可以在 package.json 中新增指令：

1
2
3
4
5


{
 "scripts": {
 "test:coverage": "vitest --environment jsdom --coverage"
 }
}

執行 npm run test:coverage 後，預設會在終端機產生出覆蓋率報告：

而 c8 覆蓋率報告總共有四種類型：

行數覆蓋率（line coverage）：以行數為單位來計算。
函式覆蓋率（function coverage）：以內部的函式為單位來計算。
分枝覆蓋率（branch coverage）：以每個判斷式為單位來計算。
語句覆蓋率（statement coverage）：以每個語句（statement）為單位計算。

測試程式碼涵蓋多少範圍的產品程式碼，甚至於每行程式碼個被執行了幾次

並且若有未覆蓋行數的情況， c8 則會在 Uncovered Line 中顯示未涵蓋的行數範圍，如下圖中的 13-17、19-28

倘若你覺得這種報告形式不方便觀看，或是希望將它製作成文件，則可以在 config.js 檔中設定 coverage.reporter 的形式：

1
2
3
4
5
6
7
8


// vite.config.js or vitest.config.js
export default defineConfig({
 test: {
 coverage: {
 reporter: ['text', 'json', 'html'],
 },
 },
})

其中 c8 提供的報告（reporter）選項有以下三種：

text：在終端機中呈現覆蓋率報告。

json：以 JSON 格式產生覆蓋率報告。

html：產生一個可互動的 HTML 覆蓋率報告。

其中 HTML 的版本中，我們還可以點擊測試檔案來查看未覆蓋的行數有哪些，相較終端機的版本，我們就不必再拿著行數去對程式碼了：

覆蓋率目標

而在瞭解怎麼查看覆蓋率報告後，那麼究竟覆蓋率目標要達到多少才是合理呢？

以《可測試的 JavaScript》一書作者 Mark Ethan Trostler 提供的答案是單元測試大約要介於 80 % 左右。

以 Martin Fowler 於 Test Coverage 一文中，則是指出大約會在於 80 至 90 % 附近。

至於為什麼不是達到百分之百呢？接下來我們來探討有關於覆蓋率相關的議題。

覆蓋率議題

覆蓋率與付出的心力

雖然以理論上來說盡可能得達到高覆蓋率，測試程式碼將涵蓋的越完全，然而為了追求 100 % 的覆蓋率所要付出的心理將會截然不同。

Jeroen Mols 在 The 100% code coverage problem 一文中的提到了心力付出與覆蓋率的關係表。

引用自 Jeroen Mols 《The 100% code coverage problem》一文中的圖

從上圖中可以看見，在覆蓋率從 0 提升至 80% 我們僅需要付出一些心力就可以輕易達成，然而要將 90% 提升至接近 100% 我們則幾乎要投入兩到三倍以上的心力才能完成。

因此，有些人雖然會認為 100% 的覆蓋率是一個不錯的目標，但是在實際上，我們可能會因為追求 100% 的覆蓋率而付出過多的心力，而導致測試程式碼的品質反而變差。

覆蓋率 100% 的誤區

在費盡千辛萬苦後，我們終於達到了 100% 覆蓋率的情況了。

然而，100 % 的覆蓋率僅能代表測試程式碼完整（Complete）的覆蓋了產品程式碼，並非代表測試程式碼的品質達到完美（Perfect），接下來我們用個簡單的例子來說明：

1
2
3
4
5


const max = (x, y) => return x

test('max', () => {
 expect(max(2, 1)).toBe(2)
})

在上方案例中，我們可以看見 max 測試案例基本上已經完全覆蓋了 max 函式的實作情況，而我們可以從這個案例中看出兩個問題：

產品程式碼本身有問題，即便測試程式碼覆蓋了 100% 的情況下，產品程式碼本身仍然是有問題的。
測試程式碼案例與路徑不足，導致覆蓋率為 100% 的情況下，並沒有測出產品程式碼中的問題與邊際案例（edge case）。

因此覆蓋率 100% 充其量只是一個指標，用來告訴我們測試程式碼是否完整的覆蓋了產品程式碼，而非「完全沒有問題」。

倘若我們想要盡可能避免這種情況的發生，這時我們就可以透過突變測試（Mutation Testing）來協助我們。

突變測試（mutation testing）

突變測試（Mutation Testing）是一種驗證與改善測試程式碼的測試方法，概念上來說，他會盡可能的抽換產品程式碼中的每個角落，接著依照抽換規則來預期測試程式碼的檢測結果。

假設我們有個比較函式如下：

1

const greaterThan = (x, y) => x > y

而這時我們測試程式碼可能會這麼處理：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


it('should return true if x is greater than y', () => {
 expect(greaterThan(2, 1)).toBe(true)
 expect(greaterThan(0, -1)).toBe(true)
 expect(greaterThan(100, 0)).toBe(true)
})
it('should return false if x is less than y', () => {
 expect(greaterThan(1, 2)).toBe(false)
 expect(greaterThan(-1, 0)).toBe(false)
 expect(greaterThan(0, 100)).toBe(false)
})

接著突變測試可能會將 greaterThan 函式中的 > 符號替換成 >= 符號，此時理論上來說應該會有測試案例失敗，但是實際上測試程式碼卻沒有檢測到這個問題，那就表示我們的測試程式碼並沒有覆蓋到這個案例。

此時我們就可以針對這種情況，再補上對應的測試案例：

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


it('should return true if x is greater than y', () => {
 expect(greaterThan(2, 1)).toBe(true)
 expect(greaterThan(0, -1)).toBe(true)
 expect(greaterThan(100, 0)).toBe(true)
})
it('should return false if x is less than y', () => {
 expect(greaterThan(1, 2)).toBe(false)
 expect(greaterThan(-1, 0)).toBe(false)
 expect(greaterThan(0, 100)).toBe(false)
})
// 新增案例
it('should return false if x is equal y', () => {
 expect(greaterThan(1, 1)).toBe(false)
})

接著突變測試再度將 > 符號替換成各種符號（e.g. <=），甚至是將 {} 語句（statement）清空，而諸如此類的手法，就是突變測試的核心概念。

若想手動置換產品程式碼中的符號，可以從這些方法下手

operator: +, -, *, /

condition: <, >, <=, >=, ==, ===, !=, !==

statement: {}, if, else, for, return, throw, try, catch

expression: &&, ||, !

突變測試的工具

雖然說我們可以手動置換產品程式碼中的各種符號，但是這樣的作法會讓我們的工作量變得非常龐大，因此我們可以透過工具來協助我們完成這些工作。

以前端領域來說，我們可以透過 Stryker Mutator 底下的 stryker-js 工具來完成這些工作。

Stryker Mutator 的概念就是透過替換不同的符號產生出突變的內容，而我們的測試程式碼應該要捕捉到那些不合理的情況，藉此來保證我們的測試案例有一定的穩固性。

然而，可惜的是 stryker-js 目前僅支援到 Jest 環境，尚未支援 Vitest 的環境，因此我這邊就暫不做介紹了，有興趣者可以追蹤該 issue 目前的最新進度。

Typescript on Wayne's blog | 偉恩的部落格 | 技術博客

【Typescript】5.0 版本發布

自 Beta 和 RC 以來有什麼新功能？

裝飾器

與實驗性遺留裝飾器的差異

編寫類型良好的裝飾器

const 泛型參數

extends 支持多個配置文件

所有枚舉都是聯合枚舉

--moduleResolution 新增 bundler 支持

自定義解析標誌

allowImportingTsExtensions

resolvePackageJsonExports

resolvePackageJsonImports

allowArbitraryExtensions

app.css

app.d.css.ts

App.tsx

customConditions

--verbatimModuleSyntax

支持 export type *

JSDoc 支持 @satisfies

JSDoc 支持 @overload

在tsc --build 時可以傳入的新指令

編輯器中不區分大小寫的導入排序

switch/case 語法補足

速度、內存和包大小優化

重大更改和棄用

運行時要求

lib.d.ts變化

API 重大變更

關係運算符中禁止的隱式強制轉換

枚舉大修

對構造函數中的參數裝飾器進行更準確的類型檢查 --experimentalDecorators

棄用和默認更改

下一步是什麼？

【Petite-Vue】大小只有 ~6KB 的 mini Vue！

Petite-Vue 的特點

什麼是 Petite-Vue？

代碼庫結構介紹

範例(一) - 在線渲染

範例(二) - 組件化

快速上手

自動初始化

手動初始化

根作用域 (Root Scope) / 作用域 (Scope)

掛載元素 (Mount)

生命週期

v-effect

組件 (Component)

純數據的函數組件

帶有模板的函數組件

全局狀態管理

指令 (Directive)

內建指令

自定義指令

自定義模板

Petite-Vue vs Vue

總結

【Typescript】tsconfig.json 的設定與資料型別介紹筆記

TypeScript 是什麼？

tsconfig.json

tsconfig.json 的預設

tsconfig.json 還有哪些設定？

TypeScript 資料型別整理表

typescript 的特殊型別

any

未宣告型別的變數及參數也視為 any 型別

用 noImplicitAny，來提醒我使用了 any

unknown

void

never

Union Types (聯合型別)

存取聯合型別的屬性或方法

Intersection Types (交集型別)

Literal Types 字面值型別

string literal types

numeric literal types

non-literal types

Tuple 元組

`--moduleResolution` 新增 bundler 支持

`--verbatimModuleSyntax`

支持 `export type *`

JSDoc 支持 `@satisfies`

JSDoc 支持 `@overload`

在tsc `--build` 時可以傳入的新指令

`lib.d.ts`變化

對構造函數中的參數裝飾器進行更準確的類型檢查 `--experimentalDecorators`

BONUS：使用自定義的 tsconfig.json