goreleaser 默认仅响应带注释的 Git tag（git tag -a），GitHub UI 创建的轻量 tag 会被忽略；需显式配置 builds 的 goos/goarch、archives 的 name_template、changelog 的 use: file 及版本号对齐，并确保 GitHub Token 具备 contents: write 权限。
GitHub Actions 里用 goreleaser 打 Tag 前必须关掉手动触发
很多人配完 .github/workflows/release.yml 发现 push tag 后啥也没发生，其实是 goreleaser 默认只响应 git tag -a 这种带注释的 tag，而 GitHub UI 点“Draft a new release”生成的是轻量 tag（lightweight tag），goreleaser 直接忽略。
- 检查当前 tag 类型：
git show-ref --tags，如果输出里没带^{}就是轻量 tag - 强制用 annotated tag：
git tag -a v1.2.0 -m "release v1.2.0"，再git push origin v1.2.0 - 在
.goreleaser.yml里显式打开skip-untracked: false，避免因 .gitignore 漏掉 CHANGELOG.md 导致构建失败
goreleaser 的 builds 配置不写 goos/goarch 就会只打当前机器平台包
本地测试时用 goreleaser build 看起来一切正常，但 CI 里跑 goreleaser release 却只生成 linux/amd64 包——因为默认 builds 不声明目标平台，就只编译 runner 当前环境支持的那一个。
- 必须显式列出要支持的组合：
goos: ["linux", "darwin", "windows"]和goarch: ["amd64", "arm64"] - Windows 下二进制后缀自动加
.exe，但archives配置里得把name_template写成{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}{{ if eq .Os "windows" }}.exe{{ end }} - ARM64 macOS 包需要 Go 1.21+，旧版
goreleaser（v1.22 之前）会静默跳过，建议锁死goreleaser/goreleaser-action@v5
Token 权限不够导致 goreleaser 推送 Release 失败：401 或 403 错误
常见错误信息是 failed to publish artifacts: POST https://api.github.com/repos/xxx/xxx/releases: 401 Bad credentials 或 403 Resource not accessible by integration，根本原因是 GitHub Token 缺少 packages 或 contents 写权限。
- GitHub Actions 默认的
${{ secrets.GITHUB_TOKEN }}有contents: write，但仅限于本 repo；跨 org 或 private repo 发布时必须换PAT - 手动创建 Personal Access Token 时，至少勾选：
public_repo（或repo）、delete_repo（goreleaser清理 draft release 需要）、workflow - 不要把 token 写进
.goreleaser.yml，统一在 workflow 里传：github_token: ${{ secrets.RELEASE_TOKEN }}
Release 正文内容从 CHANGELOG.md 抽取但格式错乱？那是 changelog 配置没对齐
goreleaser 默认用 git log 生成 changelog，但如果你维护了手写的 CHANGELOG.md，想直接塞进 Release 描述，却出现段落粘连、标题丢失，大概率是 changelog 的 use: file 和 sort: asc 冲突，或者文件编码不是 UTF-8。
立即学习“go语言免费学习笔记（深入）”；
- 确认
.goreleaser.yml里写了：changelog: { use: file, files: ["CHANGELOG.md"] } -
CHANGELOG.md必须以## [x.y.z]开头，且该版本号要和本次 tag 完全一致（比如 tag 是v2.1.0，标题就得是## [2.1.0]） - 避免用 Windows 换行符（CRLF），CI 中可能解析失败；用
dos2unix CHANGELOG.md统一转 LF
最常被忽略的是：tag 名称里的 v 前缀必须和 CHANGELOG.md 里小节标题的 v 严格一致，少一个都抽不到内容。
