jq 與 yq 很適合處理 API、設定檔與自動化輸出。先用唯讀 filter 確認結果；yq 的 -i 會原地改檔，正式設定檔要先備份與驗證語法。
動手前：JSON／YAML 可能含 token、密碼與客戶資料。不要把完整輸出送到公開服務；原地修改前先保留備份。不同名稱的 yq 實作語法不一，本頁指 mikefarah/yq v4。
jq 查看與篩選 JSON
漂亮格式化 JSONjq
jq . response.json同時驗證基本 JSON 語法。
取單一欄位jq
jq -r '.name' response.json-r 輸出原始字串，不含 JSON 引號。
取巢狀欄位並給預設值jq
jq -r '.user.email // "未提供"' response.json// 在 null 或 false 時使用右值。
列出陣列欄位jq
jq -r '.devices[] | .name' response.json陣列不存在時會報錯，可搭 ? 或預設空陣列。
安全處理可能缺少的陣列jq
jq -r '(.devices // [])[] | .name' response.json避免 null 造成迭代失敗。
依條件篩選jq
jq '.devices[] | select(.status == "online")' response.json字串大小寫與實際 schema 要一致。
多條件篩選jq
jq '.devices[] | select(.status == "online" and .latency_ms > 50)' response.json數字若是字串需先 tonumber。
建立新物件jq
jq '.devices[] | {name, ip: .management_ip, status}' response.json方便只保留工單需要欄位。
陣列排序jq
jq '.devices | sort_by(.name)' response.jsonnull 與不同型別會影響排序。
依欄位分組jq
jq '.devices | sort_by(.site) | group_by(.site) | map({site: .[0].site, count: length})' response.jsongroup_by 前先 sort_by 較易理解與維護。
計算陣列長度jq
jq '.devices | length' response.json確認欄位確實是 array。
列出所有 keyjq
jq 'keys' response.json物件與陣列的結果語意不同。
jq 轉換、合併與 API
JSON 轉 TSVjq
jq -r '.devices[] | [.name,.management_ip,.status] | @tsv' response.json欄位含 tab 或換行時要小心下游解析。
JSON 轉 CSVjq
jq -r '.devices[] | [.name,.management_ip,.status] | @csv' response.json > devices.csv可先自行輸出 header。
加入 CSV 標題jq
jq -r '["name","ip","status"], (.devices[] | [.name,.management_ip,.status]) | @csv' response.json > devices.csv試開檢查中文與換行。
合併兩個物件jq
jq -s '.[0] * .[1]' base.json override.json後者同名 key 會覆蓋前者；深層語意先測。
合併多個陣列jq
jq -s 'add' part-*.json輸入都必須是 array 才符合預期。
從環境變數帶值jq
jq --arg site "$SITE" '.devices[] | select(.site == $site)' response.json--arg 會安全建立 jq 字串。
用 curl 管線篩選shell
curl -fsS https://api.example.com/v1/health | jq '{status, version}'API 回應與 verbose log 可能含敏感資料。
jq 結果為 false/null 時回失敗jq
jq -e '.status == "ok"' health.json適合 CI 健康檢查；看 jq exit code。
yq 處理 YAML
格式化並查看 YAMLyq v4
yq '.' config.yml同時確認 yq 能解析。
讀取巢狀值yq v4
yq '.server.port' config.yml輸出型別依內容。
列出陣列內容yq v4
yq '.services[].name' compose.yml路徑需符合實際結構。
篩選 YAML 陣列yq v4
yq '.devices[] | select(.enabled == true)' devices.ymlboolean true 不要寫成字串。
不改原檔預覽新值yq v4
yq '.server.port = 8443' config.yml先看輸出，不加 -i。
原地更新前建立備份shell
cp config.yml config.yml.bak && yq -i '.server.port = 8443' config.yml更新後跑應用的 config test；備份需妥善管理。
由環境變數設定字串yq v4
SITE=tainan yq '.site = strenv(SITE)' config.yml秘密環境變數仍需保護。
YAML 轉 JSONyq v4
yq -o=json '.' config.yml > config.json轉換後檢查 anchors、tag 與型別是否符合下游。
JSON 轉 YAMLyq v4
yq -P '.' config.json > config.yml-P 以 pretty YAML 輸出。
合併 YAMLyq v4
yq eval-all 'select(fileIndex == 0) * select(fileIndex == 1)' base.yml override.yml後者會覆蓋同名 key；陣列合併語意先測。
怎麼確認有做對
- 每次轉換後再用 jq . 或 yq . 解析一次。
- 抽查型別，特別是字串形式的數字、boolean 與 null。
- 原地更新後跑應用程式自己的 config test 與 diff。
常見錯誤
- 混用不同 yq 實作的語法。
- 直接 yq -i 改正式設定，沒有備份。
- 用字串比較數字造成排序或篩選錯誤。
- 把完整 API JSON 貼到公開工單。
版本與官方文件
參數會隨工具版本與作業系統實作改變。正式環境先用 --help、-h 或系統內建說明確認，再以當版官方文件為準。
