結論先說
- 三參數固定組合:必須同時帶上
-p、--output-format json與--json-schema '<Schema>'。 - 從
.structured_output取值:啟用 Schema 後,校驗通過的原生 JSON 對象存放在外層信封的structured_output字段,用jq '.structured_output'直接讀取,無需二次反序列化字符串。 - 不阻礙中間工具調用:Schema 只約束最終交付格式,執行期間 Claude 仍可正常調用
Read、Grep與Bash。 - Schema 存獨立文件最穩:把定義寫進
.json文件再讀入變量傳參,可避開命令行引號轉義錯誤。 - 開通與配額入口:自動化批量審計消耗配額集中;國內無外幣卡用戶可在 Claude Code 訂閱專頁 或免密兌換的 Claude Pro iOS 卡密 開通,高頻流水線建議看 5 倍額度的 Claude Max 升級服務。

圖:本站根據 Claude Code 官方文檔:Run Claude Code programmatically 整理的示意圖
本文根據 Claude Code 官方文檔《CLI reference》與《Run Claude Code programmatically》整理,資料核對於 2026-11-18。配圖為本站整理的示意圖,不是介面截圖。本站(bigolab.com)不是 Anthropic 官方網站。
適用於誰
- 在腳本里讓 Claude 審代碼或出變更單,但總被 JSON 前後夾帶的解釋文字弄崩
jq解析的人; - 想保留 Claude Code 多步讀文件、搜代碼能力,僅在最後一步拿到嚴格類型化 JSON 的開發者;
- 在 PowerShell 或 Bash 裏傳 JSON Schema 字符串常遇到引號轉義報錯的人。
一、純提示詞求 JSON 與 --json-schema 的區別
只在提示詞裏寫「只輸出 JSON」時,模型仍可能包一層 Markdown 代碼圍欄或漏掉必填鍵。官方參數對比如下:
| 對比項 | 僅靠提示詞求 JSON | 僅開 --output-format json | 疊加 --json-schema |
|---|---|---|---|
| 業務結果位置 | 自由文本無固定字段 | .result(仍是字符串) | .structured_output(原生對象) |
| 必填項與枚舉保證 | 無,易拼錯鍵名或漏鍵 | 無業務字段校驗 | 嚴格按 Schema 校驗類型與枚舉 |
| 下游消費複雜度 | 需寫正則剝離代碼圍欄 | 需二次 fromjson 解析 | jq '.structured_output' 直接用 |
結構化輸出的通用 Schema 寫法也可對比 Gemini 結構化輸出 JSON Schema 指南。
二、實戰一:提取代碼安全審計報告(Bash 寫法)
先將結構定義存為 audit-schema.json:
json
{
"type": "object",
"properties": {
"blocking": { "type": "boolean" },
"issues": {
"type": "array",
"items": {
"type": "object",
"properties": {
"file": { "type": "string" },
"line": { "type": "integer" },
"severity": { "type": "string", "enum": ["high", "medium", "low"] }
},
"required": ["file", "line", "severity"]
}
}
},
"required": ["blocking", "issues"]
}
在腳本中讀取文件並提取結構化結果:
bash
SCHEMA=$(jq -c . audit-schema.json)
claude -p "審查當前分支新增接口的鑑權與注入風險" \
--output-format json \
--json-schema "$SCHEMA" \
| jq '.structured_output' > report.json
CI 只需檢查 jq -e '.blocking == false' report.json 即可判定門禁是否通過。完整流水線集成見 Claude Code 在 CI 裏無頭運行完整示例。
批量審計與訂閱配額提示:每次帶--json-schema掃描倉庫時,模型仍需多輪讀取文件並完成格式校驗,密集跑批較易觸及 Pro 檔 5 小時限額。長期跑代碼檢查的開發者可在 Claude Pro 會員自助充值 或大額度的 Claude Max 訂閱升級 中按需選型;訂閱與 API 成本對比見 Claude Code 用 Pro、Max 還是 API 划算。
三、實戰二:Windows PowerShell 生成發版變更單
PowerShell 下直接內聯雙引號極易被截斷,用 Get-Content -Raw 最省心:

圖:本站根據 Claude Code 官方文檔:CLI reference 整理的示意圖
powershell
$schema = Get-Content -Path .\changelog-schema.json -Raw
$res = claude -p "對比 main..HEAD 生成結構化變更單" --output-format json --json-schema $schema
($res | ConvertFrom-Json).structured_output | ConvertTo-Json -Depth 5
編寫 Schema 時牢記四條工程實踐細節:
- 所有必選字段都列進
required數組:JSON Schema 預設允許屬性缺省,只要沒寫進對應對象層級的required列表,模型在拿不準或偷懶時就可能直接省略該鍵,導致下游入庫腳本報空指針; - 分類與等級字段一律用
enum鎖死取值:例如把嚴重程度限定為["high", "medium", "low"],避免一次輸出大寫"HIGH"、下一次又輸出"critical"或中文"高危"; - 善用
description寫明字段業務口徑:在屬性裏加上簡短的"description": "相對於倉庫根目錄的文件路徑",比把字段解釋全堆在外部提示詞裏更不容易跑偏; - 控制單次掃描範圍與最大輪次:在大倉庫跑自動提取時,建議配合
--max-turns與明確的git diff範圍限制輸入體積,既能防止中途超時拿不到最終結構化對象,也能大幅節省單次調用的 Token 開銷。剛接觸 CLI 基礎命令的讀者可先閱讀 Claude Code 中文入門教學。
常見問題
問:為什麼返回 JSON 裏沒有 structured_output 字段?
答:先核對是否漏了 --output-format json,再看返回裏的 is_error 是否為 true(如觸發 --max-turns 輪次上限提前中止,尚未走到最終輸出步驟)。
問:提示 JSON Schema 無效怎麼排查?
答:九成是命令行引號被 Shell 吞掉。先用 jq . schema.json 驗證文件合法,再改為變量傳參。
問:能不能一邊改文件一邊最後返回結構化變更清單?
答:可以,搭配 --allowedTools "Edit" 放行編輯權限後,它會先按要求改完業務源碼文件,最後一步再嚴格按照你傳入的 Schema 彙總輸出本次改動涉及的文件路徑、修改行數與風險說明列表。
問:國內沒有外幣信用卡,怎麼開通訂閱並開報銷發票?
答:可通過本站 Claude Code 訂閱專頁 或 AI 會員充值總覽 辦理,支持支付寶、微信支付與 AlipayHK,提供免密卡密自助兌換,企業採購可開具國內增值稅發票。實時價格與售後邊界以頁面展示為準:訂閱期內非違規掉訂閱按剩餘天數折退,風控封號不在質保範圍。
相關教學
- Claude Code 在 CI 裏跑:從 claude -p 到自動審 PR
- Gemini 結構化輸出怎麼用:JSON Schema 示例
- Claude Code 用 Pro、Max 還是 API 划算
- Claude Code 中文入門教學
參考資料
- Claude Code 官方文檔:CLI reference — https://code.claude.com/docs/en/cli-reference
- Claude Code 官方文檔:Run Claude Code programmatically — https://code.claude.com/docs/en/headless
0 條評論
還沒有評論,來搶沙發~