生活分享
Claude Code|只處理變更檔案的格式化 Hook
限制格式化範圍並避免事件重複執行。格式化 Hook 如果每次都掃描整個專案,可能改到與任務無關的檔案。本篇只處理 Write 或 Edit 剛完成的 JSON 練習檔,檢查路徑、解析內容,再在有必要時寫回。你會用連續重播確認第二次不再產生變更,也會驗證失敗時原始資料仍保留。
閱讀時間約 7 分鐘

本篇目錄
格式化 Hook 如果每次都掃描整個專案,可能改到與任務無關的檔案。本篇只處理 Write 或 Edit 剛完成的 JSON 練習檔,檢查路徑、解析內容,再在有必要時寫回。你會用連續重播確認第二次不再產生變更,也會驗證失敗時原始資料仍保留。
先讀Hook 入門Claude Code|建立第一個 Hook設定事件與條件,確認 Hook 實際觸發。本篇會建立第一個 Hook:Claude 使用檔案編輯工具後,將事件名稱與工具名稱寫入練習專案的本機紀錄。你會先人工測試腳本,再接上 PostToolUse,最後用真實編輯確認觸發。這個起點能分清楚「程式可跑」與「Claude 真的呼叫過它」。閱讀全文與事件實驗Claude Code|讀懂 Hook 事件:輸入、輸出與退出碼建立可重播事件的本機測試工具。Hook 教學最容易卡住的地方,常常不是腳本語法,而是沒有分清楚誰送入事件、腳本讀到什麼,以及輸出會由誰解讀。本篇建立一個能重播事件的小實驗室,先用固定 JSON 驗證腳本,再接到 Claude 的實際事件。最後你會有正常、拒絕、輸入錯誤及診斷訊息四種可辨認結果。閱讀全文。下載第 74 篇材料,在 starter 操作。需要 Node.js 22 以上;離線重播不需 Claude 帳號,真實觸發另需登入。閱讀約 20 分鐘,練習約 45 分鐘。
明確限制會改動的檔案
閱讀完整文字說明
只處理變更檔案的格式化 Hook,以流程和文件圖形呈現教學重點。
本篇只接受練習目錄內 fixtures 下、副檔名為 .json 的實際檔案。事件必須是 PostToolUse,表示工具操作已完成。這個 Hook 不掃描其他 JSON,不格式化 JavaScript,也不碰 package-lock.json。範圍越清楚,越容易驗證格式化沒有造成額外變更。
材料的 hooks/format-json.mjs 先讀事件,再用 boundary.mjs 解析真正路徑,最後檢查相對位置。確認條件後才讀檔並 JSON.parse。這與拿到 file_path 就直接拼成一段格式化命令不同;本課不把事件資料當成 shell 程式碼。
JSON 格式化也不能用「把多個空白換成一個」這類文字替換。字串內容可能真的需要連續空白,像是地址、程式片段或使用者文字。必須先解析資料,再序列化成固定縮排,才能保留字串值的意義。此方法可能調整表面排版,但不應改變解析後的資料。
準備能看出差異的輸入
在 fixtures/demo.json 寫入一行壓縮 JSON,字串刻意保留兩個空白,另加一個陣列。先複製這個原始內容到不會被 Hook 處理的筆記,稍後才能比較。材料的 post-edit.json 指向 fixtures/demo.json,請核對事件內容與實際檔案相符。
{"title":"保留 兩個空白","items":[1,2,3]}
{
"hook_event_name": "PostToolUse",
"tool_name": "Edit",
"session_id": "lab-74",
"tool_input": {"file_path": "fixtures/demo.json"}
}
這份 JSON 是手工建立的事件,不是 Claude 真的執行過 Edit 的紀錄。重播器會補上你目前的工作目錄,再把資料送入腳本。這讓你能先測函式與檔案處理,但不能據此宣稱 Hook 已被 Claude 載入。
重播兩次,驗證冪等性
先執行重播,預期 demo.json 變成兩格縮排、結尾保留換行。第二次再送入相同事件,檔案內容應完全相同。這種重複執行不造成額外效果的性質叫冪等性,對可能收到相同事件的自動化很有用。
node hooks/replay.mjs format-json fixtures/post-edit.json
node hooks/replay.mjs format-json fixtures/post-edit.json
node --test tests/hooks.test.mjs
不只看編輯器覺得排版一樣,還要比較內容或雜湊。測試會檢查重複處理後位元組沒有改變,以及 title 裡的兩個空白仍保留。若你的版本每次都改動結尾,或改壞字串內容,即使 JSON 還能解析,也沒有通過本篇判準。
若要使用真正格式化工具處理 JavaScript,先另外確認工具及專案設定,不要把這個 JSON 範例直接套到所有檔案。不同語言的註解、尾逗號與語法規則不同。JSON.parse 不支援的 JSONC,也不能當成一般 JSON 無聲覆寫。
接到實際 PostToolUse 事件
先保存既有 .claude/settings.json,再合併下方 hooks 欄位。matcher 只匹配 Write 與 Edit,腳本本身仍會檢查路徑與副檔名。設定外層條件和程式內層條件都要存在,因為離線重播或未來調整設定時,不能只靠其中一層假設輸入永遠正確。
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [{"type": "command", "command": "node hooks/format-json.mjs", "timeout": 10}]
}
]
}
}
另開 Claude,要求只把 fixtures/demo.json 改成另一份壓縮 JSON。觀察原工具完成後的 Hook 紀錄,再讀檔確認排版。記錄實際事件、腳本退出狀態及最後檔案差異,不要只看模型說「已自動格式化」。
Hook 內的檔案寫入不是同一次 Claude Write 工具呼叫的原始內容。審查差異時應把工具修改與格式化造成的排版都算進最終結果。若需要復原,要另外檢查 Git 差異;不能把 PostToolUse 想成能撤回之前已完成的操作。
故障一:JSON 損壞
把 demo.json 最後的大括號刪掉,先保存這個故障版本的內容,再重播事件。預期腳本回報 JSON formatting failed,原始檔案維持不變。因為解析在寫入前完成,失敗不應把檔案清空或寫成部分結果。
本課把錯誤放進 PostToolUse 的 additionalContext,讓 Claude 知道格式化沒有完成;這不是 PreToolUse 的拒絕決定。主工具已經改過檔案,因此你還需要修復 JSON、重跑驗證,再確認結果。若只忽略訊息,下一步讀取仍會遇到壞資料。
不要自動「修好」任意不合法 JSON 再覆蓋原檔。缺括號可能容易猜,但缺少字串內容或數值時沒有唯一答案。讓錯誤可見並保留原始輸入,比產生一份看似能解析卻改變意思的資料更容易追查。
故障二:路徑或檔案類型不符合
把事件改成指向 model.js,重播後應不修改該檔;改成練習目錄外的專用假路徑,應得到邊界錯誤。用檔案雜湊比較前後結果,不能只因腳本沒有印東西就推定一切正常。沒有匹配目標與執行失敗是兩種不同結果。
| 案例 | 預期檔案結果 | 預期說明 |
|---|---|---|
| 合法 fixtures JSON | 固定排版且資料不變 | 完成處理 |
| 第二次相同事件 | 位元組不再改變 | 冪等 |
| 損壞 JSON | 保留原始故障內容 | 回報解析錯誤 |
| JavaScript 檔案 | 不修改 | 不在處理範圍 |
| 界外路徑 | 不讀寫界外檔案 | 回報範圍錯誤 |
若資料夾或檔名包含中文與空格,先用重播器驗證,再做真實 Hook 觸發。程式能處理路徑不代表 shell 設定一定正確;可接續可攜性與恢復Claude Code|跨平台 Hooks:中文路徑、逾時與遞迴排錯把 Hook 做成可測試、可停用、可移植的工具。Hook 在作者的資料夾能跑,不代表移到中文路徑、另一個 shell 或不同作業系統也正常。本篇建立一張環境矩陣,檢查路徑、編碼、換行、逾時與重複事件,最後寫出能停止並恢復正常工作的操作手冊。閱讀全文比較各環境。這份程式也不承諾能防止其他程序同時改動同一檔案,併發寫入需要另外設計。
避免格式工具把無關檔案一起改掉
格式化前後比較目標檔案的內容和修改清單。漂亮的 JSON 縮排只證明格式轉換成功,若其他檔案也被修改,仍不符合本課範圍。把處理目標限制在事件提供的單一檔案,並在執行前核對目錄與副檔名。
遇到無效 JSON 時保留原檔,回報解析失敗的位置,由使用者或後續修正流程處理。不要為了讓格式工具成功而自動刪除無法解析的片段,這可能改變資料意義。
停用與完成判準
停止本次 Hook 時,只移除自己加入的 PostToolUse 項目或恢復先前備份,再建立新工作階段確認沒有新的格式化觸發。保留 demo.json 與兩輪比較結果作為證據,不必刪除整個 .claude 目錄。若其他 Hook 仍在工作,確認來源再處理。
完成應有合法、重複、損壞、錯類型與界外路徑五種案例,以及至少一次實際 Claude 觸發紀錄。未登入時可以完成離線部分,但真實事件欄位要保持待測。小練習是加入一個陣列頂層 JSON,確認程式依資料格式處理,而不是只接受你第一次示範的物件形狀。
下一步可把格式化與品質檢查 HookClaude Code|建立可停止的品質檢查 Hook讓完成檢查能指出失敗並有清楚的退出機制。測試沒有通過時,Claude 應知道工作還有問題;但如果 Hook 每次都阻止結束,又可能陷入不停重試。本篇建立有次數邊界的 Stop 檢查,第一次失敗回報原因,重複觸發時停止遞迴,並把尚未完成的結果清楚交回讀者。閱讀全文分開:格式化整理已改檔案,品質檢查判斷測試結果,各自保存證據與失敗處理,避免一個事件腳本同時承擔所有任務。
回 Claude Code 教學總目錄Claude Code 完整教學目錄:從入門到自動化依平台、程度與功能找到需要的教學,從 96 篇文章與共用練習專案逐步完成操作。這個教學中心把 Claude Code 分成 96 個可以獨立閱讀的小題目,從桌面、CLI、網頁與手機開始,再學 MD 規則、常用指令、Skills、MCP 與自動化。你可以依推薦路線循序學習,也可以直接搜尋正在遇到的功能、命令或檔名。目錄依目前公開狀態顯示可閱讀文章。閱讀全文
覺得這篇整理實用嗎?分享給需要的朋友
同主題延伸閱讀
生活分享
Claude Code|建立第一個 mod:在 Claude Code 行程內數工具呼叫
寫一個三檔案的 mod,用驗證器與測試確認它掛上的事件。文件把 mod 定義成多了入口檔的 plugin:入口檔叫 hooks module,Claude Code 在事件發生時呼叫裡面的函式,函式可以觀察、改寫或接手事件。
生活分享
Claude Code|Git Worktree 平行工作
隔離多個任務的檔案與分支。Git Worktree 讓同一儲存庫擁有多個工作目錄,各自使用分支與檔案。本篇會把待辦篩選與文件整理分開,確認兩個 session 不會直接改到彼此的檔案,再把其中一個成果整合回主分支。你也會知道何時可以安全清理工作目錄。
生活分享
Claude Code|雙 Worktree 實作與衝突整合
隔離兩項功能,最後完成整合與回歸。兩個 Claude 工作階段同時編輯專案,最容易出現的問題是互相改到同一份檔案,或各自測試通過、整合後卻失敗。本篇用兩個 Worktree 分別處理篩選預設值與介面文字,故意製造一次小衝突,再完成整合、驗證與清理。你不需要先啟用 Agent Teams。
生活分享
Claude Code|比較流程品質、用量與執行時間
以同一資料集比較兩種工作方法。比較兩種 Claude 工作方法時,不能只挑成功那一次,也不能只看第一個答案有多快。本篇用固定案例、原始紀錄和一致判準,比較品質、重試、等待與人工整合時間,最後寫出有樣本數與限制的報告,而不是保證某個方法一定省錢。