goreleaser

GoReleaser 技能

GoReleaser 可自动化软件项目的发布流程。它会构建二进制文件、创建归档、发布到包管理器、构建 Docker 镜像并生成变更日志。

快速参考

任务	参考文件
构建配置	references/builds.md
归档（tar.gz、zip）	references/archives.md
Docker 镜像	references/docker.md
Linux 软件包（deb/rpm）	references/nfpm.md
Homebrew/Scoop/AUR	references/homebrew.md
签名和公证	references/signing.md
变更日志生成	references/changelog.md
CI/CD 集成	references/ci.md
release-please 集成	../release-please/references/release-please-goreleaser-unified-workflow.md
模板变量	references/templates.md
完整示例	references/examples.md

基本命令

# Initialize new config
goreleaser init

# Validate configuration
goreleaser check

# Test build locally (no publish)
goreleaser release --snapshot --clean

# Create release (usually run in CI)
goreleaser release

配置文件

GoReleaser 使用 .goreleaser.yaml（或 .goreleaser.yml）。启用架构验证：

# yaml-language-server: $schema=https://goreleaser.com/static/schema.json
version: 2

# Project name (defaults to directory name)
project_name: myapp

最简 Go 配置

# yaml-language-server: $schema=https://goreleaser.com/static/schema.json
version: 2

builds:
  - main: ./cmd/myapp
    binary: myapp
    goos: [linux, darwin, windows]
    goarch: [amd64, arm64]
    ldflags:
      - -s -w
      - -X main.version={{.Version}}

archives:
  - formats: [tar.gz]
    format_overrides:
      - goos: windows
        formats: [zip]

changelog:
  sort: asc
  filters:
    exclude:
      - "^docs:"
      - "^test:"

构建目标

Go（默认）

builds:
  - builder: go  # optional, default
    main: ./cmd/app
    goos: [linux, darwin, windows]
    goarch: [amd64, arm64]
    goarm: ["6", "7"]  # for ARM builds

Rust

builds:
  - builder: rust
    targets:
      - x86_64-unknown-linux-gnu
      - x86_64-apple-darwin
      - aarch64-apple-darwin

Zig

builds:
  - builder: zig
    targets:
      - x86_64-linux-gnu
      - x86_64-macos
      - aarch64-macos

预构建二进制文件

builds:
  - builder: prebuilt
    prebuilt:
      path: dist/myapp_{{ .Os }}_{{ .Arch }}/myapp{{ .Ext }}

常见模式

版本注入（Go）

builds:
  - ldflags:
      - -X main.version={{.Version}}
      - -X main.commit={{.Commit}}
      - -X main.date={{.Date}}

禁用 CGO

builds:
  - env:
      - CGO_ENABLED=0

多个二进制文件

builds:
  - id: cli
    main: ./cmd/cli
    binary: myapp
  - id: server
    main: ./cmd/server
    binary: myapp-server

发布

Homebrew Tap

brews:
  - repository:
      owner: myorg
      name: homebrew-tap
    homepage: https://example.com
    description: "My application"

Docker 镜像

dockers_v2:
  - dockerfile: Dockerfile
    images:
      - "ghcr.io/myorg/myapp:{{ .Tag }}"
      - "ghcr.io/myorg/myapp:latest"

GitHub 发布

release:
  github:
    owner: myorg
    name: myrepo
  draft: false
  prerelease: auto

环境变量

变量	用途
GITHUB_TOKEN	GitHub API 访问权限
GITLAB_TOKEN	GitLab API 访问权限
GITEA_TOKEN	Gitea API 访问权限
GORELEASER_KEY	Pro 许可证密钥

工作流

1. 初始化：goreleaser init 会创建 .goreleaser.yaml
2. 配置：根据需要编辑配置（参见参考文件）
3. 验证：goreleaser check 会验证配置
4. 测试：goreleaser release --snapshot --clean 在本地测试
5. 发布：创建标签并推送，CI 会运行 goreleaser release

release-please 集成规则

如果项目同时使用 release-please 和 GoReleaser，务必在统一工作流（同一个工作流文件）中实现它们，而不是使用分开串联的工作流。

请将 ../release-please/references/release-please-goreleaser-unified-workflow.md 作为权威集成指南。

• 首先运行 googleapis/release-please-action@v4。
• 使用其输出（release_created、tag_name）来有条件地运行 GoReleaser。
• 在运行 goreleaser release --clean 前，检出 ref: ${{ needs.release-please.outputs.tag_name }}。
• 使用 GITHUB_TOKEN，不要仅为了触发 GoReleaser 而引入自定义 PAT。

这样可以避免 GitHub Actions 令牌递归问题，也无需使用发布触发 PAT 的变通方案。

何时加载参考资料

• 设置构建：加载 references/builds.md，查看完整的构建选项
• 配置 Docker：加载 references/docker.md，了解多架构镜像
• Linux 软件包：加载 references/nfpm.md，了解 deb/rpm/apk 软件包
• 包管理器：加载 references/homebrew.md，了解 Homebrew/Scoop/AUR 等
• CI 设置：加载 references/ci.md，了解 GitHub Actions/GitLab CI
• release-please 集成：加载 ../release-please/references/release-please-goreleaser-unified-workflow.md，了解无需自定义 PAT 的统一工作流
• 模板语法：加载 references/templates.md，了解可用变量
• 完整示例：加载 references/examples.md，查看可直接复制粘贴的配置