Git Hooks 自動化守門員 Husky：在 Commit 與 Push 前執行檢查腳本

上一篇介紹了用 ESLint 做程式碼檢查，但 ESLint 終究是靠手動執行，難免會有遺忘的時候，團隊裡的新手也可能在不知情的情況下漏掉這個步驟。 （延伸閱讀：用 ESLint 築起專案第一道護欄，抓出潛在的程式碼地雷 ｜ 套件推薦 01）

隨著專案越來越大，上線與提交前要跑的檢查指令只會越來越多。在頻繁修改與趕進度的情況下，難免會忘記執行；又或者新加入的團隊成員根本不知道有這套檢查流程，等到代碼都推上去甚至部署了，才發現漏掉了好幾項檢查。

今天來介紹一款 Husky 套件，它可以用來管理 Git Hooks。把這整串檢查流程變成「自動化守門員」，讓 Git 在你 commit 或 push 之前先強制跑一遍，不用再靠人腦記憶要做的步驟，徹底杜絕漏跑的風險！

Husky 是什麼？

Husky 是一個管理 Git Hooks 的工具。Git 本身內建一個機制叫做 Git Hooks，簡單說就是「在你執行某個 Git 指令的時候，自動夾帶跑一段腳本」。

你可以把它想成是路障：Git 要往前走之前，先讓你的腳本檢查一遍，通過了才放行。

點擊放大

常見的 hook 有三種守門時機：

• pre-commit（存檔前檢查）：在 git commit 之前觸發。在程式碼存入本地版本紀錄前先做第一道基本檢查（如語法或格式）。
• pre-push（推送前把關）：在 git push 之前觸發。在程式碼推送到遠端伺服器（例如 GitHub）前做最後的大關卡檢驗（如資安稽核或測試）。
• commit-msg（訊息格式檢查）：在輸入 commit 訊息後觸發。通常用來檢查提交訊息是否符合團隊規範（例如 feat:、fix:）。

這些 hook 腳本原本要自己去 .git/hooks/ 資料夾手動建立，而且不會被 Git 追蹤，換一台電腦就要重設。Husky 解決了這個問題，讓你把 hook 設定放進專案裡，所有人 clone 下來就能用。

如何在專案中設定 Husky？

設定非常輕量，短短三分鐘內就能完成建置。

1. 安裝 Husky

npm install --save-dev husky

➜ 執行後的效果：package.json 的 devDependencies 裡會出現 husky 的版本號（例如 "husky": "^9.1.7"），同時 node_modules/husky/ 資料夾也會出現在專案裡。

2. 初始化 Husky

npx husky init

➜ 執行後的效果：專案根目錄會自動產生以下變化：

• 新增 .husky/ 資料夾，並在 .husky/ 裡建立一個預設的 pre-commit 範例檔案。
• package.json 的 scripts 自動加入 "prepare": "husky"，這個腳本的作用是：任何人 npm install 之後，Husky 會自動初始化，不用再手動執行一次 npx husky init。

3. 設定 Hook 指令（請依需求設定）

Hook 檔案本質上就是標準的 Shell 腳本，裡面的檢查指令完全可以根據專案需求自由自訂（任何你在終端機能執行的 npm 腳本或 bash 指令都能放進去）。

💡 以下為小編的設定範例，你可以自由設定！

① 在 pre-commit（本地提交前）

打開自動產生的 .husky/pre-commit，你可以寫入想在 commit 前自動執行的指令，例如：執行輕量的語法檢查與單元測試，確保程式品質且功能正常：

# 1. 執行 ESLint 語法檢查
npm run lint

# 2. 執行單元測試（可依專案腳本調整，如 npm test）
npm run test:unit

• 指令說明：在 commit 之前先跑全專案的 ESLint 語法檢查與測試，只要任一項出錯就會自動阻擋 commit，避免有瑕疵的代碼進入版本控制。
• 執行後的效果：下次執行 git commit 時，終端機會依序執行這些指令，全數通過後才會順利完成提交。

② 在 pre-push（遠端推送前）

在 .husky/ 資料夾裡新增一個名為 pre-push 的檔案，你可以寫入想在 push 前自動執行的指令，例如：執行嚴格的資安稽核檢查：

npm audit --audit-level=high --omit=dev

• --audit-level=high：只有「高風險」以上的漏洞才會阻擋 push，避免低風險雜訊干擾開發。
• --omit=dev：只檢查 production 依賴，開發工具的漏洞不算在內。
• 執行後的效果：下次執行 git push 時，終端機會先出現 npm audit 的掃描結果。如果沒有漏洞，push 正常繼續；如果有高風險漏洞，push 會被阻擋並列出問題清單。

點擊放大

被攔截後該如何修復？

首先要有一個核心觀念：Husky 本身只是一個「在關鍵時間點自動幫你跑指令」的執行工具。它本身不負責定義規則，也不會自動幫你修復代碼。

當提交或推送被 Husky 擋下時，終端機跳出的其實是底層檢查工具的報錯訊息：

• 如果是 pre-commit 報錯：代表程式碼違反了專案設定的 ESLint 語法規範，或是沒有通過現有的單元測試（Test Cases）。請根據終端機的行數提示，回到原始碼修正語法或修復破掉的業務邏輯測試。
• 如果是 pre-push 報錯：代表專案依賴包含了高風險漏洞，可透過 npm audit fix 升級套件，或評估更新依賴版本。

小結

Husky 本身並不複雜，安裝只需兩行指令，設定也都透明地記錄在專案檔案中。它的核心價值在於把「本來只能靠人腦記憶手動執行的零散指令」，變成「每次 commit 與 push 時由系統自動強制執行的品質守衛牆」，讓語法把關與資安稽核從可有可無的建議，變成不可妥協的標準流程。