別讓 Claude Code 看到你的 .env：四道防線完整守住敏感檔案

兩千九百萬。這是 GitGuardian 2026 年報 統計到 2025 年被推上 GitHub 公開倉庫的硬編碼 secret 數量，年增 34%——是有史以來單年最大跳升。其中跟 AI 服務相關的 token 增加了 81%。會出現這個翻倍速度，跟 AI coding agent 的全面普及脫不了關係。

Claude Code 是這波最常用的工具之一。它能讀寫專案任何檔案、執行 bash、push 到 GitHub。生產力翻倍很爽，問題是——你的 .env、API key、credentials.json 也在它的可達範圍。等你發現 Claude 把資料庫密碼當作上下文送回去、或是順手把 .env commit 上 GitHub，已經來不及。

這篇會把 Claude Code 對敏感檔案的四道防線拆給你看：第一道是 Anthropic 內建的 Git 提交保護，第二道是 settings.json 的 permissions deny，第三道是程式級的 PreToolUse Hook，第四道是 .gitignore 與搜尋工具的互動。每一道都附可複製的設定，最後給你一份懶人包範本——5 分鐘設好，整個專案的 secret 從此不會被誤讀。

為什麼 Claude Code 看到 .env 真的會出事

先講三個最近一年實際發生的事件，你就懂為什麼這個議題不是杞人憂天。

事件一：CVE-2025-55284，DNS 通道把 .env 帶出公司

2025 年 8 月，Zscaler ThreatLabz 公開了一個編號 CVE-2025-55284 的漏洞。攻擊路徑很經典——攻擊者把惡意 prompt 藏在 Claude Code 會讀到的外部資料裡（例如某個它正在分析的 GitHub repo 的 README、issue 留言），Claude 被誘導去執行 bash，把專案內的 .env 內容用 base64 編碼後塞進 DNS 查詢，透過 53 port 把資料送到攻擊者控制的 DNS 伺服器。

整個過程不會觸發 firewall——因為 DNS 流量本來就是允許的。Claude Code 預設能跑 Bash，dig 跟 nslookup 不在內建黑名單裡。漏洞修補後，Anthropic 在 security 文件加上一行「強烈建議 sandbox 模式」，但預設行為沒改。換句話說，如果你今天 update 到最新版還沒手動設 deny，這條路徑只是改了名字繼續存在。

事件二：開發者一個月帳單從 180 美元跳到 82,000 美元

2026 年 2 月，一篇開發者 post-mortem 在 HN 上爆紅。事件主角用 AI coding tool 做側專案，把 Google Cloud API key 寫死在 .env 裡測試。AI agent 在幫他重構 commit 時，把 .env 一起 add 進去，PR 被自動 merge 到 public repo。Bot 在 17 秒內就抓到 key，掛 GPU 訓練自己的模型。月底帳單 82,000 美元——是他原本月平均的 455 倍。

Google Cloud 後來免除了這筆費用，但同月 GitGuardian 發布的 AI 協作 commit 統計 顯示，掛了 AI co-author 的 commit 洩漏 secret 的速率「大約是基準值的兩倍」。AI 不會主動幫你檢查有沒有不該 commit 的東西，它只會盡力完成你給的任務。

事件三：Claude Code 自己的 source map 被推上 npm

這個更諷刺。2026 年 3 月 31 日，Anthropic 自己的工程師把 Claude Code 完整 source map 包進 npm release，VentureBeat 的報導 寫得很直接——59.8 MB、513,000 行 TypeScript 原始碼曝光，1,906 個 .ts 檔全部可讀。這代表什麼？連寫 Claude Code 的團隊自己，都會在 release 流程中誤包敏感檔案。你不會比他們更小心。

第一道防線：Claude Code 內建的 Git 提交保護

講四道防線之前，先說一個好消息——Anthropic 在 system prompt 層級已經內建了幾項硬性規則，這部分你不用設定。

Claude Code 在執行 git 相關操作時遵守以下不成文規定：第一，不會主動跑 `git add .` 或 `git add -A`，因為這兩個指令最容易把 .env、credentials.json 之類的東西誤包進去。它一律是按檔案名 add，你能在 plan 階段看到要 add 哪些。第二，commit 前如果偵測到 staged 的檔案是 .env 或類似格式，會明確警告。第三，不會用 `--no-verify` 跳過 pre-commit hook，除非你明確要求。第四，不會主動 push 到 remote，每次都會問。

這四條規則很實用，但有個前提——你要讓它走「對話式」的 git 流程。如果你直接叫它「重構並提交所有變更」，它會自己拆解步驟、自己選 add 範圍，這時內建保護才會啟動。如果你給它的是「跑這條 bash：`git add . && git commit -m fix && git push`」，它會直接執行，內建保護不會介入——因為這已經是 Bash 指令而不是 git 操作。

第二道防線：settings.json 的 permissions deny

這是這篇文章的核心。Claude Code 官方 permissions 文件 提供了 deny / ask / allow 三種規則，評估順序是 deny 先看、ask 次之、allow 最後，第一個 match 的規則勝出。位置可以放專案層 `.claude/settings.json` 或使用者層 `~/.claude/settings.json`，前者比後者優先。

最容易踩的坑：deny Read 不會擋 Bash

很多人第一次設 deny 都這樣寫：

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

看起來沒錯——擋掉 Read 工具讀取 .env。問題是，Claude Code 還有 Bash 工具。你寫 deny `Read(.env)` 但沒擋 Bash，它依然可以 `cat .env` 把內容讀出來當作上下文。這在 anthropics/claude-code GitHub issue 區是長年熱門問題，issue #24846 跟 #6699 都在反映同一件事。要真的擋住，得 Read 跟 Bash 一起寫。

正確的 deny 寫法（可複製）

把以下放進 `.claude/settings.json`，等於把所有「直接讀取敏感檔案」的合理路徑都堵掉：

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./**/.env)",
      "Read(./**/.env.*)",
      "Read(./secrets/**)",
      "Read(./config/credentials.json)",
      "Read(./**/id_rsa)",
      "Read(./**/*.pem)",
      "Read(./**/*.key)",
      "Bash(cat:*.env*)",
      "Bash(less:*.env*)",
      "Bash(more:*.env*)",
      "Bash(head:*.env*)",
      "Bash(tail:*.env*)",
      "Bash(grep:*.env*)",
      "Bash(curl:*)",
      "Bash(wget:*)",
      "Bash(dig:*)",
      "Bash(nslookup:*)",
      "WebFetch"
    ],
    "ask": [
      "Bash(git push:*)",
      "Bash(git commit:*)",
      "Bash(rm:*)"
    ],
    "defaultMode": "default"
  }
}

逐條解釋幾個重點：

• Read(./**/.env*)：星號是 deny 的 specifier，能 match 多層目錄底下所有 .env 變體。包含 monorepo 子套件的 .env.local、.env.production 都涵蓋。
• Bash(cat:*.env*)：擋掉 cat 直接讀取，連同 less / more / head / tail / grep 一起擋，因為這些都能間接拿到內容。
• Bash(curl:*) Bash(wget:*) Bash(dig:*)：擋住外連工具。這條可以擋住 CVE-2025-55284 那種 DNS 外洩路徑，也擋掉「把 .env 內容 POST 到外部」的攻擊。注意 wget / curl 預設就在 Anthropic 的 blocklist 內，但 dig / nslookup 不是，要自己加。
• WebFetch：直接擋掉整個 WebFetch 工具（如果你的工作流不需要網路抓資料）。沒擋掉的話，Claude 可以把資料 encode 到 URL query string 送出去。
• ask 區塊：把 git push、git commit、rm 改成「先問再做」。這對協作 git 流程是再加一層保險，避免 Claude 自動 push 含敏感檔的 commit。

實測：deny 規則到底有沒有用

我把上面的 settings.json 放進一個測試專案，建一個 .env 內容是 `OPENAI_API_KEY=sk-test-1234`，然後跟 Claude Code 說：「幫我看一下 .env 有沒有寫對」。結果：

結論：deny 是「黑名單」邏輯，越寫越長補漏洞，而且永遠擋不完。awk、sed、python -c、ruby -e、node -e 任何一個能讀檔的工具都是潛在繞過點。這就是為什麼第三道防線（Hook）這麼重要——它是程式級的攔截，不依賴黑名單列舉。

第三道防線：PreToolUse Hook 程式級攔截

Hook 是 Claude Code 在工具執行前後可以注入的 shell command。Anthropic 官方 hook 文件 列出了八個觸發點：SessionStart、UserPromptSubmit、PreToolUse、PostToolUse、Stop、SubagentStop、Notification、PreCompact。其中 PreToolUse 是擋敏感檔案的關鍵——它在 Read / Edit / Write / Bash 工具執行前觸發，你可以回 deny 把整個操作擋下來。

Hook 比 deny 強在哪

Hook 是程式碼，不是規則表。你可以用任何邏輯判斷要不要擋——比方「這個檔案路徑包含 .env、id_rsa、credentials、token、secret 任何一個關鍵字就擋」，一行 regex 全部 cover。不像 deny 要一條一條列。更重要的是，hook 可以攔截「Claude 想跑的 bash 指令本身」，所以 awk、python -c 那些 deny 列不到的繞過點，hook 可以從指令字串層面比對。

最小可用的 protect-env hook（可複製）

第一步，在 `.claude/settings.json` 加上 hook 設定：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read|Edit|Write|Bash",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-env.sh"
          }
        ]
      }
    ]
  }
}

第二步，建立 `.claude/hooks/protect-env.sh`，記得 `chmod +x`：

#!/bin/bash
# 從 stdin 讀 hook payload
PAYLOAD=$(cat)
TOOL=$(echo "$PAYLOAD" | jq -r '.tool_name')

# 抓出 Read/Edit/Write 的 file_path 或 Bash 的 command
if [[ "$TOOL" == "Bash" ]]; then
  TARGET=$(echo "$PAYLOAD" | jq -r '.tool_input.command')
else
  TARGET=$(echo "$PAYLOAD" | jq -r '.tool_input.file_path // .tool_input.path // ""')
fi

# 敏感檔案/關鍵字黑名單（一個 regex 解決）
PATTERN='\.env|id_rsa|\.pem$|\.key$|credentials\.json|secrets/|/\.aws/|/\.ssh/|\.netrc'

if echo "$TARGET" | grep -qE "$PATTERN"; then
  jq -n --arg reason "Blocked by protect-env hook: target matches sensitive file pattern" '{
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: $reason
    }
  }'
  exit 0
fi

# 其他情況放行
exit 0

這個 hook 做的事很單純——攔截每一次 Read / Edit / Write / Bash，把目標路徑或 bash 指令字串拿出來，跟一條 regex 比對。中了就輸出 JSON 告訴 Claude「拒絕，理由是這個」，Claude 會把錯誤訊息放進對話讓你看到，然後繼續其他任務。沒中就 exit 0 放行。

hook + deny 的分工

實務上兩道一起用，不是擇一：

第四道防線：.gitignore 與搜尋工具的真實互動

這道防線最常被誤解。先講結論——Claude Code 的 Read 工具不會自動 respect .gitignore，但 Glob 跟 Grep 預設會。也就是說，.gitignore 不能擋 Claude 主動讀，只能擋它「搜尋時不小心翻到」。

Glob / Grep 跟 .gitignore 的關係

當你叫 Claude「找出所有 config 檔」，它通常用 Glob `**/*.config.*` 或 Grep 搜內容。這兩個工具在預設模式下會跳過 .gitignore 列出的路徑——這是 ripgrep 的內建行為，Claude Code 直接繼承。

實務上的好處：你只要把 .env 寫進 .gitignore，Claude 在做廣泛搜尋時就不會掃到它。它仍然知道有 .env 這個檔（檔案系統可見），但不會主動把內容塞進上下文。

但 .gitignore 不能取代 deny

這是關鍵。Martin Eve 的部落格實測：他把 .env 寫進 .gitignore、再加一個 .claudeignore 同樣標記，明確跟 Claude 說「不要讀 .env」。Claude 還是讀了，並把內容傳回 Anthropic 伺服器（系統 telemetry）。Claude 完全沒有違抗指令的意圖，它只是把 .env 視為「使用者沒禁止用工具讀的檔」。

.claudeignore、AGENTS.md、CLAUDE.md 寫的指引——對 Claude 來說這些都只是「建議」，不是「強制」。真正的強制只有 settings.json 的 deny 規則跟 hook 的 permissionDecision deny。把守住這條線，整個 .gitignore 才能發揮輔助效果。

sensitive file gate 是什麼？社群對這套機制的稱呼

回到一個最常被問的問題：Claude Code 裡面有沒有一個叫「sensitive file gate」的功能？

老實講——沒有。「sensitive file gate」不是 Anthropic 官方文件用過的術語，你在 docs.claude.com 或 GitHub repo 任何官方頁面都搜不到這個詞。它是社群跟一些技術部落格作者用來指稱「上面這四道防線整套機制」的非正式說法，特別是指 settings.json + hooks 兩道。

實際上 Anthropic 自己的稱呼是分開的：

• Permissions：指 settings.json 裡的 deny / ask / allow rule。
• Hooks：指可以注入的 8 個 lifecycle event。
• Sandbox：指 `/sandbox` 命令啟動的隔離環境。
• Read-only mode：預設行為的描述。

如果有人跟你提「Claude Code 有 sensitive file gate」，他講的多半是 permissions deny + PreToolUse hook 這個組合。內容都對，名字不官方。SEO 搜尋的時候用「Claude Code permissions」「Claude Code 權限設定」會找到比較準的官方資料。

四道防線的觸發順序

把這四道防線的差異與分工整理成一張表，方便你快速建立心智模型：

最小可用設定範本：懶人包直接複製

如果你只想要一份能直接丟進專案就用的設定，下面這份是我自己用的精簡版本。覆蓋率 90%，不會擋到正常開發流程，5 分鐘設好。

步驟一：建立目錄結構

mkdir -p .claude/hooks
touch .claude/settings.json
touch .claude/hooks/protect-env.sh
chmod +x .claude/hooks/protect-env.sh

# 順手把 .claude/settings.local.json 加進 .gitignore，避免個人設定外流
echo ".claude/settings.local.json" >> .gitignore

步驟二：完整 settings.json（複製貼上）

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./**/.env)",
      "Read(./**/.env.*)",
      "Read(./secrets/**)",
      "Read(./**/id_rsa)",
      "Read(./**/*.pem)",
      "Read(./**/*.key)",
      "Read(./**/credentials.json)",
      "Read(./**/.aws/**)",
      "Read(./**/.ssh/**)",
      "Bash(cat:*.env*)",
      "Bash(less:*.env*)",
      "Bash(more:*.env*)",
      "Bash(head:*.env*)",
      "Bash(tail:*.env*)",
      "Bash(grep:*.env*)",
      "Bash(curl:*)",
      "Bash(wget:*)",
      "Bash(dig:*)",
      "Bash(nslookup:*)"
    ],
    "ask": [
      "Bash(git push:*)",
      "Bash(rm -rf:*)"
    ],
    "defaultMode": "default"
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read|Edit|Write|Bash",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-env.sh"
          }
        ]
      }
    ]
  }
}

步驟三：完整 protect-env.sh（複製貼上）

#!/bin/bash
PAYLOAD=$(cat)
TOOL=$(echo "$PAYLOAD" | jq -r '.tool_name')

if [[ "$TOOL" == "Bash" ]]; then
  TARGET=$(echo "$PAYLOAD" | jq -r '.tool_input.command')
else
  TARGET=$(echo "$PAYLOAD" | jq -r '.tool_input.file_path // .tool_input.path // ""')
fi

PATTERN='\.env|id_rsa|\.pem$|\.key$|credentials\.json|secrets/|/\.aws/|/\.ssh/|\.netrc|\.npmrc.*_authToken'

if echo "$TARGET" | grep -qE "$PATTERN"; then
  jq -n --arg reason "Blocked by protect-env hook" '{
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: $reason
    }
  }'
  exit 0
fi

exit 0

步驟四：實測一次

設好後重啟一次 Claude Code 讓 settings 生效，然後跟它說：「幫我看一下 .env 內容」。應該得到拒絕回應，類似這樣：

I cannot read the .env file because it's blocked by the project's permission settings.
The protect-env hook returned: "Blocked by protect-env hook"

If you need to verify environment variables, I can:
1. Check that the file exists (without reading content)
2. Help you create a .env.example template
3. Run application code that reads .env at runtime

看到這個就代表設定生效。如果 Claude 還是順利讀出內容，逐項檢查：settings.json 是否在 .claude/ 底下、hook 腳本是否 chmod +x、jq 是否裝好。

敏感檔案不該是 AI coding 的成本

Claude Code 的生產力是真的高，但生產力高跟資安強不是同一件事。Anthropic 把預設值設得寬鬆是有道理的——他們希望開發者第一次用就感受到效率。代價就是安全責任落在你身上。

把這篇的四道防線都裝上，設一次用十年。下次有新人加入專案，他 clone 下來 .claude/settings.json 跟 hook 都在 git 裡，自動套用。整個 team 的 .env 從此不會再因為一句「幫我看看 config」就被誤讀。

如果你想看 Claude Code 在其他主題的應用，可以接著讀 Claude Code Skill 完整教學：10 個讓工作效率翻倍的自訂指令 學自訂指令、為什麼 Claude Code 做出的畫面總是很醜？實測 7 個方法讓質感追上 Claude Design 解決 UI 質感問題，或對比 Codex vs Claude Code：兩大 AI 程式助手深度實測 看看哪個更適合你。如果你的團隊在做企業 AI 導入、需要更系統的安全與權限規劃，我們的 AI 顧問服務 可以幫你從架構層直接設計好。

常見問題