hereink

如何使用 jq 命令列處理 JSON：安裝、篩選欄位、映射陣列與 curl 管道

安裝 jq，提取 JSON 欄位、映射陣列，並用 curl 管道快速查看 API 回應。

除錯 REST API 或讀 CI 日誌時，jq 讓你在終端直接篩選和變換 JSON，不必把整段回應貼進編輯器。本教學走 macOS、Linux 與 Windows 的官方安裝路徑，並示範欄位提取、陣列映射與 curl 管道，面向 hereink 讀者常用的命令列工作流。

檢索詞是如何使用 jq 處理 JSON 並與 curl 管道。讀完應能安裝 jq、用 .key 取欄位、用 map 處理陣列，並把 API 回應縮成幾行可讀輸出。

安裝brew / apt / winget
篩選.field · .[] · select
管道curl -s … | jq

jq 解決什麼問題

比 python -m json.tool 更靈活

內建 json.tool 只能美化。jq 可以只列印 .data.items[0].id、過濾陣列、或把巢狀結構壓平，適合腳本和一次性除錯。

與 curl 天然搭檔

API 回應往往幾百行。管道末尾加 jq '.field'，終端只留你關心的鍵，減少捲動和複製貼上。

確認版本：jq --version。官方站點與手冊：jqlang.org，GitHub 組織 jqlang/jq。

在三大系統安裝 jq

  1. 1
    macOS（Homebrew）

    執行 brew install jq。驗證：which jq 與 jq --version。Apple Silicon 與 Intel 共用同一公式。

  2. 2
    Linux（發行版套件）

    Debian/Ubuntu：sudo apt update && sudo apt install jq。Fedora：sudo dnf install jq。Arch：sudo pacman -S jq。若倉庫版本過舊，可從 GitHub Releases 下載靜態二進位。

  3. 3
    Windows

    PowerShell：winget install jqlang.jq，或 Chocolatey：choco install jq。新開終端後跑 jq --version。

  4. 4
    第一條過濾器

    測試：echo '{"ok":true,"n":3}' | jq .ok 應輸出 true。全物件美化：echo '{"a":1}' | jq .。

篩選欄位與映射陣列

echo '{"user":{"name":"Lin","role":"admin"}}' | jq .user.name
echo '{"items":[{"id":1},{"id":2}]}' | jq '.items[]'
echo '{"items":[{"id":1,"x":0},{"id":2,"x":1}]}' | jq '.items | map(.id)'
echo '[{"k":"a","v":1},{"k":"b","v":2}]' | jq '[.[] | select(.v > 1)]'
echo '{"a":1,"b":2,"c":3}' | jq '{a,b}'

過濾器用單引號包住，避免 shell 展開 $。點號 . 表示目前 JSON 值；[] 迭代陣列。

與 curl 管道

場景命令範例說明
公開 API 元資料curl -s https://api.github.com/repos/jqlang/jq | jq '{name, description, stars: .stargazers_count}'只留 name、description、stars
腳本用純文字curl -s … | jq -r '.token'-r 去掉 JSON 字串引號
緊湊日誌行curl -s … | jq -c '.items[]'每元素一行，便於 rg 再搜
私有 APIcurl -s -H "Authorization: Bearer $TOKEN" … | jq .jq 只處理回應體
適合
快速查看 REST 回應欄位、過濾容器日誌裡的 JSON 行、CI 裡解析建置元資料。
不適合
編輯並寫回大 JSON 檔；非 JSON 文字（先用 grep/rg）。
jq: parse error 是什麼意思？

輸入不是合法 JSON。用 jq . 單獨測輸入；對 NDJSON 用 jq -s 或逐行處理。

Windows 上 jq 找不到命令？

安裝後重啟終端。執行 where jq。winget/Chocolatey 通常會自動加入 PATH。

jq 和 yq 一樣嗎？

不一樣。jq 專用於 JSON。YAML 需 yq 或先轉格式。

欄位對齊後畫一張圖

終端裡理清 API 結構後，服務邊界仍適合攤在同一張白板上。見 如何建立空間。

立即開會