6.9 --output-format - 指定输出格式

概述

--output-format 标志允许您指定 Claude 响应的输出格式。这对于自动化脚本、数据处理、API 集成等场景非常有用。

基本语法

bash


claude --output-format <格式>

支持的格式

格式	描述	使用场景

text| 纯文本格式（默认）| 一般对话和代码生成 json| JSON 格式| 自动化脚本、API 集成 markdown| Markdown 格式| 文档生成、技术写作 yaml| YAML 格式| 配置文件生成

使用场景

1. JSON 格式输出

用于自动化脚本和数据处理：

    bash


    # 获取 JSON 格式的响应
    claude --output-format json -p "分析这个 Python 文件的结构"

    # 输出示例
    {
      "analysis": {
        "language": "Python",
        "functions": ["main", "process_data", "calculate"],
        "imports": ["os", "sys", "json"],
        "complexity": "medium"
      },
      "suggestions": [
        "添加类型注解",
        "拆分长函数",
        "添加错误处理"
      ]
    }

### 2\. Markdown 格式输出

用于文档生成和技术写作：

    bash


    # 生成 Markdown 格式的文档
    claude --output-format markdown -p "为这个 API 生成文档"

    # 输出示例
    # API 文档
    ## 用户认证
    ### POST /api/auth/login
    登录用户账号。

    ```json

    {
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "user": {
        "id": 1,
        "username": "john_doe"
      }
    }


### 3\. YAML 格式输出


用于配置文件生成：

```javascript
    bash


    # 生成 YAML 格式的配置
    claude --output-format yaml -p "生成一个 Docker Compose 配置"

    # 输出示例
    version: '3.8'
    services:
      web:
        image: nginx:latest
        ports:
          - "80:80"
        volumes:
          - ./html:/usr/share/nginx/html
      db:
        image: postgres:13
        environment:
          POSTGRES_PASSWORD: example
        volumes:
          - postgres_data:/var/lib/postgresql/data
    volumes:
      postgres_data:

### 4\. 纯文本格式输出

用于一般对话和代码生成：

    bash


    # 默认文本格式
    claude --output-format text -p "解释什么是递归"

    # 输出示例
    递归是一种编程技术，函数直接或间接地调用自身。

    基本原理：
    1. 基础情况：递归的终止条件
    2. 递归情况：函数调用自身，但参数更接近基础情况

    示例：
    def factorial(n):
        if n <= 1:
            return 1
        return n * factorial(n - 1)

## 高级用法

### 1\. 与其他标志组合

    bash


    # JSON 格式 + 指定模型
    claude --output-format json --model opus -p "分析代码"

    # Markdown 格式 + 限制工具
    claude --output-format markdown --allowedTools "Read" "Grep" -p "生成文档"

    # YAML 格式 + 详细日志
    claude --output-format yaml --verbose -p "生成配置"

### 2\. 管道输出到文件

    bash


    # 将 JSON 输出保存到文件
    claude --output-format json -p "分析项目结构" > analysis.json

    # 将 Markdown 输出保存到文件
    claude --output-format markdown -p "生成 README" > README.md

    # 将 YAML 输出保存到文件
    claude --output-format yaml -p "生成配置" > config.yaml

### 3\. 与其他工具集成

    bash


    # 使用 jq 处理 JSON 输出
    claude --output-format json -p "获取文件列表" | jq '.files[]'

    # 使用 pandoc 转换 Markdown
    claude --output-format markdown -p "生成文档" | pandoc -o doc.pdf

    # 使用 yq 处理 YAML 输出
    claude --output-format yaml -p "生成配置" | yq '.services[].image'

### 4\. 在脚本中使用

    bash


    #!/bin/bash
    # analyze.sh

    # 获取 JSON 格式的分析结果
    RESULT=$(claude --output-format json -p "分析代码质量")

    # 提取评分
    SCORE=$(echo "$RESULT" | jq '.score')

    # 根据评分执行不同操作
    if [ "$SCORE" -gt 80 ]; then
        echo "代码质量优秀"
    else
        echo "代码质量需要改进"
    fi

## 实际应用示例

### 示例 1: 自动化代码审查

    bash


    #!/bin/bash
    # code-review.sh
    FILE=$1

    # 获取 JSON 格式的审查结果
    REVIEW=$(claude --output-format json \
    --append-system-prompt "代码审查重点：安全性、性能、可维护性" \
    -p "审查 $FILE 的代码质量")

    # 提取问题数量
    ISSUES=$(echo "$REVIEW" | jq '.issues | length')
    echo "发现 $ISSUES 个问题"

    # 如果有问题，显示详细信息
    if [ "$ISSUES" -gt 0 ]; then
    echo "$REVIEW" | jq '.issues[]'
    fi

### 示例 2: 自动生成文档

    bash


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

    # 为所有 Python 文件生成 Markdown 文档
    for file in src/*.py; do
        echo "为 $file 生成文档..."

        claude --output-format markdown \
          --append-system-prompt "生成符合 Google 风格的 API 文档" \
          -p "为 $file 生成文档" > "docs/$(basename $file .py).md"
    done

    echo "文档生成完成"

### 示例 3: 配置文件生成

    bash


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

    # 生成 YAML 格式的配置文件
    claude --output-format yaml \
    --append-system-prompt "生成生产环境的配置文件" \
    -p "生成包含 Web 服务器、数据库和缓存的配置" > docker-compose.yml

    echo "配置文件已生成：docker-compose.yml"

### 示例 4: 数据分析报告

    bash


    #!/bin/bash
    # analyze-data.sh

    DATA_FILE=$1

    # 获取 JSON 格式的分析结果
    ANALYSIS=$(claude --output-format json \
      --append-system-prompt "数据分析重点：趋势、异常、建议" \
      -p "分析 $DATA_FILE 中的数据")

    # 生成 Markdown 报告
    cat > report.md << EOF
    # 数据分析报告

    ## 概述
    \$(echo "$ANALYSIS" | jq -r '.summary')

    ## 关键指标
    \$(echo "$ANALYSIS" | jq -r '.metrics | to_entries[] | "- \(.key): \(.value)"')

    ## 建议
    \$(echo "$ANALYSIS" | jq -r '.recommendations[] | "- \(.)"')
    EOF

    echo "报告已生成：report.md"

## 格式特定技巧

### JSON 格式技巧

    bash


    # 请求结构化的 JSON 输出
    claude --output-format json -p "以 JSON 格式返回文件列表，包含文件名、大小和修改时间"

    # 在提示中指定 JSON 结构
    claude --output-format json -p "返回以下 JSON 结构：{\"files\": [{\"name\": \"\", \"size\": 0, \"lines\": 0}]}"

    # 使用 jq 提取特定字段
    claude --output-format json -p "分析代码" | jq '.suggestions[]'

### Markdown 格式技巧

    bash


    # 请求特定类型的 Markdown 内容
    claude --output-format markdown -p "生成包含代码示例和表格的 Markdown 文档"

    # 生成 API 文档
    claude --output-format markdown -p "生成 OpenAPI 规范格式的 API 文档"

    # 生成技术博客
    claude --output-format markdown -p "写一篇关于微服务架构的技术博客"

### YAML 格式技巧

    bash


    # 生成 Kubernetes 配置
    claude --output-format yaml -p "生成 Kubernetes Deployment 和 Service 配置"

    # 生成 CI/CD 配置
    claude --output-format yaml -p "生成 GitHub Actions 工作流配置"

    # 生成多环境配置
    claude --output-format yaml -p "生成开发、测试和生产环境的配置"

## 最佳实践

### 1\. 选择合适的格式

    bash


    # 数据处理和自动化 -> JSON
    claude --output-format json -p "分析数据"

    # 文档和技术写作 -> Markdown
    claude --output-format markdown -p "生成文档"

    # 配置文件 -> YAML
    claude --output-format yaml -p "生成配置"

    # 一般对话 -> text（默认）
    claude -p "解释概念"

### 2\. 在提示中指定结构

    bash


    # 明确指定 JSON 结构
    claude --output-format json -p "返回 JSON：{\"result\": \"\", \"confidence\": 0.0}"

    # 明确指定 Markdown 结构
    claude --output-format markdown -p "生成包含标题、代码块和表格的 Markdown"

### 3\. 验证输出格式

    bash


    # 验证 JSON 格式
    claude --output-format json -p "分析代码" | jq . > /dev/null && echo "JSON 有效"

    # 验证 YAML 格式
    claude --output-format yaml -p "生成配置" | yq eval . > /dev/null && echo "YAML 有效"

### 4\. 错误处理

    bash


    #!/bin/bash
    # 处理 JSON 输出错误
    RESULT=$(claude --output-format json -p "分析代码")
    if ! echo "$RESULT" | jq . > /dev/null 2>&1; then
    echo "错误：无效的 JSON 输出"
    echo "$RESULT"
    exit 1
    fi
    echo "JSON 输出有效"

## 常见问题

### Q1: 所有格式都支持吗？

A: 支持的格式包括 text、json、markdown 和 yaml。某些复杂格式可能需要额外的处理。

### Q2: 如何确保输出是有效的格式？

A: 可以使用相应的验证工具（如 jq 验证 JSON，yq 验证 YAML）来验证输出。

### Q3: 可以自定义输出格式吗？

A: 不可以直接自定义格式，但可以在提示中指定输出的结构和内容。

### Q4: JSON 输出的大小有限制吗？

A: 有一定的限制，但对于大多数应用场景来说足够。如果输出很大，考虑分批处理。

### Q5: 如何处理格式错误？

A: 使用验证工具检查输出，并在脚本中添加错误处理逻辑。

## 与其他工具的集成

### 1\. 与 jq 集成

    bash


    # 提取特定字段
    claude --output-format json -p "分析代码" | jq '.score'

    # 过滤数据
    claude --output-format json -p "获取文件列表" | jq '.files[] | select(.size > 1024)'

    # 转换格式
    claude --output-format json -p "分析数据" | jq -r '.summary'

### 2\. 与 yq 集成

    bash


    # 提取配置值
    claude --output-format yaml -p "生成配置" | yq '.services.web.image'

    # 更新配置
    claude --output-format yaml -p "生成配置" | yq '.services.web.ports[0] = "8080:80"' > new-config.yaml

### 3\. 与 pandoc 集成

    bash


    # Markdown 转 PDF
    claude --output-format markdown -p "生成文档" | pandoc -o document.pdf

    # Markdown 转 HTML
    claude --output-format markdown -p "生成文档" | pandoc -o document.html

### 4\. 与 Python 集成

    python


    import subprocess
    import json

    # 获取 JSON 输出
    result = subprocess.run(
        ['claude', '--output-format', 'json', '-p', '分析代码'],
        capture_output=True,
        text=True
    )

    # 解析 JSON
    data = json.loads(result.stdout)

    # 使用数据
    print(f"分数: {data['score']}")
    print(f"建议: {data['suggestions']}")