04.GoReleaser配置归档

发表于： 2026-08-02 分类于：

将二进制文件打包为归档文件、容器、系统软件包等。

本文只保留归档与源代码归档，其它软件包的构建参见： Package and Archive – GoReleaser

归档

构建好的二进制文件将与 README 和 LICENSE 文件一起打包成一个 tar.gz 文件。在 archives 部分，可以自定义归档名称、附加文件以及格式。

以下是一个带注释的 archives 部分示例，其中所有字段均已指定：

archives:
  - #
    # ID of this archive.
    #
    # Default: 'default'.
    id: my-archive

    # IDs of the builds which should be archived in this archive.
    #
    # Since "v2.8" (use 'builds' in previous versions)
    # Default: empty (include all).
    ids:
      - default

    # Archive formats.
    #
    # If format is `binary`, no archives are created and the binaries are instead
    # uploaded directly.
    #
    # Valid options are:
    # - `tar.gz`
    # - `tgz`
    # - `tar.xz`
    # - `txz`
    # - `tar.zst`
    # - `tzst` Since "v2.1"
    # - `tar`
    # - `gz`
    # - `xz` Since "v2.16"
    # - `zip`
    # - `binary`
    #
    # Default: ['tar.gz'].
    format: "zip" # Singular form, single format, deprecated.
    formats: ["zip", "tar.gz"] # Plural form, multiple formats. Since "v2.6"

    # This will create an archive without any binaries, only the files are there.
    # The name template must not contain any references to `Os`, `Arch` and etc, since the archive will be meta.
    #
    # Templates: allowed.
    meta: true

    # Archive name.
    #
    # Default:
    # - if format is `binary`:
    #   - `{{ .Binary }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}{{ with .Arm }}v{{ . }}{{ end }}{{ with .Mips }}_{{ . }}{{ end }}{{ if not (eq .Amd64 "v1") }}{{ .Amd64 }}{{ end }}`
    # - if format is anything else:
    #   - `{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}{{ with .Arm }}v{{ . }}{{ end }}{{ with .Mips }}_{{ . }}{{ end }}{{ if not (eq .Amd64 "v1") }}{{ .Amd64 }}{{ end }}`
    # Templates: allowed.
    name_template: "{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}"

    # Sets the given file info to all the binaries included from the `builds`.
    #
    # Default: copied from the source binary.
    builds_info:
      group: root
      owner: root
      mode: 0644
      # format is `time.RFC3339Nano`
      mtime: 2008-01-02T15:04:05Z

    # Set this to true if you want all files in the archive to be in a single directory.
    # If set to true and you extract the archive 'goreleaser_Linux_arm64.tar.gz',
    # you'll get a directory 'goreleaser_Linux_arm64'.
    # If set to false, all files are extracted separately.
    # You can also set it to a custom directory name (templating is supported).
    # Default: false.
    wrap_in_directory: true

    # If set to true, will strip the parent directories away from binary files.
    #
    # This might be useful if you have your binary be built with a sub-directory
    # for some reason, but do no want that sub-directory inside the archive.
    strip_binary_directory: true

    # Can be used to change the archive formats for specific GOOSs.
    # Most common use case is to archive as zip on Windows.
    format_overrides:
      - # Which GOOS to override the format for.
        goos: windows

        # The formats to use for the given GOOS.
        #
        # Valid options are:
        # - `tar.gz`
        # - `tgz`
        # - `tar.xz`
        # - `txz`
        # - `tar.zst`
        # - `tzst` # Since  "v2.1"
        # - `tar`
        # - `gz`
        # - `xz` Since "v2.16"
        # - `zip`
        # - `binary` # be extra-cautious with the file name template in this case!
        # - `none`   # skips this archive
        #
        format: "zip" # Singular form, single format, deprecated.
        formats: ["zip", "tar.gz"] # Plural form, multiple formats. Since "v2.6"

    # Additional files/globs you want to add to the archive.
    #
    # Default: [ 'LICENSE*', 'README*', 'CHANGELOG', 'license*', 'readme*', 'changelog'].
    # Templates: allowed.
    files:
      - LICENSE.txt
      - README_{{.Os}}.md
      - CHANGELOG.md
      - docs/*
      - design/*.png
      - templates/**/*
      # a more complete example, check the globbing deep dive below
      - src: "*.md"
        dst: docs

        # Strip parent directories when adding files to the archive.
        strip_parent: true

        # File info.
        # Not all fields are supported by all formats available formats.
        #
        # Default: copied from the source file.
        info:
          # Templates: allowed.
          owner: root

          # Templates: allowed.
          group: root

          # Must be in time.RFC3339Nano format.
          #
          # Templates: allowed.
          mtime: "{{ .CommitDate }}"

          # File mode.
          mode: 0644

    # Additional templated files to add to the archive.
    # Those files will have their contents pass through the template engine,
    # and its results will be added to the archive.
    #
    # This feature is only available in GoReleaser Pro.
    # Templates: allowed.
    templated_files:
      # a more complete example, check the globbing deep dive below
      - src: "LICENSE.md.tpl"
        dst: LICENSE.md

        # File info.
        # Not all fields are supported by all formats available formats.
        #
        # Default: copied from the source file.
        info:
          # Templates: allowed.
          owner: root

          # Templates: allowed.
          group: root

          # Must be in time.RFC3339Nano format.
          #
          # Templates: allowed.
          mtime: "{{ .CommitDate }}"

          # File mode.
          mode: 0644

    # Before and after hooks for each archive.
    # Skipped if archive format is binary.
    # If multiple formats are set, hooks will be executed for each format.
    # Extra template fields available: `.Format`.
    # This feature is only available in GoReleaser Pro.
    hooks:
      before:
        - make clean # simple string
        - cmd: go generate ./... # specify cmd
        - cmd: go mod tidy
          output: true # always prints command output
          dir: ./submodule # specify command working directory
        - cmd: touch {{ .Env.FILE_TO_TOUCH }}
          env:
            - "FILE_TO_TOUCH=something-{{ .ProjectName }}" # specify hook level environment variables

      after:
        - make clean
        - cmd: cat *.yaml
          dir: ./submodule
        - cmd: touch {{ .Env.RELEASE_DONE }}
          env:
            - "RELEASE_DONE=something-{{ .ProjectName }}" # specify hook level environment variables

    # Disables the binary count check.
    allow_different_binary_count: true

[NOTE] 可以使用通配符语法添加整个目录、其子目录以及其中的文件，例如：directory/**/*。

[WARNING] 如果 format 为 binary，则files 与 wrap_in_directory 选项将被忽略如果 format 设置为 binary，name_template 选项将不会反映 dist 目录下的文件名。该模板仅适用于二进制文件上传的位置（例如 GitHub 发布）。

深入探讨“globbing”选项 (Pro)

将通过一些示例，逐一说明每种情况下的具体情况。

files:
  # Adds `README.md` at the root of the archive:
  - README.md

  # Adds all `md` files to the root of the archive:
  - "*.md"

  # Adds all `md` files to the root of the archive:
  - src: "*.md"

  # Adds all `md` files in the current directory to a `docs` directory in the
  # archive:
  - src: "*.md"
    dst: docs

  # Recursively adds all `go` files to a `source` directory in the archive.
  # in this case, `cmd/myapp/main.go` will be added as `source/cmd/myapp/main.go`
  - src: "**/*.go"
    dst: source

  # Recursively adds all `go` files to a `source` directory in the archive,
  # stripping their parent directory.
  # In this case, `cmd/myapp/main.go` will be added as `source/main.go`:
  - src: "**/*.go"
    dst: source
    strip_parent: true
# ...

仅打包二进制文件

由于 GoReleaser 会在文件列表为空时始终将 README 和 LICENSE 文件添加到压缩包中，因此需要在 archives 部分提供已填充的文件列表，一个可行的技巧是使用类似以下这种方法：

archives:
  - files:
      - none*

这将添加所有符合通配符 none* 的文件；前提是系统中不存在任何符合该通配符的文件，否则仅会将二进制文件添加到归档中。任何无法匹配任何文件的通配符都应能正常工作。

关于 Gzip/XZ 的说明

Gzip 和 xz 是一种纯压缩格式，因此其中不可能包含多个文件。可以推测希望该文件是二进制文件，因此 archives 部分可能如下所示：

archives:
  # Note: Replace gz with xz for xz.
  - format: gz
    files:
      - none*

这应该会生成仅包含二进制文件的 .gz 文件，解压时应使用类似 gzip -d file.gz 的命令（如果是 xz 格式，则使用 unxz file.xz）。

不归档

如果想直接发布二进制文件，而不进行任何归档，可以将 format 设置为 binary：

archives:
  - format: binary

然后，可以设置一个自定义的 name_template，例如，该名称将在将二进制文件上传到发布版本时使用。

源代码归档

GoReleaser 可以将当前的标签源代码存档添加到发布版本中

source:
  # Whether this pipe is enabled or not.
  enabled: true

  # Name template of the final archive.
  #
  # Default: '{{ .ProjectName }}-{{ .Version }}'.
  # Templates: allowed.
  name_template: "{{ .ProjectName }}"

  # Format of the archive.
  #
  # Valid formats are: tar, tgz, tar.gz, and zip.
  #
  # Default: 'tar.gz'.
  format: "tar"

  # Prefix.
  # String to prepend to each filename in the archive.
  #
  # Templates: allowed.
  prefix_template: "{{ .ProjectName }}-{{ .Version }}/"

  # Additional files/globs you want to add to the source archive.
  #
  # Templates: allowed.
  files:
    - LICENSE.txt
    - README_{{.Os}}.md
    - CHANGELOG.md
    - docs/*
    - design/*.png
    - templates/**/*
    # a more complete example, check the globbing deep dive below
    - src: "*.md"
      dst: docs

      # Strip parent directories when adding files to the archive.
      strip_parent: true

      # File info.
      # Not all fields are supported by all formats available formats.
      # Default: file info of the source file.
      info:
        owner: root
        group: root
        mode: 0644
        # format is `time.RFC3339Nano`
        mtime: 2008-01-02T15:04:05Z

  # Additional templated files to add to the source archive.
  # Those files will have their contents pass through the template engine,
  # and its results will be added to the source archive.
  #
  # This feature is only available in GoReleaser Pro.
  # Templates: allowed.
  templated_files:
    # a more complete example, check the globbing deep dive below
    - src: "LICENSE.md.tpl"
      dst: LICENSE.md
      info:
        owner: root
        group: root
        mode: 0644
        mtime: 2008-01-02T15:04:05Z

Checksums

GoReleaser 生成一个 project_1.0.0_checksums.txt 文件并随发布版本一起上传，以便您的用户验证下载的文件是否正确。

checksum 部分允许自定义文件名：

checksum:
  # You can change the name of the checksums file.
  #
  # Default: '{{ .ProjectName }}_{{ .Version }}_checksums.txt', or,
  #   when split is set: '{{ .ArtifactName }}.{{ .Algorithm }}'.
  # Templates: allowed.
  name_template: "{{ .ProjectName }}_checksums.txt"

  # Algorithm to be used.
  #
  # Accepted options are:
  # - sha256
  # - sha512
  # - sha1
  # - crc32
  # - md5
  # - sha224
  # - sha384
  # - sha3-256
  # - sha3-512
  # - sha3-224
  # - sha3-384
  # - blake2s
  # - blake2b
  # - blake3
  #
  # Default: 'sha256'.
  algorithm: sha256

  # If true, will create one checksum file for each artifact.
  split: true

  # IDs of artifacts to include in the checksums file.
  #
  # If left empty, all published binaries, archives, linux packages and source archives
  # are included in the checksums file.
  ids:
    - foo
    - bar

  # Disable the generation/upload of the checksum file.
  disable: true

  # You can add extra pre-existing files to the checksums file.
  # The filename on the checksum will be the last part of the path (base).
  # If another file with the same name exists, the last one found will be used.
  #
  # Templates: allowed.
  extra_files:
    - glob: ./path/to/file.txt
    - glob: ./glob/**/to/**/file/**/*
    - glob: ./glob/foo/to/bar/file/foobar/override_from_previous
    - glob: ./single_file.txt
      name_template: file.txt # note that this only works if glob matches 1 file only

  # Additional templated extra files to add to the checksum.
  # Those files will have their contents pass through the template engine,
  # and its results will be added to the checksum.
  #
  # This feature is only available in GoReleaser Pro.
  # Templates: allowed.
  templated_extra_files:
    - src: LICENSE.tpl
      dst: LICENSE.txt