超时设置唯一有效位置是配置文件中的 run.timeout 字段,必须带单位(如 2m、90s),决定单次 run 最大耗时;CI 推荐 2m~5m,本地可设 10m;命令行 --timeout 优先级更高但易导致维护混乱,IDE 仅读取该配置。

超时设置在哪配:run.timeout 是唯一有效位置
golangci-lint 的超时控制只在配置文件的 run.timeout 字段生效,其他地方(比如命令行传 --timeout 但没写进配置)在 CI 或 IDE 集成中容易被忽略或覆盖。这个值决定单次 golangci-lint run 执行的最大允许耗时,超时后直接 kill 进程并返回非零退出码。
-
run.timeout值必须带单位,例如2m、90s、5m30s;写成120会报错 - CI 场景下建议设为
2m~5m:GitHub Actions 默认 runner 是 2 vCPU,太长容易卡住流水线,太短可能误杀正常扫描 - 本地开发可设更宽松(如
10m),尤其首次全量扫描老项目时,避免因缓存未命中导致假超时 - 该配置不作用于子命令如
golangci-lint help或golangci-lint version
命令行 --timeout 和配置文件 timeout 冲突吗
会冲突,且命令行参数优先级更高 —— 但仅当显式传入时才覆盖。比如你在 CI 脚本里写 golangci-lint run --timeout=1m,那 .golangci.yml 里的 run.timeout 就完全不生效。
- CI 中推荐「只在配置文件里设
run.timeout,命令行不加--timeout」:避免多处维护、降低出错概率 - 本地调试某次慢扫描时,可用
golangci-lint run --timeout=30s快速验证是否真卡死,而非改配置再重载 - 注意:
--timeout不能缩写为-t,会报错 Unknown flag - GoLand / VS Code 等 IDE 通常只读取配置文件,不识别命令行参数,所以 IDE 里超时行为完全取决于
.golangci.yml
为什么设了 timeout 还是卡住不动
常见原因是并发失控或 linter 自身 hang 住,超时机制无法触发。golangci-lint 的 timeout 是对整个 run 进程设的信号量,但如果某个 linter(比如 gocyclo)陷入无限循环,OS 层面可能无法及时响应 SIGTERM。
- 加
run.concurrency: 2:CI 环境普遍只有 2 vCPU,不设会默认用runtime.NumCPU(),导致资源争抢和调度延迟,间接让 timeout 失效 - 启用
--fast模式(或配置run.fast: true):跳过已知易 hang 的 linter(如goconst、gocyclo),保留govet、errcheck等核心项 - 检查是否启用了
typecheck:它依赖 go build cache,若 cache 损坏或模块下载卡住,timeout 可能被绕过;建议关掉:linters-settings.typecheck.enable: false - 确认没有在
run.build-tags里写错 tag,导致编译阶段卡死 —— 那个阶段 timeout 不起作用
CI 流水线里 timeout 设多少才合理
不是越短越好。观察几次干净 master 分支的平均耗时,取 P95 值再加 30 秒,是较稳妥的 baseline。硬设 30s 在中大型项目里基本等于必失败。
立即学习“go语言免费学习笔记(深入)”;
- 小型项目(1m 足够
- 中型项目(10k–50k 行):建议
2m,同时开run.cache-dir: ~/.cache/golangci-lint并在 CI 中缓存该路径 - 大型单体(>50k 行):必须分步,例如先跑
--fast+2m,再 nightly 全量跑--timeout=10m - GitHub Actions 中,如果用
golangci/golangci-lint-action@v3,它的args字段传参会覆盖配置文件 timeout,务必统一管理


















