应使用官方 golangci/golangci-lint-action,因其自动处理二进制缓存、PR 行级标注、working-directory 语义化控制及版本稳定性;裸跑 golangci-lint run 会缺失这些关键能力,易导致漏缓存、错版本、无法标注问题。

直接用 golangci/golangci-lint-action 官方 Action,别自己写 shell 脚本调用二进制 —— 否则容易漏缓存、错版本、不标注 PR 问题。
为什么不能直接 run: golangci-lint run?
GitHub Actions 中裸跑 golangci-lint 命令看似简单,但会跳过三个关键能力:
- PR 上的问题无法自动在代码行旁标注(
golangci/golangci-lint-action内置了 annotation 输出) - 二进制下载和缓存由 Action 自动管理;手动 install 容易因
GOBIN或权限问题失败 - 默认不支持
skip-pull-request、working-directory等语义化控制,出错时调试成本高
基础 workflow 必须包含的 4 个要素
一个能真正落地的 .github/workflows/lint.yml 至少要满足:
-
on: pull_request触发(仅检查变更文件,非全量扫描) - 使用
actions/checkout@v4+submodules: true(若项目含 submodule) -
golangci/golangci-lint-action@v3(当前稳定版,v4 尚未 GA) -
args: --timeout=5m --new-from-rev=origin/main(避免历史问题刷屏,聚焦本次改动)
常见报错:no such file or directory: .golangci.yml
这个错误不是配置文件缺失,而是 golangci-lint-action 默认在 working-directory 下找配置,而你没显式指定路径:
立即学习“go语言免费学习笔记(深入)”;
- 如果
.golangci.yml在项目根目录,加working-directory: .(显式声明更安全) - 如果配置放在
config/linters/.golangci.yml,必须设working-directory: config/linters,且确保该路径下有go.mod或能被识别为 Go module 根 - 不要依赖 “自动向上查找” —— Action 不做路径回溯,只查当前工作目录
缓存失效导致每次重装 lint 工具?
golangci/golangci-lint-action 默认会缓存二进制到 ~/.cache/golangci-lint,但以下情况会绕过缓存:
- 用了
version: latest(每次拉最新 commit,无法复用) - workflow 中设置了
skip-cache: true(调试时可开,上线必须关) - runner 环境变化(如从
ubuntu-22.04切到ubuntu-24.04,缓存路径不同)
建议始终固定版本:version: v1.54.2(截至 2026 年 10 月最新稳定版),既保兼容又稳缓存。


















