jq JSON 处理：命令行 JSON 查询、过滤与转换完全指南

jq-json-processing by laurigates/claude-plugins

91 周安装量

23 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/laurigates/claude-plugins --skill jq-json-processing

开发命令行工具数据处理

🇨🇳中文介绍

jq JSON 处理

使用 jq（轻量级且灵活的命令行 JSON 处理器）处理、查询和转换 JSON 数据的专业知识。

核心专长

JSON 操作

使用路径表达式查询和过滤 JSON
转换 JSON 结构和形态
合并、融合和拆分 JSON 数据
验证 JSON 语法和结构

数据提取

从 JSON 对象中提取特定字段
根据条件过滤数组
导航嵌套的 JSON 结构
处理空值和缺失键

基本命令

基础查询

# 美化打印 JSON
jq '.' file.json

# 提取特定字段
jq '.fieldName' file.json

# 提取嵌套字段
jq '.user.email' file.json

# 提取数组元素
jq '.[0]' file.json
jq '.items[2]' file.json

数组操作

# 获取数组长度
jq '.items | length' file.json

# 遍历数组
jq '.items | map(.name)' file.json

# 过滤数组
jq '.items[] | select(.active == true)' file.json
jq '.users[] | select(.age > 18)' file.json

# 数组排序
jq '.items | sort_by(.name)' file.json
jq '.items | sort_by(.date) | reverse' file.json

# 获取首/尾元素
jq '.items | first' file.json
jq '.items | last' file.json

# 唯一值
jq '.tags | unique' file.json

对象操作

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

相关 Skills

find-skills 技能搜索工具 - Vercel Labs 开源智能体技能包管理器

896,800 周安装

Vercel React 最佳实践指南 | 58条Next.js性能优化规则与代码重构

290,500 周安装

Vercel Web界面规范检查工具 - 自动检测代码是否符合Web设计指南

233,800 周安装

agent-browser 浏览器自动化工具 - Vercel Labs 命令行网页操作与测试

163,300 周安装

# 条件选择
jq 'select(.status == "active")' file.json
jq '.[] | select(.price < 100)' file.json

# 多条件 (AND)
jq '.[] | select(.active and .verified)' file.json
jq '.[] | select(.age > 18 and .country == "US")' file.json

# 多条件 (OR)
jq '.[] | select(.type == "admin" or .type == "moderator")' file.json

# 存在 / 拥有字段
jq '.[] | select(has("email"))' file.json
jq 'select(.optional != null)' file.json

# 非条件
jq '.[] | select(.status != "deleted")' file.json

# 字符串插值
jq '"Hello, \(.name)"' file.json

# 转换为字符串
jq '.id | tostring' file.json

# 字符串包含
jq '.[] | select(.email | contains("@gmail.com"))' file.json

# 字符串以...开始/结束
jq '.[] | select(.name | startswith("A"))' file.json
jq '.[] | select(.file | endswith(".json"))' file.json

# 分割字符串
jq '.path | split("/")' file.json

# 将数组连接为字符串
jq '.tags | join(", ")' file.json

# 小写/大写
jq '.name | ascii_downcase' file.json
jq '.name | ascii_upcase' file.json

# 递归下降
jq '.. | .email? // empty' file.json

# 归约 (求和，累加)
jq '[.items[].price] | add' file.json
jq 'reduce .items[] as $item (0; . + $item.price)' file.json

# 变量赋值
jq '.items[] | . as $item | $item.name + " - " + ($item.price | tostring)' file.json

# 条件 (if-then-else)
jq '.items[] | if .price > 100 then "expensive" else "affordable" end' file.json
jq 'if .error then .error else .data end' file.json

# 错误处理的 Try-catch
jq '.items[] | try .field catch "not found"' file.json

# 展平嵌套数组
jq '.items | flatten' file.json
jq '.items | flatten(1)' file.json  # 展平一层

# 从嵌套结构中提取所有电子邮件
jq '.. | .email? // empty' users.json

# 获取所有项目中所有标签的唯一列表
jq '[.items[].tags[]] | unique' data.json

# 按状态统计项目数
jq 'group_by(.status) | map({status: .[0].status, count: length})' items.json

# 将 API 响应转换为简单列表
jq '.results[] | {id, name: .full_name, active: .is_active}' response.json

# 过滤 GitHub 工作流运行 (最近的失败)
gh run list --json status,conclusion,name,createdAt | \
  jq '.[] | select(.conclusion == "failure") | {name, createdAt}'

# 提取 package.json 依赖项及其版本
jq '.dependencies | to_entries | map("\(.key)@\(.value)")' package.json

# 合并两个 JSON 文件
jq -s '.[0] * .[1]' base.json override.json

# 从日志数据创建摘要
jq 'group_by(.level) | map({level: .[0].level, count: length, samples: [.[].message][:3]})' logs.json

使用 ? 操作符进行可选访问：.field?
使用 // empty 过滤掉空值/错误
使用 try-catch 进行优雅的错误处理
使用 has("field") 检查字段是否存在

# 与 curl 集成 (API 调用)
curl -s "https://api.github.com/users/octocat" | jq '.name, .bio'

# 与 gh CLI 集成 (GitHub 操作)
gh api repos/owner/repo/issues | jq '.[] | {number, title, state}'

# 与 find 集成 (批处理)
find . -name "package.json" -exec jq '.version' {} \;

# 与 xargs 集成 (并行处理)
cat urls.txt | xargs -I {} curl -s {} | jq '.data'

# 与 yq 集成 (YAML 转 JSON 转换)
yq eval -o=json file.yaml | jq '.specific.field'

.field - 访问字段
.[] - 遍历数组/对象
| - 管道 (链式操作)
, - 多个输出
? - 可选 (抑制错误)
// - 替代操作符 (默认值)

keys, values - 对象键/值
length - 数组/对象/字符串长度
map(), select() - 数组操作
sort, sort_by() - 排序
group_by() - 分组
unique - 去重
add - 数字求和或字符串连接
has() - 检查字段是否存在
type - 获取值类型

tostring, tonumber - 转换类型
@csv, @tsv, @json - 格式化输出
split(), join() - 字符串/数组转换

🇺🇸English

jq JSON Processing

Expert knowledge for processing, querying, and transforming JSON data using jq, the lightweight and flexible command-line JSON processor.

Core Expertise

JSON Operations

Query and filter JSON with path expressions
Transform JSON structure and shape
Combine, merge, and split JSON data
Validate JSON syntax and structure

Data Extraction

Extract specific fields from JSON objects
Filter arrays based on conditions
Navigate nested JSON structures
Handle null values and missing keys

Essential Commands

Basic Querying

# Pretty-print JSON
jq '.' file.json

# Extract specific field
jq '.fieldName' file.json

# Extract nested field
jq '.user.email' file.json

# Extract array element
jq '.[0]' file.json
jq '.items[2]' file.json

Array Operations

# Get array length
jq '.items | length' file.json

# Map over array
jq '.items | map(.name)' file.json

# Filter array
jq '.items[] | select(.active == true)' file.json
jq '.users[] | select(.age > 18)' file.json

# Sort array
jq '.items | sort_by(.name)' file.json
jq '.items | sort_by(.date) | reverse' file.json

# Get first/last elements
jq '.items | first' file.json
jq '.items | last' file.json

# Unique values
jq '.tags | unique' file.json

Object Operations

# Get all keys
jq 'keys' file.json
jq '.config | keys' file.json

# Get all values
jq '.[] | values' file.json

# Select specific fields
jq '{name, email}' file.json
jq '{name: .fullName, id: .userId}' file.json

# Add field
jq '. + {newField: "value"}' file.json

# Delete field
jq 'del(.password)' file.json

# Merge objects
jq '. * {updated: true}' file.json

Filtering and Conditions

# Select with conditions
jq 'select(.status == "active")' file.json
jq '.[] | select(.price < 100)' file.json

# Multiple conditions (AND)
jq '.[] | select(.active and .verified)' file.json
jq '.[] | select(.age > 18 and .country == "US")' file.json

# Multiple conditions (OR)
jq '.[] | select(.type == "admin" or .type == "moderator")' file.json

# Exists / has field
jq '.[] | select(has("email"))' file.json
jq 'select(.optional != null)' file.json

# Not condition
jq '.[] | select(.status != "deleted")' file.json

String Operations

# String interpolation
jq '"Hello, \(.name)"' file.json

# Convert to string
jq '.id | tostring' file.json

# String contains
jq '.[] | select(.email | contains("@gmail.com"))' file.json

# String starts/ends with
jq '.[] | select(.name | startswith("A"))' file.json
jq '.[] | select(.file | endswith(".json"))' file.json

# Split string
jq '.path | split("/")' file.json

# Join array to string
jq '.tags | join(", ")' file.json

# Lowercase/uppercase
jq '.name | ascii_downcase' file.json
jq '.name | ascii_upcase' file.json

Pipes and Composition

# Chain operations
jq '.items | map(.name) | sort | unique' file.json

# Multiple filters
jq '.users[] | select(.active) | select(.age > 18) | .email' file.json

# Group by
jq 'group_by(.category)' file.json
jq 'group_by(.status) | map({status: .[0].status, count: length})' file.json

Output Formatting

# Compact output (no pretty-print)
jq -c '.' file.json

# Raw output (no quotes for strings)
jq -r '.message' file.json
jq -r '.items[] | .name' file.json

# Output as tab-separated values
jq -r '.[] | [.name, .age, .email] | @tsv' file.json

# Output as CSV
jq -r '.[] | [.name, .age, .email] | @csv' file.json

# Output as JSON array on one line
jq -c '[.items[]]' file.json

Input/Output Options

# Read from stdin
cat file.json | jq '.items'
curl -s https://api.example.com/data | jq '.results'

# Multiple input files
jq -s '.' file1.json file2.json  # Slurp into array

# Write to file
jq '.filtered' input.json > output.json

# In-place edit (use sponge from moreutils)
jq '.updated = true' file.json | sponge file.json

Advanced Patterns

# Recursive descent
jq '.. | .email? // empty' file.json

# Reduce (sum, accumulate)
jq '[.items[].price] | add' file.json
jq 'reduce .items[] as $item (0; . + $item.price)' file.json

# Variable assignment
jq '.items[] | . as $item | $item.name + " - " + ($item.price | tostring)' file.json

# Conditional (if-then-else)
jq '.items[] | if .price > 100 then "expensive" else "affordable" end' file.json
jq 'if .error then .error else .data end' file.json

# Try-catch for error handling
jq '.items[] | try .field catch "not found"' file.json

# Flatten nested arrays
jq '.items | flatten' file.json
jq '.items | flatten(1)' file.json  # Flatten one level

Real-World Examples

# Extract all emails from nested structure
jq '.. | .email? // empty' users.json

# Get unique list of all tags across items
jq '[.items[].tags[]] | unique' data.json

# Count items by status
jq 'group_by(.status) | map({status: .[0].status, count: length})' items.json

# Transform API response to simple list
jq '.results[] | {id, name: .full_name, active: .is_active}' response.json

# Filter GitHub workflow runs (recent failures)
gh run list --json status,conclusion,name,createdAt | \
  jq '.[] | select(.conclusion == "failure") | {name, createdAt}'

# Extract package.json dependencies with versions
jq '.dependencies | to_entries | map("\(.key)@\(.value)")' package.json

# Merge two JSON files
jq -s '.[0] * .[1]' base.json override.json

# Create summary from log data
jq 'group_by(.level) | map({level: .[0].level, count: length, samples: [.[].message][:3]})' logs.json

Best Practices

Query Construction

Start simple, build complexity incrementally
Test filters on small datasets first
Use -c flag for compact output in scripts
Use -r flag for raw strings (no quotes)

Performance

Use select() early in pipeline to reduce data
Use targeted queries with specific paths for large files
Stream large JSON with --stream flag
Consider jq -c for faster processing

Error Handling

Use ? operator for optional access: .field?
Use // empty to filter out nulls/errors
Use try-catch for graceful error handling
Check for field existence with has("field")

Readability

Break complex queries into multiple steps
Use variables with as $var for clarity
Add comments in shell scripts
Format multi-line jq programs for readability

Common Patterns

API Response Processing

# GitHub API: Get PR titles and authors
gh pr list --json title,author,number | \
  jq -r '.[] | "#\(.number) - \(.title) by @\(.author.login)"'

# REST API: Extract and flatten pagination
curl -s "https://api.example.com/items" | \
  jq '.data.items[] | {id, name, status}'

Configuration Files

# Extract environment-specific config
jq '.environments.production' config.json

# Update configuration value
jq '.settings.timeout = 30' config.json > config.updated.json

# Merge base config with environment overrides
jq -s '.[0] * .[1]' base-config.json prod-config.json

Log Analysis

# Count errors by type
jq 'select(.level == "error") | .type' logs.json | sort | uniq -c

# Extract error messages with timestamps
jq -r 'select(.level == "error") | "\(.timestamp) - \(.message)"' logs.json

# Group by hour and count
jq -r '.timestamp | split("T")[1] | split(":")[0]' logs.json | sort | uniq -c

Data Transformation

# CSV to JSON (with headers)
jq -R -s 'split("\n") | .[1:] | map(split(",")) |
  map({name: .[0], age: .[1], email: .[2]})' data.csv

# JSON to CSV
jq -r '.[] | [.name, .age, .email] | @csv' data.json

# Flatten nested structure
jq '[.items[] | {id, name, category: .meta.category}]' nested.json

Troubleshooting

Invalid JSON

# Validate JSON syntax
jq empty file.json  # Returns exit code 0 if valid

# Find syntax errors
jq '.' file.json 2>&1 | grep "parse error"

Empty Results

# Debug: Print entire structure
jq '.' file.json

# Debug: Check field existence
jq 'keys' file.json
jq 'type' file.json  # Check if array, object, etc.

# Debug: Show all values
jq '.. | scalars' file.json

Type Errors

# Check field types
jq '.field | type' file.json

# Convert types safely
jq '.id | tonumber' file.json
jq '.count | tostring' file.json

# Handle mixed types
jq '.items[] | if type == "array" then .[] else . end' file.json

Performance Issues

# Stream large files
jq --stream '.' large-file.json

# Process line by line
cat large.json | jq -c '.[]' | while read -r line; do
  echo "$line" | jq '.field'
done

Integration with Other Tools

# With curl (API calls)
curl -s "https://api.github.com/users/octocat" | jq '.name, .bio'

# With gh CLI (GitHub operations)
gh api repos/owner/repo/issues | jq '.[] | {number, title, state}'

# With find (batch processing)
find . -name "package.json" -exec jq '.version' {} \;

# With xargs (parallel processing)
cat urls.txt | xargs -I {} curl -s {} | jq '.data'

# With yq (YAML to JSON conversion)
yq eval -o=json file.yaml | jq '.specific.field'

Quick Reference

Operators

.field - Access field
.[] - Iterate array/object
| - Pipe (chain operations)
, - Multiple outputs
? - Optional (suppress errors)
// - Alternative operator (default value)

Functions

keys, values - Object keys/values
length - Array/object/string length
map(), select() - Array operations
sort, sort_by() - Sorting
group_by() - Grouping
unique - Remove duplicates
add - Sum numbers or concatenate
has() - Check field existence

Type Conversions

tostring, tonumber - Convert types
@csv, @tsv, @json - Format output
split(), join() - String/array conversion

Installation

# macOS (Homebrew)
brew install jq

# Ubuntu/Debian
sudo apt-get install jq

# Verify installation
jq --version

Resources

Official Manual : https://stedolan.github.io/jq/manual/
jq Playground : https://jqplay.org/
Tutorial : https://stedolan.github.io/jq/tutorial/

Weekly Installs

Repository

laurigates/clau…-plugins

GitHub Stars

First Seen

Feb 12, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

opencode84

github-copilot83

codex83

gemini-cli82

amp82

kimi-cli82

jq JSON 处理：命令行 JSON 查询、过滤与转换完全指南

🇨🇳中文介绍

jq JSON 处理

核心专长

基本命令

基础查询

数组操作

对象操作

相关 Skills

过滤与条件

字符串操作

管道与组合

输出格式化

输入/输出选项

高级模式

实际示例

最佳实践

常见模式

API 响应处理

配置文件

日志分析

数据转换

故障排除

无效 JSON

空结果

类型错误

性能问题

与其他工具集成

快速参考

操作符

函数

类型转换

安装

资源