mikefarah/yq

项目介绍

yq 是一个轻量、可移植的命令行处理器，支持 YAML、JSON、XML、CSV、TSV、TOML、HCL、INI 和 properties 等格式。它采用与 jq 相似的表达式语法，熟悉 jq 的用户可以把基本的取值、筛选和赋值思路直接迁移到不同格式上。项目用 Go 编写，提供无额外依赖的二进制文件，适合放进 shell 脚本、CI 任务和容器镜像里处理结构化配置。

它面向开发者、DevOps 工程师以及需要从终端读写配置文件的用户。除读取外，还支持原地更新文件、尽量保留 YAML 注释和格式、合并多份文档、拆分输出、处理 front matter，以及在不同格式之间转换。

快速使用

在 macOS 或 Linux 上通过 Homebrew 安装：

brew install yq

也可以从最新发布页下载对应平台的二进制文件。Linux x86_64 可以直接放到 PATH 中：

wget https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64 -O /usr/local/bin/yq && chmod +x /usr/local/bin/yq

假设有 file.yaml，读取嵌套字段：

yq '.a.b[0].c' file.yaml

原地修改：

yq -i '.a.b[0].c = "cool"' file.yaml

把 YAML 转成 JSON：

yq -o json file.yaml

格式通常根据文件扩展名或 STDIN 自动识别，也可以用 -p/--input-format 和 -o/--output-format 显式指定。更多命令参数见用法说明，常见转换可参考recipes。

使用约束

• YAML 注释和空白会尽量保留，但并非所有场景都能正确处理。
• 遵循 YAML 1.2，yes 和 no 不再视为布尔值；依赖 YAML 1.1 布尔行为的文件需要留意。
• 语法与 jq 相似但不完全兼容，部分参数（例如 slurp）语义不同。
• Snap 包采用严格 confinement，读写 root 文件需要通过 sudo 管道或临时文件完成。
• 官方 Docker 镜像默认不以 root 运行；需要在容器内额外安装软件时，可用 --user root 或在 Dockerfile 中切换 USER root。
• 容器镜像默认不带时区数据，使用 tz 操作符需要额外安装 tzdata。

HotRepo 点评

在 2026-11-07 的 Go 日榜中，项目记录到 16,233 stars、当日新增 7 stars，位列第 7。这只是单日快照，不能说明趋势，但更适合理解为一个已长期存在于 Go 和 Kubernetes 用户日常工具链中的成熟工具，而不是快速蹿升的新项目。

2023 年 Hacker News 讨论比星数更有信息量：评论者讨论过 yq 对锚点、未加引号版本号等棘手 YAML 写法的处理（讨论帖、示例评论），也有人与 gojq 比较 jq 兼容性和键顺序保留。实际使用中，yq 是成熟且常用的格式化/编辑工具，但面对复杂 YAML 时仍需用实际文件验证具体行为。