最常见原因是 Runner 未启用或 job 的 tags 不匹配；需在 GitLab UI 启用 Runner，并确保 .gitlab-ci.yml 中 tags 与注册时完全一致（区分大小写、空格敏感）。
为什么 gitlab-runner register 后不执行任务？
最常见原因是 Runner 没启用或没匹配到 job 的 tags。GitLab 不会自动调度未标记、未激活、或系统级权限不足的 Runner。
- 注册后必须手动在 GitLab UI 的
Admin Area → Runners页面点击启用（绿色开关） -
.gitlab-ci.yml中的tags必须与注册时填的 tags 完全一致（区分大小写，空格敏感） - 如果用
dockerexecutor，确认宿主机已安装并运行dockerd，且gitlab-runner用户在docker组里：sudo usermod -aG docker gitlab-runner - 检查日志：
sudo gitlab-runner --debug run或查 systemd 日志：sudo journalctl -u gitlab-runner -f
Go 项目 CI 中 go mod download 失败或超慢？
私有 Runner 默认不继承宿主机 GOPROXY 设置，且国内直连 proxy.golang.org 常被阻断。
- 在
before_script中显式设置：export GOPROXY=https://goproxy.cn,direct - 更稳妥的做法是写进 Runner 的环境变量：编辑
/etc/gitlab-runner/config.toml，在[[runners]]下加：[runners.environment] GOPROXY = "https://goproxy.cn,direct"
- 避免在
go build前反复下载依赖，可加cache配置缓存go/pkg/mod目录（注意：需用docker或shellexecutor，ssh不支持路径级 cache）
用 shell executor 跑 Go 测试为何提示 command not found: go？
shell executor 默认以非登录 shell 启动，不会加载 ~/.bashrc 或 /etc/profile，导致 PATH 缺失 Go 安装路径。
- 确认 Go 已全局安装（如
/usr/local/go/bin/go），而非仅当前用户解压使用 - 在
config.toml的[[runners]]段落中显式设置environment：[runners] environment = ["PATH=/usr/local/go/bin:/usr/bin:/bin"]
- 或者改用
dockerexecutor + 官方golang:1.22-alpine镜像，彻底规避环境差异问题
gitlab-runner 服务启动失败，日志报 Failed to load config.toml
不是文件不存在，而是格式错误——TOML 对缩进、引号、布尔值写法极其敏感，尤其从 YAML 复制配置时容易出错。
立即学习“go语言免费学习笔记（深入）”；
- 检查
config.toml是否含制表符（TOML 只认空格）；用cat -A config.toml查看隐藏字符 - 所有字符串值必须用双引号包裹，比如
url = "https://gitlab.example.com/"，单引号或无引号会解析失败 - 布尔值必须小写：
executor = "shell"✔️，privileged = true✔️，但privileged = TRUE❌ - 修改后务必用
sudo gitlab-runner verify校验配置有效性，再sudo systemctl restart gitlab-runner
config.toml 格式和 journalctl 里的第一行报错。 
