Ultra Lab
Claude Code 教學Claude Code hooksClaude CodeAI 開發實戰經驗

Claude Code Hooks 中文設定教學(2026):用 PreToolUse/PostToolUse 自動檢查、自動格式化、擋危險指令

· · 24 分鐘閱讀
目錄
  1. 為什麼要用 hooks?
  2. Claude Code hooks 事件表與基本結構
  3. 設定檔放哪一層
  4. 一個 hook 由三層組成
  5. 實測三段
  6. 實測一:PostToolUse 改完檔自動跑 prettier/black
  7. 實測二:PreToolUse 擋 rm -rf 和 git push --force
  8. 實測三:SessionStart 與 UserPromptSubmit 注入專案規範
  9. 常見錯誤 6 條
  10. 我們自己怎麼用

Claude Code hooks 是你寫在 settings.json 裡、由 Claude Code 在固定時間點自動執行的指令。最常用的三種是:PostToolUse 在 Claude 改完檔案後自動跑 prettier 或 black,PreToolUse 在指令執行前檢查、腳本回 exit 2 就擋下,SessionStart 和 UserPromptSubmit 把專案規範送進 Claude 的 context。

這篇標明「實測」的設定和輸出,是我們 2026 年 11 月 8 日在一台 Windows 10 電腦上(Git Bash、Claude Code 2.1.285)實際跑過的;其餘照 Claude Code 官方 hooks 文件寫,文中會標出來。官方文件描述的版本比 2.1.285 新(文件裡提到 2.1.309),標「照官方文件」的項目沒有在 2.1.285 上逐項驗過,以你自己 claude --version 的版本和文件為準。實測在一個新開的空資料夾裡做,用 claude -p --setting-sources project 只載入那個資料夾的設定,沒有動到任何正式專案。還沒裝 Claude Code 的話,先看 Claude Code 實戰教學把環境弄好。

為什麼要用 hooks?

Claude Code hooks 解決的是「希望每次都發生、但不想靠 Claude 記得」的事。你可以在 CLAUDE.md 寫「改完檔要跑 prettier」,Claude 多半會照做,但不保證每次都做。官方文件對 hooks 的定義是:使用者自訂的 shell 指令,在 Claude Code 生命週期的特定時間點執行,讓某些動作一定發生,而不是交給模型決定。

所以分工很清楚:規則和說明寫在 CLAUDE.md,一定要發生的動作交給 hook。格式化、擋危險指令、記錄每一條指令、在發文前檢查內容,都是 hook 擅長的事。

Claude Code hooks 事件表與基本結構

Claude Code hooks 有 30 多個事件,入門最常用的是下面 8 個,其中 PreToolUse、UserPromptSubmit、Stop 能擋下動作,PostToolUse 不能:

事件 什麼時候觸發 能不能擋
SessionStart session 開始或恢復時 不能,stdout 會進 context
UserPromptSubmit 你送出提示、Claude 處理之前 能,擋下的提示不會送到 Claude
PreToolUse 工具呼叫執行前 能,擋下這次工具呼叫
PermissionRequest 工具呼叫需要權限決定時 用 JSON 決定,不看 exit 2
PostToolUse 工具呼叫成功之後 不能,工具已經跑完
Notification Claude Code 發出通知時 不能
Stop Claude 回應結束時 能,讓 Claude 繼續做
SessionEnd session 結束時 不能

「能不能擋」一欄來自官方的 exit code 2 對照表。

設定檔放哪一層

Claude Code hooks 寫在 settings.json 的 hooks 物件裡,可以放在使用者、專案、local 三層,放在哪一層決定誰會用到,三層的 hooks 會合併執行:

位置 範圍 能不能共用
~/.claude/settings.json 你的所有專案 不能,只在你的電腦
.claude/settings.json 單一專案 能,可以進版控
.claude/settings.local.json 單一專案 不能,只給你自己

另外還有組織的 managed 設定、plugin、skill 和 subagent 的 frontmatter 也能帶 hooks,這篇不展開。

一個 hook 由三層組成

Claude Code 的每個 hook 由三層巢狀組成:事件(例如 PreToolUse)→ matcher(例如只看 Bash 工具)→ handler(要跑的指令)。事件觸發時,Claude Code 把一段 JSON 從 stdin 傳給你的指令,裡面有 session_id、cwd、hook_event_name,工具類事件還有 tool_name 和 tool_input。你的指令用 exit code 回話:

  • exit 0:沒有意見。對 PreToolUse 來說不等於允許,工具照樣走一般權限流程。
  • exit 2:擋下。stderr 的內容會當成原因回給 Claude(或顯示給你,依事件而定)。
  • 其他 exit code:大多數事件會當成「不擋的錯誤」,動作照樣執行。

實測三段

Claude Code hooks 最常用的三種用法是改完檔自動格式化、擋危險指令、注入專案規範,我們在 Claude Code 2.1.285 上三種都實測過。三段都在同一個 .claude/settings.json 裡,hook 腳本用 node 寫,因為這台 Windows 沒裝官方範例用的 jq。

實測一:PostToolUse 改完檔自動跑 prettier/black

PostToolUse 配 Edit|Write 的 matcher,會在 Claude 每次用 Edit 或 Write 改完檔案後執行。設定:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/format.js\"", "timeout": 60 }
        ]
      }
    ]
  }
}

format.js 從 stdin 讀 tool_input.file_path,.js、.ts 這類檔案跑 prettier,.py 跑 black:

const { execSync } = require("child_process");
let raw = "";
process.stdin.on("data", (c) => (raw += c));
process.stdin.on("end", () => {
  const file = JSON.parse(raw).tool_input?.file_path || "";
  let cmd = "";
  if (/\.(js|ts|jsx|tsx|json|css|md)$/.test(file)) cmd = `npx --yes prettier@3 --write "${file}"`;
  else if (/\.py$/.test(file)) cmd = `black -q "${file}"`;
  if (!cmd) process.exit(0);
  try {
    execSync(cmd, { stdio: ["ignore", "ignore", "pipe"] });
    process.exit(0);
  } catch (e) {
    process.stderr.write(`格式化失敗:${file}\n${e.stderr || e.message}`);
    process.exit(2); // PostToolUse 回 2:檔案已改,把錯誤丟回給 Claude
  }
});

實測時我們故意要 Claude 用單引號、不加分號、add(a,b,c=0) 不加空格。Claude 的 Edit 確實照這樣寫,hook 跑完後檔案變成:

const bye = (name) => {
  return "bye " + name;
};
def add(a, b, c=0):
    return a + b + c

hook 成功時對話裡不會出現任何訊息,這跟官方文件說的一樣。有趣的是 Claude 自己察覺了:它回報「Edit 之後有 hook 改動了這兩個檔案,可能是 formatter」,改回原寫法一次又被排版,就停下來說明,沒有一直重試。在這次實測裡,格式化 hook 跟提示衝突時,留下來的是 hook 排版的結果。

實測二:PreToolUse 擋 rm -rf 和 git push --force

PreToolUse 配 Bash matcher,可以在每條 shell 指令執行前檢查內容,回 exit 2 就擋下。設定:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/guard.js\"" }
        ]
      }
    ]
  }
}

guard.js:

let raw = "";
process.stdin.on("data", (c) => (raw += c));
process.stdin.on("end", () => {
  const cmd = JSON.parse(raw).tool_input?.command || "";
  const rules = [
    [/\brm\s+-[a-zA-Z]*r[a-zA-Z]*f|\brm\s+-[a-zA-Z]*f[a-zA-Z]*r/, "rm -rf"],
    [/\bgit\s+push\b.*(--force\b|--force-with-lease\b|\s-f\b)/, "git push --force"],
  ];
  for (const [re, name] of rules) {
    if (re.test(cmd)) {
      process.stderr.write(`已擋下:這個專案不允許 ${name}。需要的話請使用者自己在終端機執行。\n`);
      process.exit(2);
    }
  }
  process.exit(0);
});

上線前先照官方建議,用 echo 餵一段 JSON 手動測,rm -rf build 和 git push -f 都回 2,ls -la 回 0。接著叫 Claude 執行 rm -rf build 和 git push --force origin master,Claude 收到的工具結果是(實測):

PreToolUse:Bash hook error: [node "$CLAUDE_PROJECT_DIR/.claude/hooks/guard.js"]: 已擋下:這個專案不允許 rm -rf。需要的話請使用者自己在終端機執行。
PreToolUse:Bash hook error: [node "$CLAUDE_PROJECT_DIR/.claude/hooks/guard.js"]: 已擋下:這個專案不允許 git push --force。需要的話請使用者自己在終端機執行。

build 資料夾還在,Claude 回報兩個指令都被 hook 擋下、沒有執行。官方文件另外寫明,hook 回的 deny 在 bypassPermissions 模式下也有效。

要誠實說的是,這種字串比對擋不住所有寫法:我們手動測 rm -r -f build,guard.js 回 0,沒擋。hook 適合擋常見的手滑。權限設定的 deny 規則(例如在 permissions.deny 寫 Bash(rm *))可以再加一層,但官方文件說明這類規則也只擋 Claude 平常寫出的形式,/bin/rm -rf build/ 和 bash -c 'rm -rf build/' 就擋不住,它不是安全邊界。要不依賴指令文字的限制,官方建議用 sandboxing。

實測三:SessionStart 與 UserPromptSubmit 注入專案規範

SessionStart 和 UserPromptSubmit 在 exit 0 時,stdout 會進 Claude 的 context,適合放「這個專案現在的狀態」。設定:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          { "type": "command", "command": "echo '專案規範:這個 repo 用 pnpm,不用 npm;commit 前要跑 pnpm test。'" }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          { "type": "command", "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/ctx.js\"" }
        ]
      }
    ]
  }
}

ctx.js 每次送出提示時讀目前分支,用 JSON 的 additionalContext 送進去:

const { execSync } = require("child_process");
const branch = execSync("git branch --show-current").toString().trim();
console.log(JSON.stringify({
  hookSpecificOutput: {
    hookEventName: "UserPromptSubmit",
    additionalContext: `目前分支是 ${branch}。這個 repo 週五前不部署正式站。`,
  },
}));

我們叫 Claude 不用任何工具,回答「用哪個套件管理器、有沒有部署限制」。它答 pnpm,並說「有,週五前不部署正式站。這是 UserPromptSubmit hook 說的」(實測)。官方建議注入的文字寫成陳述句(「這個 repo 用 pnpm」),不要寫成像系統命令的口氣,否則可能被 Claude 當成提示注入。

常見錯誤 6 條

Claude Code hooks 設定錯了多半不會報錯,只是安靜地沒生效,下面 6 條裡有 4 條是我們實際重現過的。

1. matcher 大小寫寫錯(實測)。 官方文件寫明 matcher 區分大小寫。我們把 "Bash" 改成 "bash",同樣叫 Claude 跑 rm -rf build,hook 完全沒觸發,build 被刪掉,debug log 裡一筆 PreToolUse 紀錄都沒有。另外官方文件說明,UserPromptSubmit、Stop 這類事件不支援 matcher,寫了會被直接忽略。

2. 腳本沒執行權限、Windows 路徑(照官方文件+實測)。 在 macOS 和 Linux,hook 腳本要先 chmod +x。出現 command not found 時,官方建議用絕對路徑或 $CLAUDE_PROJECT_DIR,shell 形式要加雙引號。Windows 上 hook 預設用 Git Bash 執行,沒有 Git Bash 才用 PowerShell。我們實測 Windows 傳進來的 file_path 是反斜線路徑,官方的 protect-files 範例也先把反斜線轉成斜線再比對。

3. 用 exit 1 想擋卻沒擋(實測)。 這是最危險的一條。我們把 guard.js 的 exit(2) 改成 exit(1),debug log 記下 status code 1,但指令照跑、build 被刪,Claude 也沒看到任何訊息。官方文件特別警告:exit 1 雖然是 Unix 慣用的失敗碼,在 hook 裡是不擋的錯誤,要擋一定用 exit 2。

4. JSON 欄位放錯層(實測)。 additionalContext 和 permissionDecision(後者照官方文件)都要包在 hookSpecificOutput 裡。我們把 additionalContext 放到最外層,Claude 答「部署限制:不知道」,對話裡沒有任何錯誤;只有 debug log 寫著 Hook JSON output had unrecognized keys (ignored): additionalContext。另外 stdout 開頭不是 { 會被當純文字,shell profile 裡無條件的 echo 就會造成這個問題。

5. 搞錯設定層級(照官方文件)。 hooks 跨層是合併的,使用者、專案、local 三層各自的 hook 都會跑,不會互相覆蓋。disableAllHooks 則照設定優先序取值,所以專案設定的 false 會蓋過你使用者層的 true。還有一點要小心:互動模式下要先信任資料夾,hooks 才會跑;用 claude -p 時則一律當成已信任,clone 來的 repo 裡的 hooks 會直接執行,對陌生 repo 跑 -p 前先看過它的 .claude/ 設定。

6. hook 太慢(實測+官方文件)。 實測一的 debug log 出現 Slow PostToolUse hooks: 7769ms for Edit,第一次 npx --yes prettier@3 要下載套件。我們另外計時,npx --yes prettier@3 每次約 2.6 到 2.8 秒,在專案裡安裝 prettier 後直接用 node 執行約 0.3 秒。官方文件的預設逾時是 command hook 10 分鐘、UserPromptSubmit 30 秒;PreToolUse hook 逾時不會擋下工具呼叫,所以別讓守門的 hook 跑太久。要逾時或失敗就擋,官方提供 "onFailure": "block",但需要 Claude Code 2.1.295 以後,我們這台 2.1.285 還沒有。

不確定 hook 有沒有跑,打 /hooks 看有沒有列在對的事件底下,或用 claude --debug 開 debug log 看實際的 exit code 和輸出。

我們自己怎麼用

Claude Code hooks 的 matcher 也能比對 MCP 工具,MCP 工具名稱的格式是 mcp__伺服器__工具,所以接了 MCP server 之後,可以在 Claude 呼叫特定工具前先跑你自己的檢查。MCP 怎麼接,見上週的 Claude Code 接 MCP server 中文設定教學。

我們用自家的 MindThread MCP 試了一次發文前檢查(實測):matcher 寫 mcp__mindthread__publish|mcp__mindthread__schedule_text,腳本看到內文有「保證獲利」就 exit 2。Claude 呼叫 publish 時收到 已擋下:貼文含禁用詞「保證獲利」,請改寫後再送。,請求在送到伺服器前就停了。這次沒有放金鑰,本來就不會真的發出去。

hooks 管的是 Claude 做的動作;如果你也寫自己的 MCP server 或系統提示詞,系統提示詞和工具描述可以交給我們開源的 UltraProbe 做靜態檢查,它比對你貼上的文字,不呼叫模型,也不掃描 MCP server 本身。

常見問題

Claude Code 的 hooks 要寫在哪個設定檔?

看你要給誰用。只給自己、所有專案都要的,寫在 ~/.claude/settings.json;整個團隊都要的,寫在專案的 .claude/settings.json 並進版控;只給自己、只在這個專案用的,寫在 .claude/settings.local.json。三層的 hooks 會合併執行,不會互相覆蓋。改完設定通常不用重開,Claude Code 會自動重新載入,可以打 /hooks 確認有沒有讀到。

PreToolUse hook 回 exit 0 是不是代表允許執行?

不是。官方文件寫明 exit 0 代表「沒有意見」,工具呼叫照樣走一般的權限流程,該問你的還是會問。要擋就回 exit 2 並把原因寫到 stderr;要跳過權限提示,得 exit 0 並在 stdout 印出 permissionDecision 為 allow 的 JSON,而且設定檔裡的 deny 規則仍然有效。反過來,hook 回的 deny 在 bypassPermissions 模式下也擋得住。

Claude Code hooks 在 Windows 上能用嗎?

能。官方文件說明 Windows 上的 hook 指令預設用 Git Bash 執行,沒裝 Git Bash 才改用 PowerShell,也可以在單一 hook 設 "shell": "powershell"。我們在 Windows 10 的 Git Bash 下實測,hook 腳本用 node 寫、不依賴 jq,三段都跑得起來。要注意 Windows 上 tool_input.file_path 是反斜線路徑,腳本比對路徑前要先處理。

hooks 跟 CLAUDE.md 差在哪?什麼時候該用哪個?

CLAUDE.md 是寫給 Claude 看的說明,Claude 會參考但不保證每次照做;hook 是 Claude Code 在固定時間點一定會執行的指令,不靠模型決定。官方建議固定不變的專案規範放 CLAUDE.md,需要每次都發生的動作(格式化、擋指令、記錄)或需要跑程式才拿得到的動態資訊(目前分支、CI 結果)才用 hook。

想自己動手試試?

UltraProbe 免費、免註冊,掃一次網站就知道 Google 與 AI 找不找得到你。

ULTRA LAB 週報

每週一,GitHub 前十+一件學到的事

每個工具都標清楚能不能商用、適合誰。卡關了可以到 Discord 問。

只用來寄週報,不會給別人;每封都能一鍵退訂。

加入 Discord