根本原因是Ubuntu runner未预装goreleaser，需用官方脚本curl安装或goreleaser-action；.goreleaser.yml必须配置builds和archives；GitHub Actions需声明permissions: contents: write，并显式设置go-version和GOPROXY。
GitHub Actions 里 goreleaser 找不到 goreleaser 命令
根本原因是默认 Ubuntu runner 没装 goreleaser，得自己装。别指望 apt install goreleaser —— 官方不进系统源，装了也是旧版或报错。
实操建议：
- 用官方推荐的安装方式：在 workflow 里加一步
curl -sL https://git.io/goreleaser | sh，装到$HOME/bin - 确保
$HOME/bin在PATH里，加一句export PATH="$HOME/bin:$PATH"到后续步骤的shell环境中 - 或者更稳妥：用
goreleaser/goreleaser-action@v4官方 Action，它自动处理二进制下载和 PATH 注入
goreleaser 配置文件 .goreleaser.yml 必须定义 builds 和 archives
没配 builds，goreleaser 就不知道编译哪个 main.go；没配 archives，生成的二进制不会打包成 .tar.gz，Release 页面只有一堆裸二进制，用户难用。
常见错误现象：Release 创建成功，但点进去只有 checksums.txt，没有平台归档包。
立即学习“go语言免费学习笔记（深入）”；
实操建议：
-
builds至少指定main（如./cmd/myapp）和goos/goarch（比如["linux", "darwin"]） -
archives要开启format: tar.gz，并设name_template（例如{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}），否则 GitHub Release 上传逻辑会失败 - 如果项目有多个
main包（如 CLI + server），得显式列全，不能靠 glob 自动发现
GitHub Actions 触发 release 的时候，GITHUB_TOKEN 权限不够
GITHUB_TOKEN 默认没有 packages: write 或 contents: write 权限，而 goreleaser 创建 Release 必须写 contents。不改权限会报错：failed to publish artifacts: POST https://api.github.com/repos/xxx/releases: 403 Resource not accessible by integration
实操建议：
- 在 workflow 文件顶部加权限声明：
permissions: contents: write - 别用
secrets.GITHUB_TOKEN做变量传给 goreleaser —— 它默认就用这个 token，只要权限开对就行 - 如果还涉及上传到 GitHub Packages（如
publishers），额外加packages: write
goreleaser 构建时 GOPROXY 或 Go 版本不匹配导致依赖拉取失败
Ubuntu runner 默认 Go 版本可能太老（如 1.20），而项目用了 io/fs 或泛型语法，直接构建失败；或者公司内网没配 GOPROXY，私有模块拉不到。
实操建议：
- 在 workflow 里用
actions/setup-go@v4显式指定go-version（如'1.22'），别依赖系统自带 - 加环境变量：
GOPROXY: https://proxy.golang.org,direct（国内可换为https://goproxy.cn） - 若用 Go Modules 私有仓库，必须提前配置
git config或~/.netrc，否则go mod download卡住
最常被忽略的是 permissions 和 go-version 这两处 —— 错一个，整个 release 流水线就静默失败，日志里只显示 “exit code 1”，得翻完整 log 才能看出是权限或版本问题。
