本文 AI 產出，尚未審核

TypeScript — 編譯與建構工具整合

主題：Prettier 整合

簡介

在現代前端開發中，程式碼風格的一致性不僅能提升可讀性，還能減少因格式問題而產生的 merge 衝突。
Prettier 是一套「意見統一」的程式碼格式化工具，能自動把程式碼排版成既美觀又符合團隊約定的樣子。對於使用 TypeScript 的專案而言，將 Prettier 與編譯、建構流程緊密結合，能讓 開發者只需專注於邏輯，而不必手動調整縮排、分號或換行。

本篇文章將從概念說明、安裝設定、與常見建構工具（Webpack、Vite、ESLint、Git Hook）整合的實作範例，帶你一步步在 TypeScript 專案中導入 Prettier，並分享避免踩雷的技巧與最佳實踐。

核心概念

1. 為什麼要在 TypeScript 專案中使用 Prettier？

項目 目的
統一程式碼風格 讓所有檔案遵循同一套排版規則，減少閱讀成本
自動化格式化 只要執行一次指令或在 IDE 中保存，即可自動完成排版
降低 Merge 衝突 格式化的差異不會被 Git 認為是功能變更
與 Linter 共存 Prettier 處理「外觀」問題，ESLint 處理「語意」問題，兩者相輔相成

重點：Prettier 不會 取代 TypeScript 的型別檢查或 ESLint 的規則，只是把「程式碼長什麼樣」這件事交給它處理。

2. 安裝 Prettier 與 TypeScript 相容套件

# 基本安裝
npm i -D prettier

# 若要讓 Prettier 能正確解析 .ts/.tsx 檔案，安裝 parser
npm i -D @typescript-eslint/parser

# 若想結合 ESLint（建議做法）
npm i -D eslint-config-prettier eslint-plugin-prettier

Tip：在 monorepo 中，建議在根目錄安裝 Prettier，子套件只需要在 package.json 中設定 prettier 欄位或引用根目錄的設定檔。

3. 建立 Prettier 設定檔

3.1 .prettierrc（JSON 格式）

{
  "printWidth": 100,
  "tabWidth": 2,
  "useTabs": false,
  "semi": true,
  "singleQuote": true,
  "trailingComma": "all",
  "arrowParens": "avoid"
}

3.2 .prettierrc.js（可寫程式碼的設定）

module.exports = {
  // 每行最大長度
  printWidth: 100,
  // 使用 2 個空格縮排
  tabWidth: 2,
  // 加上分號
  semi: true,
  // 使用單引號
  singleQuote: true,
  // 物件、陣列最後一個元素加逗號
  trailingComma: "all",
  // 箭頭函式參數只有一個時省略括號
  arrowParens: "avoid",
};

注意：若專案同時使用 EditorConfig，Prettier 會自動讀取 .editorconfig 中的 indent_style、indent_size 等設定，避免衝突。

4. 與 ESLint 整合

4.1 安裝相關套件（已在上方說明）

npm i -D eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin

4.2 eslint.config.js（或 .eslintrc.js）範例

module.exports = {
  parser: "@typescript-eslint/parser",
  plugins: ["@typescript-eslint", "prettier"],
  extends: [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended",
    // 關閉所有與 Prettier 重疊的規則
    "prettier",
  ],
  rules: {
    // 讓 Prettier 的格式化錯誤顯示為 ESLint 錯誤
    "prettier/prettier": "error",
    // 其他自訂規則
    "@typescript-eslint/no-unused-vars": ["error", { argsIgnorePattern: "^_" }],
  },
};

關鍵："prettier/prettier": "error" 會把 Prettier 格式化的結果當作 ESLint 錯誤回報，讓 CI / Git Hook 能夠阻止未格式化的提交。

5. 在建構工具中使用 Prettier

5.1 Webpack + prettier-webpack-plugin

npm i -D prettier-webpack-plugin

// webpack.config.js
const PrettierPlugin = require("prettier-webpack-plugin");

module.exports = {
  // ... 其他設定
  plugins: [
    new PrettierPlugin({
      extensions: [".ts", ".tsx", ".js", ".jsx"],
      // 若想在打包時自動格式化，可開啟
      // overwrite: true,
    }),
  ],
};

說明：此插件會在每次編譯完成後，把輸出的檔案重新格式化，確保產出檔案（尤其是 dist 中的 .js）保持一致的排版風格。

5.2 Vite + vite-plugin-prettier

npm i -D vite-plugin-prettier

// vite.config.ts
import { defineConfig } from "vite";
import prettier from "vite-plugin-prettier";

export default defineConfig({
  plugins: [
    prettier({
      // 只在開發模式下自動格式化
      apply: "dev",
      // 目標檔案類型
      include: ["src/**/*.ts", "src/**/*.tsx"],
    }),
  ],
});

5.3 npm Script 直接呼叫 Prettier

{
  "scripts": {
    "format": "prettier --write \"src/**/*.{ts,tsx,js,jsx,json,md}\"",
    "format:check": "prettier --check \"src/**/*.{ts,tsx,js,jsx,json,md}\""
  }
}

使用方式

  • npm run format → 一次性把所有檔案格式化
  • npm run format:check → 在 CI 中檢查是否有未格式化的檔案

6. 結合 Git Hook（husky + lint‑staged）

npm i -D husky lint-staged

{
  "husky": {
    "hooks": {
      "pre-commit": "lint-staged"
    }
  },
  "lint-staged": {
    "*.{ts,tsx,js,jsx}": [
      "prettier --write",
      "git add"
    ]
  }
}

流程說明

  1. 開發者 git commit 時，husky 觸發 pre-commit
  2. lint‑staged 找出 staged 的檔案，先交給 Prettier 格式化
  3. 格式化後自動重新加入 staged，確保提交的程式碼已符合格式規範

常見陷阱與最佳實踐

陷阱 說明 解法
Prettier 與 ESLint 規則衝突 例如 semi、quotes 兩套工具同時檢查會產生重複錯誤 在 ESLint extends 中加入 "prettier"，或使用 eslint-config-prettier 完全關閉衝突規則
.prettierignore 設定錯誤 忘記把 node_modules、dist 加入忽略，導致格式化大量不必要檔案 建立 .prettierignore，內容示例：
node_modules/
dist/
*.min.js
不同開發者使用不同的換行符 Windows 與 macOS 的換行符 (CRLF vs LF) 會在 Git 中產生差異 在 .editorconfig 中指定 end_of_line = lf，並在 Prettier 中加上 "endOfLine": "lf"
在大型 monorepo 中重複安裝 每個子套件都安裝 Prettier，會浪費磁碟空間 在根目錄安裝 Prettier，子套件只需在 package.json 中設定 "prettier": "./.prettierrc" 以繼承根設定
格式化失敗時未阻止 CI 只執行 prettier --write，但未檢查結果 在 CI pipeline 中加入 prettier --check，若返回非 0 結束碼則失敗

最佳實踐清單

  1. 一次設定、全局共用：根目錄放置 .prettierrc、.prettierignore、.editorconfig，子套件皆引用。
  2. 把格式化納入 CI：npm run format:check → npm test，確保每次 PR 都通過。
  3. 在 IDE 中啟用「保存時自動格式化」：VS Code 只要安裝 Prettier 外掛，並在 settings.json 加入 "[typescript]": { "editor.formatOnSave": true }。
  4. 結合 lint‑staged：讓開發者在本機提交前就完成格式化，減少 CI 負擔。
  5. 定期審視設定：隨著團隊需求變化，可能要調整 printWidth、trailingComma 等選項，請在每次 major 版本升級時檢視。

實際應用場景

場景一：開源 TypeScript 函式庫

  • 需求：所有貢獻者的程式碼風格必須一致，避免因格式差異產生不必要的 review 討論。
  • 解法：
    1. 在根目錄加入 .prettierrc、.prettierignore。
    2. 使用 husky + lint-staged 強制在 PR 前自動格式化。
    3. CI 中執行 npm run format:check，若失敗即阻止合併。

場景二：企業內部大型前端單頁應用（Vite + TypeScript）

  • 需求：開發者使用不同作業系統，且專案使用 Vite 作為開發伺服器。
  • 解法：
    1. 在 vite.config.ts 中加入 vite-plugin-prettier，在開發模式自動格式化保存的檔案。
    2. 在 settings.json 中設定 editor.formatOnSave，確保本機即時排版。
    3. CI pipeline 內加入 npm run format:check && npm run lint，一次檢查格式與程式碼品質。

場景三：微服務或 Serverless Functions（Node.js + TypeScript）

  • 需求：部署前的打包檔案（.js）需要保持乾淨的排版，方便日後除錯。
  • 解法：
    1. 使用 prettier-webpack-plugin（或在 Webpack output 後使用 prettier-cli）對產出的檔案重新格式化。
    2. 在 package.json 加入 "build": "webpack && npm run format:check"，確保打包結果不會因手動編輯產生格式錯誤。

總結

Prettier 在 TypeScript 專案 中的角色，就是把「程式碼長什麼樣」交給機器自動處理，讓開發者可以把注意力放在 型別安全、業務邏輯 與 測試 上。
透過以下步驟，你即可完成完整的 Prettier 整合：

  1. 安裝 prettier、@typescript-eslint/parser、eslint-config-prettier 等相依套件。
  2. 建立 .prettierrc（或 .prettierrc.js）與 .prettierignore，統一全案排版規則。
  3. 與 ESLint 透過 extends: ["prettier"] 以及 prettier/prettier 規則結合，避免規則衝突。
  4. 在建構工具（Webpack、Vite）或 npm script 中加入自動格式化指令。
  5. 使用 Git Hook（husky + lint‑staged）在 commit 前保證所有檔案已被 Prettier 處理。
  6. 於 CI 加入 prettier --check，讓格式化成為品質門檻的一部份。

只要遵循上述 最佳實踐，即使在大型、多人協作的 TypeScript 專案裡，也能保持程式碼的 乾淨、一致 與 可維護。快把 Prettier 加入你的開發流程，讓程式碼自動變美吧！