Headless模式与自动化

Headless模式让Claude Code可以在非交互环境下运行，这是实现CI/CD集成和自动化的关键。

什么是Headless模式？

Headless模式使用 -p 参数执行单行命令，不进入交互界面：

bash

# 交互模式
claude
> 输入问题...

# Headless模式
claude -p "分析这个项目的结构"

基本用法

单行命令

bash

# 分析代码
claude -p "这个项目的架构是什么？"

# 生成文档
claude -p "为src/api目录生成API文档"

# 代码审查
claude -p "审查最近一次提交的代码"

指定文件

bash

# 分析特定文件
claude -p "解释 src/auth.py 的功能" --file src/auth.py

# 处理多个文件
claude -p "检查这些文件的类型定义" --file "src/**/*.ts"

输出格式

JSON输出

bash

claude -p "统计项目中的TODO数量" --output-format json

输出：

json

{
  "result": "找到15个TODO注释",
  "details": [
    {"file": "src/main.ts", "line": 42, "content": "TODO: 添加错误处理"},
    {"file": "src/api.ts", "line": 15, "content": "TODO: 优化性能"}
  ]
}

流式JSON

适合实时处理：

bash

claude -p "分析日志文件并报告错误" --output-format stream-json

纯文本（默认）

bash

claude -p "解释这个函数的作用"

CI/CD集成

GitHub Actions

yaml

# .github/workflows/claude-review.yml
name: Claude Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Claude Code
        run: npm install -g @anthropic-ai/claude-code
        
      - name: Configure Claude
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude config set apiKey $ANTHROPIC_API_KEY
          
      - name: Run Code Review
        run: |
          claude -p "审查这个PR的代码变更，检查安全问题和性能问题" \
            --output-format json > review-result.json
            
      - name: Post Review Comment
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const result = JSON.parse(fs.readFileSync('review-result.json'));
            await github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body: result.result
            });

GitLab CI

yaml

# .gitlab-ci.yml
claude-review:
  stage: test
  image: node:20
  script:
    - npm install -g @anthropic-ai/claude-code
    - export ANTHROPIC_API_KEY=$CI_ANTHROPIC_API_KEY
    - claude -p "运行代码审查并生成报告" --output-format json > review.json
  artifacts:
    paths:
      - review.json

Jenkins Pipeline

groovy

pipeline {
    agent any
    stages {
        stage('Claude Review') {
            steps {
                sh 'npm install -g @anthropic-ai/claude-code'
                withCredentials([string(credentialsId: 'anthropic-api-key', variable: 'API_KEY')]) {
                    sh 'claude config set apiKey $API_KEY'
                    sh 'claude -p "审查代码" --output-format json > review.json'
                }
            }
        }
    }
}

Git Hooks集成

Pre-commit Hook

bash

#!/bin/bash
# .git/hooks/pre-commit

# 获取待提交的文件
files=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(ts|tsx|js|jsx)$')

if [ -n "$files" ]; then
    echo "运行Claude代码检查..."
    
    result=$(claude -p "检查这些文件的代码质量：$files" \
        --dangerously-skip-permissions \
        --output-format text)
    
    if echo "$result" | grep -q "CRITICAL"; then
        echo "发现严重问题，提交被阻止"
        echo "$result"
        exit 1
    fi
fi

exit 0

Pre-push Hook

bash

#!/bin/bash
# .git/hooks/pre-push

echo "运行安全检查..."

result=$(claude -p "检查代码中的安全漏洞" \
    --dangerously-skip-permissions)

if echo "$result" | grep -q "SECURITY"; then
    echo "发现安全问题，推送被阻止"
    exit 1
fi

exit 0

自动化脚本示例

批量生成测试

bash

#!/bin/bash
# generate-tests.sh

# 为所有没有测试的源文件生成测试
find src -name "*.ts" -not -name "*.test.ts" | while read file; do
    test_file="${file%.ts}.test.ts"
    
    if [ ! -f "$test_file" ]; then
        echo "为 $file 生成测试..."
        claude -p "为这个文件生成完整的单元测试：$file" \
            --file "$file" \
            --output-format text > "$test_file"
    fi
done

自动化文档生成

bash

#!/bin/bash
# generate-docs.sh

# 生成API文档
claude -p "扫描所有API端点并生成OpenAPI文档" \
    --output-format json > docs/api.json

# 生成README
claude -p "根据项目内容更新README.md" \
    --dangerously-skip-permissions

# 生成CHANGELOG
claude -p "根据git历史生成CHANGELOG" \
    --output-format text > CHANGELOG.md

代码质量检查

bash

#!/bin/bash
# code-quality-check.sh

echo "=== 运行代码质量检查 ==="

# 1. 检查代码复杂度
echo "检查代码复杂度..."
claude -p "分析代码复杂度，找出最复杂的10个函数" \
    --output-format json > reports/complexity.json

# 2. 检查安全问题
echo "检查安全问题..."
claude -p "扫描代码中的安全漏洞，包括SQL注入、XSS等" \
    --output-format json > reports/security.json

# 3. 检查性能问题
echo "检查性能问题..."
claude -p "找出可能的性能瓶颈" \
    --output-format json > reports/performance.json

# 4. 生成汇总报告
claude -p "根据以上检查结果生成汇总报告" \
    --output-format text > reports/summary.md

echo "=== 检查完成 ==="

自动化重构

bash

#!/bin/bash
# auto-refactor.sh

# 找出需要重构的代码
issues=$(claude -p "找出代码中需要重构的部分，列出文件路径和原因" \
    --output-format json)

# 对每个问题执行重构
echo "$issues" | jq -r '.files[]' | while read file; do
    echo "重构 $file..."
    claude -p "重构这个文件以提高代码质量" \
        --file "$file" \
        --dangerously-skip-permissions
done

定时任务

Cron集成

bash

# crontab -e

# 每天早上8点运行代码审查
0 8 * * * cd /path/to/project && claude -p "每日代码审查" >> /var/log/claude-daily.log

# 每周一生成周报
0 9 * * 1 cd /path/to/project && claude -p "生成本周开发周报" > /reports/weekly.md

使用systemd

ini

# /etc/systemd/system/claude-watch.service
[Unit]
Description=Claude Code Watch Service

[Service]
Type=simple
ExecStart=/usr/local/bin/claude-watch.sh
Restart=on-failure

[Install]
WantedBy=multi-user.target

bash

#!/bin/bash
# /usr/local/bin/claude-watch.sh

while true; do
    # 监控文件变化
    inotifywait -r -e modify,create,delete ./src
    
    # 运行检查
    claude -p "检查最近的代码变更" --output-format json >> /var/log/claude-watch.log
    
    sleep 60
done

高级技巧

链式命令

bash

# 多步骤任务
claude -p "分析代码" && \
claude -p "根据分析结果重构" && \
claude -p "运行测试验证"

管道处理

bash

# 从日志分析
tail -100 /var/log/app.log | claude -p "分析这些日志，找出错误原因"

# 从git diff分析
git diff HEAD~1 | claude -p "审查这次代码变更"

环境变量传递

bash

# 传递环境变量
export BRANCH_NAME=$(git branch --show-current)
claude -p "当前分支是 $BRANCH_NAME，分析这个分支的变更"

最佳实践

1. 使用 --dangerously-skip-permissions 谨慎

仅在受信任的环境中使用：

bash

# CI环境可以安全使用
if [ "$CI" = "true" ]; then
    claude -p "..." --dangerously-skip-permissions
else
    claude -p "..."
fi

2. 错误处理

bash

#!/bin/bash
set -e

result=$(claude -p "检查代码" --output-format json)

if [ $? -ne 0 ]; then
    echo "Claude执行失败"
    exit 1
fi

# 处理结果
echo "$result" | jq '.result'

3. 结果验证

bash

result=$(claude -p "生成配置文件")

# 验证输出
if ! echo "$result" | jq -e . > /dev/null 2>&1; then
    echo "输出不是有效的JSON"
    exit 1
fi

下一步

学会了Headless模式后，继续学习高级CLI参数。

Headless模式与自动化 ​

什么是Headless模式？ ​

基本用法 ​

单行命令 ​

指定文件 ​

输出格式 ​

JSON输出 ​

流式JSON ​

纯文本（默认） ​

CI/CD集成 ​

GitHub Actions ​

GitLab CI ​

Jenkins Pipeline ​

Git Hooks集成 ​

Pre-commit Hook ​

Pre-push Hook ​

自动化脚本示例 ​

批量生成测试 ​

自动化文档生成 ​

代码质量检查 ​

自动化重构 ​

定时任务 ​

Cron集成 ​

使用systemd ​

高级技巧 ​

链式命令 ​

管道处理 ​

环境变量传递 ​

最佳实践 ​

1. 使用 --dangerously-skip-permissions 谨慎 ​

2. 错误处理 ​

3. 结果验证 ​

下一步 ​

Headless模式与自动化

什么是Headless模式？

基本用法

单行命令

指定文件

输出格式

JSON输出

流式JSON

纯文本（默认）

CI/CD集成

GitHub Actions

GitLab CI

Jenkins Pipeline

Git Hooks集成

Pre-commit Hook

Pre-push Hook

自动化脚本示例

批量生成测试

自动化文档生成

代码质量检查

自动化重构

定时任务

Cron集成

使用systemd

高级技巧

链式命令

管道处理

环境变量传递

最佳实践

1. 使用 --dangerously-skip-permissions 谨慎

2. 错误处理

3. 结果验证

下一步