goreleaser 多平台发布失败主因是 builds 未显式声明 goos/goarch 组合、Windows 二进制缺 .exe 后缀、archives.name_template 配置不当及 GITHUB_TOKEN 权限不足；需手动补全架构、规范命名、启用 checksums/sign 并正确注入 GPG 私钥。
goreleaser 本地跑通 goreleaser build --snapshot 不等于能发 Release——多平台发布失败，八成卡在配置没对齐或权限漏项上。
builds 块必须显式声明 goos/goarch 笛卡尔积
默认配置只列了 linux、darwin、windows，但没写具体架构组合，goreleaser 就只编译当前系统平台。比如你在 macOS 上跑，它不会自动生成 windows/amd64 或 linux/arm64。
-
builds下的goos和goarch必须成对出现，不能只写goos: [linux, windows]就完事 - 常见组合要手动补全：
- linux: [amd64, arm64, arm]、- darwin: [amd64, arm64]、- windows: [amd64, 386, arm64] - Windows 平台下，
builds[].binary必须带.exe后缀（如myapp.exe），否则生成的二进制在 Windows 上双击无响应 - ARM 编译慢、体积大，CI 中可临时用
skip: true跳过，但本地至少跑一次验证是否能通
archives.name_template 决定用户看到的文件名
用户下载的是 archives 打包后的归档，不是 builds 生成的原始二进制。默认 name_template: "{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}" 会输出 myapp_v1.2.3_darwin_arm64.tar.gz，但用户更习惯 myapp-1.2.3-macos-arm64.zip。
- 用
replacements映射系统名：darwin: macos、386: i386、amd64: x86_64 -
name_template里加{{ if eq .Os "windows" }}.exe{{ end }}只影响 zip 包内主文件名，不影响 tar.gz；想统一加扩展名，得配format: zip并在模板末尾加.zip - 别依赖
builds[].binary控制归档内文件名——它只影响构建时的输出名，归档名完全由archives.name_template决定 - 本地快速验证：运行
goreleaser build --snapshot --clean，检查dist/目录下的文件名是否符合预期
GITHUB_TOKEN 权限不足是 CI 中 release 失败最隐蔽原因
GitHub Actions 默认提供的 ${{ secrets.GITHUB_TOKEN }} 有 contents: write，但 goreleaser 创建 Release 需要更多权限，且错误日志只报 403 Forbidden 或 422 Validation Failed，不提示缺哪项。
初始化并管理阿里云SDK Go 客户端，涵盖 sync.Once 单例、goroutine 安全、endpoint 与 region 配置、VPC 端点及调试。
立即学习“go语言免费学习笔记（深入）”；
- 私有仓库必须手动去 Settings → Actions → General → “Workflow permissions” 改为 Read and write permissions，否则
GITHUB_TOKEN根本没权限创建 release - Public repo 需
public_repo，private repo 需repo；如果还推 Docker 镜像，额外要packages: write和id-token: write - CI 中用
echo $GITHUB_TOKEN | wc -c检查 token 是否为空或过短（正常应 >100 字符） - 本地测试可用
GITHUB_TOKEN=xxx goreleaser release --skip-publish先跑通构建，再放开--skip-publish确认权限
checksums 和 signature 不是锦上添花，而是可信发布的底线
不生成 checksums.txt 或签名文件，下游用户无法验证二进制完整性，也过不了企业安全审计。
-
checksums默认开启，但容易被注释掉；sign完全默认关闭，必须手动启用并配 GPG 私钥 -
checksums.name_template必须含{{ .ProjectName }}，否则多个版本会覆盖同一文件 - GPG key 必须是已上传到 GitHub Settings → SSH and GPG keys 的公钥对应私钥，且私钥需通过 CI secrets 注入（如
GORELEASER_SIGNING_SECRET_KEY） - 签名失败常因私钥格式不对（需 ASCII-armored、含 BEGIN PGP PRIVATE KEY BLOCK）、或 passphrase 未正确传入
真正麻烦的从来不是写配置，而是每个平台命名规则、token 权限粒度、归档模板变量作用域这些细节之间互相咬合——改错一处，整个发布链就断在你看不见的地方。
