GoReleaser 配置文件必须放在项目根目录，即与 go.mod 同级，文件名为 .goreleaser.yml 或 .goreleaser.yaml；builds 需显式声明 GOOS/GOARCH 组合；GitHub 发布需 GITHUB_TOKEN 具备 contents:write 权限；checksums 和 signs 需单独启用。
GoReleaser 配置文件放哪？.goreleaser.yml 必须在项目根目录
GoReleaser 启动时默认只认项目根目录下的 .goreleaser.yml（或 .goreleaser.yaml），不会向上递归查找，也不会读子目录里的同名文件。如果放错位置，运行 goreleaser check 会直接报错：config file ".goreleaser.yml" not found。
常见错误现象：把配置文件放在 scripts/ 或 build/ 目录下，本地能跑通但 CI 失败——因为 CI 拉的是干净 clone，工作目录就是仓库根。
- 必须放在 Git 仓库根路径，和
go.mod同级 - 文件名大小写敏感，Linux/macOS 下
.Goreleaser.yml无效 - 用
goreleaser check验证前，先确认ls -a | grep goreleaser真的列出来了
交叉编译目标平台怎么写？builds 里用 GOOS/GOARCH 组合
GoReleaser 默认只构建当前系统平台，要发 Windows、macOS、ARM64 Linux，得显式声明 builds 列表。每个条目本质是 GOOS + GOARCH 的组合，不是“平台名”字符串。
容易踩的坑：写成 darwin-arm64 或 win64 这类非标准值，GoReleaser 会静默忽略该构建项，不报错但也不产出二进制。
- 正确写法示例：
goos: windows,goarch: amd64；goos: darwin,goarch: arm64 -
goarm只对GOARCH=arm有效（不是arm64），设了也没用 - 想禁用某平台构建？删掉对应
builds条目，别加enabled: false—— 该字段已被弃用，新版直接忽略
发布到 GitHub Release 失败？检查 GITHUB_TOKEN 权限和 env 注入方式
GoReleaser 推送 release 依赖 GitHub API，失败时典型错误是：HTTP 401 Unauthorized 或 HTTP 403 Forbidden。根本原因几乎全是 token 权限不足或没传进去。
GitHub 新版 token（fine-grained）默认不带 contents: write 权限，而 GoReleaser 创建 release、上传 asset 都需要它。PAT（classic）则必须勾选 public_repo 或 repo。
- CI 中注入方式必须是环境变量：
GITHUB_TOKEN=xxx，不能写进.goreleaser.yml里硬编码 - GitHub Actions 中，要用
env: { GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} }，不是with:传参 - 本地调试时，运行前执行
export GITHUB_TOKEN=ghp_...，别指望--debug能绕过鉴权
checksum 和 signature 文件为什么没生成？checksums 和 signs 是独立模块
很多用户以为只要配了 builds，GoReleaser 就自动附带校验和与签名——其实 checksum 和签名是两个可选、需显式启用的 pipeline 步骤，不配就不会跑。
更隐蔽的问题是：即使启用了 signs，若本地没装 gpg 或没导入对应私钥，GoReleaser 会跳过签名并只打 warning，不中断流程，最终 release 页面看不到 .sig 文件。
- 开启 checksum：在配置顶层加
checksums: {}（空对象即可） - 开启签名：加
signs: [{id: default}]，并确保gpg --list-secret-keys能列出匹配的密钥 ID - 签名失败时日志里会有
skipping signing，但 exit code 仍是 0 —— 务必翻日志末尾确认
多平台发布真正的复杂点不在语法，而在每一步的隐式依赖：GPG 密钥链状态、token 权限粒度、Go 版本对 GOAMD64 等新环境变量的支持程度。这些地方不报硬错，但结果就是缺文件、少平台、release 卡住不动。
