TypeScript 模組與命名空間（Modules & Namespaces）

主題：模組別名（Module Aliases）

---

簡介

在大型前端或 Node.js 專案中，模組（module） 是組織程式碼的核心概念。隨著檔案數量的增長，引用路徑往往變得冗長且易出錯，例如 import { User } from '../../../models/user'。此時 模組別名（module alias） 就能大幅提升可讀性、維護性與開發效率。

本篇文章將從概念說明、設定方式、實作範例、常見陷阱與最佳實踐，逐步帶你掌握在 TypeScript 中使用模組別名的技巧，讓你的程式碼結構更清晰、匯入更直觀。

---

核心概念

1. 為什麼需要模組別名？

• 減少相對路徑的層層上升：長度不一的 ../../.. 會讓檔案移動時產生大量修改。
• 提升語意：別名能直接表達「這是一個工具函式」或「這是 API 介面」等意圖。
• 統一管理：只要在一個設定檔改動別名，即可全專案同步更新。

2. TypeScript 中的別名設定位置

設定檔	作用範圍
tsconfig.json 的 compilerOptions.paths	編譯階段的路徑映射，適用於 ESM、CommonJS、Node 等環境。
webpack.config.js 的 resolve.alias	打包階段的別名，配合 ts-loader 或 babel-loader 使用。
vite.config.ts 的 resolve.alias	Vite 開發伺服器與打包的別名設定。
jsconfig.json（VS Code）	僅提供編輯器 IntelliSense，對編譯無影響。

重點：若只在 tsconfig.json 設定別名，編譯器可以正確解析；但在實際執行（Node、瀏覽器）時，仍需相同的別名映射給 bundler 或執行環境。

3. paths 的語法與範例

{
  "compilerOptions": {
    "baseUrl": "./src",               // 所有相對路徑的基礎目錄
    "paths": {
      "@utils/*": ["utils/*"],        // @utils → src/utils
      "@components/*": ["components/*"],
      "@models": ["models/index"]     // 單一檔案別名
    }
  }
}

• * 為萬用字元，會對應到同層的子路徑。
• 若別名指向單一檔案（如 @models），則不需要 *。

---

程式碼範例

以下示範 三種不同情境 的模組別名使用方式，皆以 TypeScript 為例，並加入詳細註解。

範例 1：簡單的工具函式別名

// src/utils/math.ts
export function add(a: number, b: number): number {
  return a + b;
}
export function mul(a: number, b: number): number {
  return a * b;
}

// tsconfig.json (只顯示相關部分)
{
  "compilerOptions": {
    "baseUrl": "./src",
    "paths": {
      "@utils/*": ["utils/*"]
    }
  }
}

// src/app.ts
// 使用別名 @utils 直接匯入函式，省去 ../../utils 的相對路徑
import { add, mul } from '@utils/math';

console.log(add(2, 3)); // 5
console.log(mul(4, 5)); // 20

說明：@utils/math 會被編譯器解析為 src/utils/math.ts，讓檔案搬移或重新命名時，只要更新 paths 即可。

---

範例 2：React 元件的別名與自動匯入

// src/components/Button.tsx
import React from 'react';

export const Button: React.FC<{ onClick: () => void }> = ({ onClick, children }) => (
  <button onClick={onClick}>{children}</button>
);

// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": "./src",
    "paths": {
      "@components/*": ["components/*"]
    }
  }
}

// src/pages/Home.tsx
import React from 'react';
import { Button } from '@components/Button'; // 別名讓匯入更直觀

export const Home: React.FC = () => (
  <div>
    <h1>Welcome Home</h1>
    <Button onClick={() => alert('Clicked!')}>點我</Button>
  </div>
);

技巧：在 VS Code 中安裝 Path Intellisense 或使用內建的 自動匯入 功能，別名會自動出現在建議清單裡，提升開發效率。

---

範例 3：多層目錄與單檔別名（Index Re-export）

// src/models/user.ts
export interface User {
  id: string;
  name: string;
}

// src/models/index.ts
export * from './user';    // 重新導出，形成單一入口點

// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": "./src",
    "paths": {
      "@models": ["models/index"]
    }
  }
}

// src/services/auth.ts
import { User } from '@models'; // 只寫 @models，背後指向 models/index.ts

export function getCurrentUser(): User {
  // 假設從 localStorage 取得
  return JSON.parse(localStorage.getItem('user')!);
}

優點：當模型檔案增多時，只要在 models/index.ts 中統一 export *，外部使用者只需要記住 一個別名 @models，不必關心實際檔名。

---

範例 4：搭配 Webpack 別名（前端專案）

// webpack.config.js
const path = require('path');

module.exports = {
  // ...
  resolve: {
    alias: {
      '@utils': path.resolve(__dirname, 'src/utils/'),          // 與 tsconfig 同步
      '@components': path.resolve(__dirname, 'src/components/')
    },
    extensions: ['.ts', '.tsx', '.js', '.json']
  },
  module: {
    rules: [
      {
        test: /\.tsx?$/,
        use: 'ts-loader',
        exclude: /node_modules/
      }
    ]
  }
};

提醒：tsconfig.json 與 webpack.config.js 必須保持 一致，否則編譯通過但執行時會找不到模組。

---

範例 5：Node.js 原生 ES 模組（ts-node）

// tsconfig.json
{
  "compilerOptions": {
    "module": "ESNext",
    "target": "ES2022",
    "baseUrl": "./src",
    "paths": {
      "@services/*": ["services/*"]
    }
  },
  "typeAcquisition": {
    "enable": true
  }
}

// src/services/logger.ts
export function log(msg: string) {
  console.log(`[LOG] ${msg}`);
}

// src/main.ts
import { log } from '@services/logger';

log('Server started');

使用 ts-node 執行：

npx ts-node src/main.ts

重點：Node.js 原生 ES 模組需要在 package.json 中設定 "type": "module"，且 ts-node 會自動參考 tsconfig.json 的 paths。

---

常見陷阱與最佳實踐

陷阱	說明	解決方式 / 最佳實踐
別名與實體路徑不一致	只在 tsconfig.json 設定別名，卻忘了在 bundler（Webpack、Vite）同步設定，導致執行時找不到模組。	同步設定：在專案根目錄維護一份 alias.config.js，兩側皆引用。
使用相對路徑的混用	在同一檔案內同時使用 ../../utils 與 @utils，會讓團隊成員混淆。	統一規範：新檔案建立時，強制使用別名；舊檔案可透過腳本自動轉換。
paths 的萬用字元不對稱	@components/*: ["components/*"] 正確；若寫成 @components/*: ["components"]，會導致解析失敗。	遵循語法：* 必須同時出現在左、右兩側，或完全不使用。
別名衝突	多個別名指向相同目錄，或不同別名指向同一檔案，會造成 IDE 警告或執行時不確定性。	唯一性：在 paths 中保持別名唯一，必要時使用更具語意的前綴（如 @ui/*、@api/*）。
測試環境未套用別名	Jest、Mocha 等測試框架不自動讀取 tsconfig.json 的 paths，導致測試失敗。	設定映射：在 jest.config.js 中使用 moduleNameMapper 與 ts-jest 的 pathsToModuleNameMapper。

建議的最佳實踐

1. 將 baseUrl 設為 src，讓所有別名都以專案根目錄為基礎，避免 ../。
2. 在 package.json 中加入 "_moduleAliases"（若使用 module-alias 套件），讓 Node 執行時也能解析。
3. 使用自動化腳本（如 tsc-alias）在編譯後把別名轉成相對路徑，減少部署時的額外設定。
4. 結合 Lint 規則（eslint-plugin-import）檢查別名是否正確，防止拼寫錯誤。
5. 文件化別名清單：在 README 或專案 Wiki 中列出所有別名與說明，降低新成員上手成本。

---

實際應用場景

場景	別名的好處	範例
大型單頁應用（SPA）	跨層級的 UI 元件、服務、工具函式都能以簡短路徑匯入，減少檔案搬移成本。	import { fetchUser } from '@api/user'
微服務前端聚合層	不同子專案共用同一套型別或工具庫，只需在根 tsconfig.json 設定別名，即可在所有子專案共用。	import { Logger } from '@shared/logger'
Node.js 後端專案	服務、模型、資料庫存取層的路徑一致，測試檔案也可使用相同別名，保持測試與程式碼同步。	import { UserModel } from '@models/user'
多語系資源檔	透過別名指向 src/locales，讓語系切換程式碼更簡潔。	import zhTW from '@i18n/zh-TW.json'
開發工具或 CLI	當工具本身需要載入多個內部模組時，別名讓指令列程式碼更易讀。	import { parseArgs } from '@cli/args'

---

總結

• 模組別名 是提升 TypeScript 專案可讀性與維護性的關鍵技巧，特別適用於大型、多人協作的程式碼基底。
• 只要在 tsconfig.json 設定 baseUrl 與 paths，再配合 Bundler（Webpack、Vite）、測試框架、Node 執行環境 同步設定，即可完成完整的別名鏈結。
• 避免常見陷阱（路徑不同步、萬用字元錯誤、測試環境缺少映射）並遵循 最佳實踐（統一規範、文件化、Lint 檢查），能讓別名真正發揮效益。
• 在實務上，別名不只是語法糖，更是架構治理的工具：它讓檔案搬移、重構、跨模組共享變得毫不費力。

掌握了模組別名，你的 TypeScript 專案將變得更乾淨、更易於擴展，也能讓團隊開發流程更加順暢。快把本文的設定範例套用到你的專案中，立即感受開發效率的提升吧！