GoReleaser 本地构建失败主因是未识别项目结构：需确保 go.mod 在当前目录、存在 main 包、builds[].main 用相对路径（如 ./cmd/myapp），并注意 git 初始化、CGO 设置及平台匹配。
GoReleaser 本地构建失败：找不到 main 包或 go.mod
本地跑 goreleaser build 或 goreleaser release --snapshot 报错，常见是 GoReleaser 根本没识别到你的项目结构。它默认在当前目录找 go.mod，且要求至少一个 main 包（哪怕只是临时的）。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 确认
go.mod在执行命令的当前目录下，不是子目录里；goreleaser不会向上递归查找 - 如果项目是多模块结构（比如有
cmd/myapp），必须在cmd/myapp目录下运行命令，或用--config指向带builds[].main配置的.goreleaser.yaml - 临时加个
main.go在根目录（内容就package main; func main(){}）能快速验证是否环境问题，但别提交 -
goreleaser build --debug会输出实际解析的go list -json结果，看它到底加载了哪些包
goreleaser release --snapshot 生成的二进制名不对或缺失
Snapshot 模式本意是“模拟发布”，但它仍会按 .goreleaser.yaml 中的 builds[].id、builds[].binary 和平台列表生成文件。名字不对，通常是配置和代码路径不匹配。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
-
builds[].main必须是相对go.mod的路径，比如./cmd/myapp，不能写成cmd/myapp（缺./会被当成模块名） -
builds[].binary默认取自main路径最后一段，但如果你改过，就得显式写对，比如binary: myapp-cli - Windows 下生成
.exe后缀是自动的，但 Linux/macOS 不会加.bin之类后缀——别指望它帮你补 - 用
goreleaser check可提前发现binary和main不一致的警告
本地调试时 changelog 为空或报 git is required
goreleaser 默认从 git 历史生成 changelog，本地没提交或没 tag 就会空，甚至卡住。它不读 CHANGELOG.md，也不接受手工输入。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 跑之前至少做一次
git init && git add . && git commit -m "init"，否则git命令直接失败 - 想跳过 changelog？在
.goreleaser.yaml里加changelog:空块，或设changelog.skip: true - Snapshot 模式下，
--rm-dist很重要：不清 dist 目录，上次失败残留的旧文件可能干扰判断 - 如果用
git worktree或子模块，goreleaser可能定位不到主仓库根目录，这时得加--workdir显式指定
交叉编译本地产物无法运行：exec format error 或 panic on startup
GoReleaser 默认开启 CGO 和系统链接，本地构建的 macOS 二进制在 Linux 容器里跑不了，反之亦然。这不是 bug，是默认行为没关干净。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 强制纯静态编译：在
builds[]下加env: ["CGO_ENABLED=0"]，尤其对 CLI 工具最稳妥 - 如果用了
cgo（比如依赖 SQLite），就不能关 CGO，得用对应平台的GOOS/GOARCH构建，本地测试时建议只构建当前平台 -
builds[].goos和goarch列表别盲目全写，先只留一个（比如["linux"]），验证通了再扩 - 用
file dist/myapp_*看生成文件的真实架构，比猜靠谱
本地测试发布真正的难点不在语法，而在 Git 状态、Go 模块边界、CGO 与目标平台三者的隐式耦合——少一个条件，goreleaser 就静默降级或报错不明。调的时候盯紧 --debug 输出里的 GOOS、main 路径和 git rev-parse 结果就行。
