go项目github actions报“cannot find module”主因是工作目录错误或go111module未启用：确保go.mod在当前目录（勿cd子目录）、显式设goproxy、用working-directory指定路径，而非手动cd。
Go 项目在 GitHub Actions 上跑不起来，90% 是因为没搞清模块路径和环境变量的默认行为，不是配置写得不够多。
go test ./ 报 “cannot find module” 怎么办
这不是代码问题，是工作目录或模块启用状态不对。GitHub Actions 的 actions/checkout@v4 拉下来的是整个仓库，但如果你的 go.mod 不在根目录（比如在 src/ 或 cmd/myapp/），go test ./ 就会找不到模块。
- 确认
go.mod文件真实存在于工作流运行时的当前目录下——最简单方法是在run步骤开头加ls -la和pwd - 不要在
actions/checkout后手动cd到子目录；改用working-directory参数指定测试路径，例如：working-directory: ./cmd/myapp - 显式设置
GOPROXY=https://proxy.golang.org,direct（国内可换为https://goproxy.cn），避免因代理为空导致拉包失败却不报错 - Go 1.16+ 默认启用 modules，但若项目历史较老、
GO111MODULE被意外关闭，可在env中强制设为on
要不要加 go mod download
绝大多数情况下不用，加了反而容易出问题。
Convert Github Repository
下载
适用于以下场景：（1）用户提供 GitHub 仓库 URL 或本地仓库路径，并请求将其转换为其他格式；（2）用户请求导出 GitHub 仓库……
-
go test、go build会自动触发依赖解析和下载，手动加go mod download属于冗余操作 - 如果用了
actions/cache@v4缓存/home/runner/go/pkg/mod，那go mod download更没必要——缓存已覆盖下载环节 - 唯一需要它的场景：私有 registry + 首次构建无缓存，且你想把失败提前暴露在单独步骤里（便于定位网络问题）
- 错误写法：
run: go mod download && go test ./——这会让后续命令继承前一个命令的失败状态，掩盖真实错误
race 测试总失败，是代码有问题吗
大概率不是。GitHub-hosted runner 的内存限制（ubuntu-latest 默认约 7GB）会让 -race 很容易 OOM，尤其在测试全包（./...）时。
- 只在专用
test-racejob 中启用-race，别混进普通 test job - 缩小测试范围：
go test -race -short ./pkg/... -run=TestUnit，避免跑集成测试或耗内存的 benchmark - 如果仍失败，优先降级到
ubuntu-22.04（内存更大），而不是调大-gcflags或关 GC - cgo 启用时 race detector 不可用，若项目含
import "C"，需确保CGO_ENABLED=1且系统有build-essential
交叉编译生成的二进制为什么在目标机器上打不开
因为没控制 GOOS 和 GOARCH，默认构建的是 runner 当前平台（Linux x86_64）的二进制。
- 本地 macOS 开发时，
go build出来的是 Darwin 二进制，直接丢到 Linux server 上肯定报 “Exec format error” - 发布前必须显式指定：
GOOS=linux GOARCH=amd64 go build -o bin/app ./cmd/app - 含 cgo 的项目跨平台编译要额外小心：要么禁用（
CGO_ENABLED=0），要么在对应平台 runner 上构建（如用macos-latest构建 macOS 版） - 体积优化建议加
-ldflags="-s -w"，能减掉调试符号和 DWARF 信息，通常省 30%+ 体积
真正难的不是写对 YAML，而是理解每个步骤背后的真实执行环境：runner 是临时容器、go 命令的行为受当前目录和环境变量联合约束、缓存 key 写错就等于没缓存。这些细节不会报错，但会让 CI 表现得“时灵时不灵”。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
