github actions 中用 goreleaser 发布需三步：同步 go.mod 与 go.sum、.goreleaser.yml 中 name_template 正确处理 windows 后缀、settings 中开启 workflow read and write permissions。
GitHub Actions 里用 goreleaser 发 Release，不是配对就能跑通
Go 项目发 Release，goreleaser 是事实标准，但 GitHub Actions 默认环境没装它，直接写 goreleaser release 会报 command not found。必须显式安装，且得选对版本——新版 goreleaser（v2+）默认要求 Go 1.21+，而 GitHub Actions 的 ubuntu-latest 自带 Go 1.22，看似兼容，但如果你的 go.mod 里写了 go 1.19，goreleaser 会静默跳过构建。
- 用
actions/setup-go@v4显式指定 Go 版本，和go.mod保持一致 - 用
curl -sL https://git.io/goreleaser | sh安装最新稳定版（v2.x），别信文档里“自动检测”的说法 -
.goreleaser.yml里加skip: true的条件判断容易漏掉：比如env:下写- GORELEASER_CURRENT_TAG=.*会导致非 tag 推送也触发构建，应改用if: startsWith(github.ref, 'refs/tags/')在 workflow 级控制
交叉编译产物名含 GOOS/GOARCH，但默认不加扩展名，Windows 用户打不开
goreleaser 默认生成的二进制文件没后缀，比如 myapp_Windows_x86_64，用户下载后双击没反应——这不是权限问题，是 Windows 根本不认这个文件名。必须在 .goreleaser.yml 里显式配置 binary: "{{ .ProjectName }}_{{ .Os }}_{{ .Arch }}" 并追加 .exe，但注意：不能硬写 .exe，得用模板判断 {{ if eq .Os "windows" }}.exe{{ end }}，否则 Linux/macOS 产物也会多出 .exe 后缀。
-
archives:块下设name_template: "{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}{{ if eq .Os \"windows\" }}.exe{{ end }}" - 别依赖
builds[].binary，它只影响主二进制名，不影响 archive 打包后的文件名 - 本地测试时用
goreleaser build --snapshot快速验证命名逻辑，比反复 push tag 省时间
GITHUB_TOKEN 权限不够，Release 创建失败但日志只显示 403 Forbidden
GitHub Actions 默认提供的 ${{ secrets.GITHUB_TOKEN }} 有 contents: write，但 goreleaser 发 Release 需要 packages: write（如果同时推到 GitHub Packages）和 id-token: write（如果用了 OIDC）。更隐蔽的是：当仓库设为 private 时，GITHUB_TOKEN 默认无法创建 Release，必须手动在 Settings → Actions → General → “Workflow permissions” 改成 “Read and write permissions”，否则 goreleaser 报错连具体缺失哪项权限都不说。
- 检查路径：
Settings → Actions → General → Workflow permissions，勾选Read and write permissions - 如果用了
signs:或publishers:，还得额外开id-token: write - 错误日志里出现
failed to publish artifacts: POST https://api.github.com/repos/xxx/releases: 403，基本就是权限卡在这一步
Go module checksum 不匹配导致 goreleaser 构建失败，但错误指向不明
当你改了 go.mod 依赖或本地 go.sum 被意外修改，goreleaser 在 Actions 里执行 go build 时可能报 verifying github.com/xxx@v1.2.3: checksum mismatch。这不是网络问题，是 CI 环境里 go.sum 和你本地不一致。GitHub Actions 默认不会缓存 go.sum，每次都是干净环境，所以必须确保提交的 go.sum 是最新且正确的。
- CI 前先本地运行
go mod tidy && go mod verify，确认无误再 commit - workflow 中加一步
go mod download，放在setup-go之后、goreleaser之前，提前暴露校验失败 - 别在
.goreleaser.yml里写builds[].mod: readonly，它只控制go build参数，不解决go.sum校验问题
实际跑通的关键不在 YAML 写得多漂亮，而在 tag 推送前那三件事：go.mod 和 go.sum 对齐、.goreleaser.yml 里 name_template 处理好 Windows 后缀、仓库 Settings 里把 Workflow permissions 手动打开。少一个，Release 就卡在某个静默失败点。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
