Claude Code Hooks 2026 完整实战指南：6 个生产可用的 Hook 场景，附完整脚本和配置

~/.claude/settings.json              # 全局：所有项目生效
.claude/settings.json                # 项目级：随代码提交，团队共享
.claude/settings.local.json          # 本地：不提交，只对自己生效

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check.sh",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

#!/bin/bash
# .claude/hooks/block-dangerous-commands.sh

INPUT=$(cat)
COMMAND=$(echo"$INPUT" | jq -r '.tool_input.command // empty')

# 定义危险模式（正则匹配）
DANGEROUS_PATTERNS=(
'rm\s+-rf\s+/'           # rm -rf 根目录或绝对路径
'git\s+push\s+.*--force'# force push
'DROP\s+TABLE'           # 删表
'DROP\s+DATABASE'        # 删库
'git\s+reset\s+--hard'   # 丢弃未提交修改
'>\s*/dev/sd'            # 写入磁盘设备
)

for pattern in"${DANGEROUS_PATTERNS[@]}"; do
ifecho"$COMMAND" | grep -iEq "$pattern"; then
    # 退出码 2 = 阻塞性错误，Claude 会收到拒绝通知
    echo"BLOCKED: 命令匹配危险模式 [$pattern]" >&2
    echo"原始命令: $COMMAND" >&2
    exit 2
fi
done

# 通过检查，允许执行
exit 0

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-dangerous-commands.sh",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

#!/bin/bash
# .claude/hooks/protect-sensitive-files.sh

INPUT=$(cat)
FILE_PATH=$(echo"$INPUT" | jq -r '.tool_input.file_path // empty')

# 如果没有文件路径（比如 Bash 命令），直接放行
[ -z "$FILE_PATH" ] && exit 0

# 敏感文件模式
PROTECTED_PATTERNS=(
'\.env$'
'\.env\.'
'credentials'
'secret'
'\.pem$'
'\.key$'
'package-lock\.json$'
'pnpm-lock\.yaml$'
'yarn\.lock$'
'go\.sum$'
)

for pattern in"${PROTECTED_PATTERNS[@]}"; do
ifecho"$FILE_PATH" | grep -iEq "$pattern"; then
    echo"BLOCKED: 不允许修改敏感文件 $FILE_PATH" >&2
    exit 2
fi
done

exit 0

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-sensitive-files.sh",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

#!/bin/bash
# .claude/hooks/auto-lint.sh

INPUT=$(cat)
FILE_PATH=$(echo"$INPUT" | jq -r '.tool_input.file_path // empty')

[ -z "$FILE_PATH" ] && exit 0

# 根据文件类型选择 linter
case"$FILE_PATH"in
  *.js|*.ts|*.jsx|*.tsx)
    RESULT=$(npx eslint --fix "$FILE_PATH" 2>&1) || true
    ;;
  *.py)
    RESULT=$(python -m ruff check --fix "$FILE_PATH" 2>&1) || true
    ;;
  *.go)
    RESULT=$(gofmt -w "$FILE_PATH" 2>&1) || true
    ;;
  *.java)
    # 只检查不修复，把问题反馈给 Claude
    RESULT=$(mvn checkstyle:check -pl "$(dirname "$FILE_PATH")" 2>&1 | tail -5) || true
    ;;
  *)
    exit 0
    ;;
esac

# 如果有 lint 问题，作为 context 反馈给 Claude
if [ -n "$RESULT" ]; then
  jq -n --arg result "$RESULT" --arg file "$FILE_PATH"'{
    hookSpecificOutput: {
      hookEventName: "PostToolUse",
      additionalContext: "Lint 结果 [\($file)]:\n\($result)\n如果有问题请修复。"
    }
  }'
fi

exit 0

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/auto-lint.sh",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

#!/bin/bash
# .claude/hooks/inject-context.sh

# 收集项目状态
BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo"unknown")
RECENT_COMMITS=$(git log --oneline -5 2>/dev/null || echo"no commits")
DIRTY_FILES=$(git diff --name-only 2>/dev/null | head -10)
ISSUES=$(gh issue list -L 3 --json title,number --jq '.[] | "#\(.number) \(.title)"' 2>/dev/null || echo"GitHub CLI 不可用")

# 构建上下文
CONTEXT="
当前分支: $BRANCH
最近 5 次提交:
$RECENT_COMMITS

未提交的修改:
${DIRTY_FILES:-无}

最近的 Issues:
${ISSUES:-无}
"

jq -n --arg ctx "$CONTEXT"'{
  hookSpecificOutput: {
    hookEventName: "SessionStart",
    additionalContext: $ctx
  }
}'

exit 0

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/inject-context.sh",
            "timeout": 15
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "async": true,
            "command": "echo \"$(date +%Y-%m-%dT%H:%M:%S) | $(jq -r '.tool_name') | $(jq -r '.tool_input | tostring' | head -c 200)\" >> \"$CLAUDE_PROJECT_DIR\"/.claude/audit.log"
          }
        ]
      }
    ]
  }
}

2026-04-08T14:23:01 | Edit | {"file_path":"/src/main/java/Service.java","old_string":"...
2026-04-08T14:23:05 | Bash | {"command":"mvn compile -pl dlm-framework/dlm-rule"}
2026-04-08T14:23:12 | Read | {"file_path":"/src/test/java/ServiceTest.java"}

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "http",
            "url": "http://localhost:8080/api/validate-command",
            "headers": {
              "Authorization": "Bearer $COMPLIANCE_TOKEN"
            },
            "allowedEnvVars": ["COMPLIANCE_TOKEN"],
            "timeout": 10
          }
        ]
      }
    ]
  }
}