TypeScript 進階型別操作：`satisfies` 運算子（TS 4.9+）

簡介

在大型前端專案中，型別安全是維持程式碼可維護性與可靠性的關鍵。自 TypeScript 4.9 起，新增的 satisfies 運算子提供了一種 在保留原始值型別的同時，驗證物件或陣列結構符合指定型別的方式。它彌補了 as 斷言與直接指定型別之間的灰色地帶，讓開發者在 編譯期 捕捉更細微的錯誤，同時避免不必要的型別寬鬆化。

本篇文章將深入探討 satisfies 的運作原理、常見使用情境與最佳實踐，並提供多個實務範例，協助你在日常開發中即時提升型別嚴謹度。

核心概念

1. `satisfies` 與 `as`、`:` 的差異

用法	語法	目的	編譯結果
型別註記 (`:`)	`const obj: T = {...}`	將值斷言為 T，若值不符合 T，會在編譯時錯誤；變數的推斷型別會變成 T。	變數型別被收斂為 T。
斷言 (`as`)	`const obj = {...} as T`	告訴編譯器把值視為 T，不做結構檢查；可能隱藏錯誤。	變數型別被擴張為 T。
`satisfies`	`const obj = {...} satisfies T`	檢查值是否符合 T，但不改變變數本身的推斷型別。	變數保留原始推斷型別，同時得到編譯時驗證。

重點：satisfies 僅作為型別檢查，不會改變變數的推斷結果，讓你既能確保結構正確，又不失去原始型別資訊（例如字面量類型）。

2. 基本語法

const config = {
  host: "localhost",
  port: 8080,
  secure: false,
} satisfies ServerConfig;

ServerConfig 為一個介面或型別別名。
若 config 少了 port 或 secure 的型別不匹配，編譯器會報錯。
config 的型別仍然是 字面量型別 { host: "localhost"; port: 8080; secure: false; }，因此在後續使用時可以獲得更精確的自動完成與檢查。

3. 為何需要 `satisfies`？

保留字面量型別：在設定檔、路由表等需要「精確值」的情境，satisfies 能讓你同時得到型別檢查與字面量推斷。
避免過度寬鬆：使用 as 可能讓錯誤靜默；使用 : 會把變數「收斂」成寬鬆的介面，失去原始值的細節。
支援映射型別與條件型別：satisfies 能與 keyof、typeof 等結合，寫出更動態的型別驗證。

程式碼範例

以下示範 5 個常見且實用的 satisfies 用法，均配有註解說明。

範例 1：簡易設定檔驗證

interface ServerConfig {
  host: string;
  port: number;
  secure: boolean;
}

// ✅ 正確符合 ServerConfig
const devConfig = {
  host: "localhost",
  port: 3000,
  secure: false,
} satisfies ServerConfig;

// ❌ 少了一個屬性會在編譯時錯誤
// const badConfig = {
//   host: "example.com",
//   port: 443,
// } satisfies ServerConfig; // Error: Property 'secure' is missing

說明：若使用 as ServerConfig，上述錯誤會被忽略；若使用 :，devConfig 的型別會被收斂成 ServerConfig，失去 host: "localhost" 這樣的字面量資訊。

範例 2：保留字面量型別於路由表

type Route = {
  path: `/${string}`;
  method: "GET" | "POST" | "PUT" | "DELETE";
  handler: () => void;
};

const routes = [
  {
    path: "/users",
    method: "GET",
    handler: () => console.log("list users"),
  },
  {
    path: "/users",
    method: "POST",
    handler: () => console.log("create user"),
  },
] satisfies ReadonlyArray<Route>;

// routes[0].method // => "GET" (字面量型別，IDE 可提供完整補完)

重點：satisfies 讓 routes 保持 只讀陣列 且每個元素的字面量型別不被收斂，對於後續的路由檢查與自動完成非常有幫助。

範例 3：與 `keyof` 共同使用，保證物件鍵的正確性

type Theme = {
  primary: string;
  secondary: string;
  background: string;
};

const themeColors = {
  primary: "#ff6600",
  secondary: "#0066ff",
  background: "#ffffff",
} satisfies Record<keyof Theme, string>;

// 若錯寫成 backgroundColor，編譯會直接報錯

說明：Record<keyof Theme, string> 動態取得 Theme 的所有鍵，satisfies 確保 themeColors 完整對應，且不會把 themeColors 的型別收斂成 Record<...>，仍保留每個屬性的字面量值。

範例 4：條件型別結合 `satisfies` 檢查 API 回傳結構

type ApiResponse<T> = {
  success: true;
  data: T;
} | {
  success: false;
  error: string;
};

type User = { id: number; name: string };

const mockResponse = {
  success: true,
  data: { id: 1, name: "Alice" },
} satisfies ApiResponse<User>;

// 若把 success 設為 false 卻仍提供 data，編譯器會警告

實務價值：在寫測試或 mock 資料時，satisfies 能保證 每個分支 的結構正確，減少因手寫 mock 而產生的錯誤。

範例 5：使用 `as const` 與 `satisfies` 共同打造不可變常數

type Action = {
  type: "increment" | "decrement";
  payload: number;
};

const incrementAction = {
  type: "increment",
  payload: 1,
} as const satisfies Action;

// incrementAction.type   // "increment" (字面量型別)
// incrementAction.payload // 1 (字面量型別)

技巧：as const 讓物件變為 只讀且字面量推斷，再配合 satisfies 確認符合 Action 介面，兩者結合是 Redux、NgRx 等狀態管理工具的常見寫法。

常見陷阱與最佳實踐

陷阱	說明	解決方案
忘記使用 `satisfies`	直接使用 `:` 或 `as` 會失去字面量資訊或隱藏錯誤。	在需要同時驗證與保留字面量時，優先考慮 `satisfies`。
對泛型型別使用不當	`satisfies` 只能在具體值上使用，不能直接放在泛型參數宣告處。	先把具體值賦給變數，再使用 `satisfies` 進行檢查。
過度依賴 `as const`	`as const` 會把所有屬性變成只讀，若不需要只讀會造成不必要的限制。	僅在確定不會再變更的資料上使用，或搭配 `satisfies` 只保留必要的只讀性。
與 `unknown` 結合時的錯誤訊息	`satisfies` 會把錯誤訊息投射到最底層屬性，訊息有時過長。	使用型別別名包裝錯誤訊息，或在 IDE 中啟用 TypeScript 4.9 的 `--pretty` 輸出。
在函式返回值上使用 `satisfies`	`satisfies` 只能在表達式上使用，不能直接放在函式宣告的返回型別。	在函式內部先建立暫存變數，使用 `satisfies` 檢查後再回傳。

最佳實踐

先寫 as const 再 satisfies：保留字面量，同時驗證結構。
將型別別名抽離：讓錯誤訊息更易讀，並可在多處重複使用。
在大型設定檔、路由表、API mock 中統一使用 satisfies，確保所有欄位完整且型別正確。
結合 readonly：若資料不應被改變，使用 satisfies Readonly<...>，讓編譯器同時檢查與限制寫入。
在 CI/CD 流程中開啟 noImplicitAny、strict，確保 satisfies 的型別推斷不被寬鬆設定掩蓋。

實際應用場景

1. 前端設定檔（environment.ts）

在多環境專案中，environment 物件常包含 API URL、Feature Flag 等。使用 satisfies 可在 開發階段即捕捉缺漏，同時保留每個屬性的字面量值，讓後續的 process.env 取值更安全。

interface EnvConfig {
  apiBase: string;
  enableLogging: boolean;
  featureToggle: {
    newDashboard: boolean;
  };
}

export const environment = {
  apiBase: "https://dev.api.example.com",
  enableLogging: true,
  featureToggle: {
    newDashboard: false,
  },
} satisfies EnvConfig;

2. Redux / NgRx Action 常量

在狀態管理中，Action 必須嚴格符合 { type, payload } 結構。satisfies 能避免 type 拼寫錯誤 或 payload 型別不符。

type CounterAction = {
  type: "increment" | "decrement";
  payload: number;
};

export const inc = {
  type: "increment",
  payload: 1,
} as const satisfies CounterAction;

3. API Mock 與測試資料

單元測試常需要模擬後端回傳。satisfies 能確保 測試資料符合實際 API 定義，減少因測試與實際不一致而產生的錯誤。

type Product = {
  id: number;
  name: string;
  price: number;
};

const mockProduct = {
  id: 101,
  name: "Keyboard",
  price: 49.99,
} satisfies Product;

4. 動態生成的 UI 配置

例如表格欄位、表單欄位等設定，常以陣列或物件形式傳遞。使用 satisfies 能在 編譯時驗證每個欄位的必填屬性，避免跑時錯誤。

type TableColumn = {
  key: string;
  label: string;
  sortable?: boolean;
};

const columns = [
  { key: "id", label: "ID", sortable: true },
  { key: "name", label: "名稱" },
] satisfies ReadonlyArray<TableColumn>;

總結

**satisfies** 是 TypeScript 4.9 之後的關鍵型別工具，結合了嚴格的結構驗證與保留字面量推斷，在以下情境中尤為有價值：

設定檔、路由表、API mock：在開發階段即捕捉遺漏或錯誤。
狀態管理 Action：防止 type 拼寫與 payload 型別不符。
大型陣列或物件集合：保持只讀與精確的自動完成。

使用時務必遵守「先 as const 再 satisfies」的模式，避免過度寬鬆的斷言或收斂型別的資訊遺失。透過上述範例與最佳實踐，你可以在日常開發中更安心地使用 TypeScript，讓程式碼在 編譯期即獲得更高的安全保證，同時保持彈性與可讀性。

最後提醒：satisfies 並不會改變執行時的行為，它僅是 編譯期的型別檢查。若想在執行時驗證資料結構，仍需搭配 runtime validation（例如 Zod、io-ts）一起使用。祝你在 TypeScript 的進階型別世界中玩得開心！

TypeScript 進階型別操作：satisfies 運算子（TS 4.9+）

簡介