.golangci.yml是官方推荐的主流配置格式,因YAML支持注释、缩进即语义、IDE自动补全及schema校验;而.golangci.json虽被支持但极少使用,因JSON无注释、易语法出错、不被优先加载,且output.formats: json仅控制报告输出格式而非配置文件格式。

golangci-lint 的 .golangci.yml(不是 JSON)才是主流配置格式,官方不支持纯 JSON 配置文件;所谓“JSON 配置格式”实际指输出报告用 json 格式,或误将 YAML 配置项写成 JSON 语法导致解析失败。
为什么 .golangci.json 不被推荐使用
golangci-lint 支持 .golangci.json 作为配置文件,但实践中极少有人用,原因很实在:
- YAML 天然支持注释(
#),而 JSON 不支持——配置里要说明某条exclude-rules为什么存在,没注释等于埋雷 - 嵌套结构在 YAML 中缩进即语义,在 JSON 中靠大括号和逗号,易手抖少写逗号或错位括号,
golangci-lint run直接报failed to read config: invalid character - 所有文档、示例、IDE 插件(GoLand/VS Code)默认识别的都是
.golangci.yml,强行用 JSON 会失去自动补全和 schema 校验 - 即使你写了
.golangci.json,只要项目根目录下同时存在.golangci.yml,它就会被优先加载——JSON 文件根本不会生效
output.formats: json 是报告输出,不是配置文件格式
很多人搜“golangci-lint JSON 配置”,真正想要的是把检查结果导出为机器可读的 JSON,用于 CI 解析或后续处理。这和配置文件格式无关,而是 output.formats 的取值问题:
一个基于官方 Mailtrap Node.js SDK 构建的 ASE 技能,用于发送事务邮件并与 Mailtrap 沙盒或生产流程协作。它非常适合需要 API 驱动邮件投递、测试邮箱验证和结构化消息自动化的代理工作流。
- 必须显式设为
json,不能只写在配置里就完事:命令行必须带--out-format=json,否则仍走彩色终端输出 - JSON 输出默认不带源码上下文,想看到报错行附近的代码,得额外加
print-issued-lines: true - 路径字段
path必须是具体文件名(如report.json)或stdout;写成-或留空,会静默失败,无任何提示 - 示例最小可用配置片段(写在
.golangci.yml中):
output: format: json print-issued-lines: true <p>issues: max-issues-per-linter: 0 # 防止截断 max-same-issues: 0 # 防止合并同类项</p>
CI 中 JSON 报告失效的三个典型表现
你以为配了 format: json 就万事大吉,但在 GitHub Actions 或 Jenkins 里常遇到:
- GitHub Actions 日志里有 JSON 内容,但
actions/upload-artifact上传的report.json是空文件 → 检查是否漏了--out-format=json参数,仅配置文件里写没用 - 解析脚本报
invalid character 'F' looking for beginning of value→ 实际输出的是终端格式的FATAL错误信息,不是 JSON,说明 linter 运行失败(比如路径不存在),而你没捕获退出码 - JSON 里
path字段是./internal/foo.go,但 CI 环境工作目录是/home/runner/work/repo/repo→ 路径没标准化,建议统一用$(pwd)做前缀或改用github-actions格式避免路径歧义
真正难的不是写对 JSON 结构,而是让 JSON 输出稳定、完整、路径可靠——它本质是个管道衔接问题,不是语法问题。
golang免费学习笔记(深入):立即使用
在学习笔记中,你将探索golang的核心概念和高级技巧!










