必须在项目根目录创建名为.golangci.yml的配置文件，显式启用govet、errcheck、staticcheck等核心linter并禁用lll、dupl，CI和本地均需通过--config=.golangci.yml参数强制指定配置路径，确保检查行为完全一致。
团队需要统一代码检查规则并确保所有成员本地和CI中执行完全一致的golangci-lint检查，否则会出现“本地没报错、CI却失败”或“同事提交后我本地突然一堆警告”的协作断裂。
在项目根目录创建标准化配置文件
在项目根目录新建文件 .golangci.yml，这是golangci-lint默认读取的配置入口，【必须命名为该名称且位于项目根目录】。
粘贴基础团队配置（含超时、并发、核心linter启用）：
run:
timeout: 5m
concurrency: 8
modules-download-mode: readonly
linters:
enable:
- govet
- errcheck
- staticcheck
- gosimple
- unused
- ineffassign
- gosec
disable:
- lll
- dupl
issues:
max-issues-per-linter: 30
max-same-issues: 3
立即学习“go语言免费学习笔记（深入）”；
用tools.go锁定工具链版本
在项目根目录创建 tools.go 文件，内容如下：
package tools
//go:build tools
// +build tools
import (
_ "github.com/golangci/golangci-lint/cmd/golangci-lint"
)
这一步不是可选的——它把golangci-lint声明为项目“构建依赖”，让 go mod vendor 或 go install 能精准复现版本。不这样做，不同人执行 go install @latest 可能拉到不同commit，导致规则行为漂移。
执行 go mod tidy -e && go mod vendor，确保 vendor/ 下包含 golangci-lint 的确切版本代码。
配置pre-commit自动触发检查
方法一：使用 pre-commit 框架（推荐）
1. 在项目根目录创建 .pre-commit-config.yaml：
repos:
- repo: https://github.com/dnephin/pre-commit-golang
rev: v0.5.0
hooks:
- id: go-fmt
- id: go-vet
- id: golangci-lint
args: [--config=.golangci.yml]
2. 运行 pre-commit install 安装钩子；之后每次 git commit 都会自动执行 golangci-lint --config=.golangci.yml。
方法二：纯Makefile驱动（轻量级）
在 Makefile 中添加：
lint:
golangci-lint run --config=.golangci.yml
.PHONY: lint
然后在 .git/hooks/pre-commit 中写入：#!/bin/sh → make lint || exit 1，并赋予可执行权限：chmod +x .git/hooks/pre-commit。
CI中强制使用同一份配置
在GitHub Actions工作流中，明确指定配置路径和版本：
- name: Run golangci-lint
uses: golangci/golangci-lint-action@v3
with:
version: v1.56.1
args: --config=.golangci.yml --timeout=5m
注意：不要省略 --config=.golangci.yml 参数。CI默认可能读取全局配置或 fallback 到内置规则，【缺少该参数将导致CI与本地行为不一致】。
配置变更流程与同步机制
第一步：修改 .golangci.yml 并本地验证
运行 golangci-lint run --config=.golangci.yml 确认无误，观察是否引入大量历史问题——若新增linter触发过多告警，需评估是否设为warning级别或加exclude规则。
第二步：提交配置变更并附带说明
提交信息必须注明变更原因，例如：chore(lint): 启用 gosec 检查硬编码密码，排除 testdata/ 目录。
第三步：通知团队更新本地缓存
运行 go install github.com/golangci/golangci-lint/cmd/golangci-lint@v1.56.1 → golangci-lint cache clean，避免旧缓存干扰新规则生效。
