GitHub Actions 下载工件指南：download-artifact 插件使用详解

GitHub Actions 的 download-artifact 插件是 CI/CD 流程中管理构建产物的核心工具。本指南将详细介绍如何高效使用这个强大的下载工件功能，帮助您在自动化工作流中轻松获取所需的构建文件。

什么是 download-artifact？

download-artifact 是 GitHub Actions 官方提供的下载插件，专门用于从工作流运行中下载之前上传的构建产物。无论是单个应用构建、多平台编译结果，还是测试报告文档，都能通过这个插件快速获取。

快速开始

基础用法：下载单个工件

最简单的使用场景是下载特定名称的工件：

jobs:
  build:
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: my-artifact

指定下载目录

您可以将工件下载到指定目录：

jobs:
  build:
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: my-artifact
          path: your/destination/dir

核心功能详解

1. 下载所有工件

如果省略 name 参数，将下载当前运行的所有工件：

jobs:
  build:
    steps:
      - uses: actions/download-artifact@v4

2. 合并多个工件到同一目录

在多平台构建场景中，您可能希望将所有工件合并到同一目录：

jobs:
  build:
    steps:
      - uses: actions/download-artifact@v4
        with:
          path: path/to/artifacts
          merge-multiple: true

3. 使用模式匹配筛选工件

通过 pattern 参数可以使用 glob 模式筛选要下载的工件：

jobs:
  build:
    steps:
      - uses: actions/download-artifact@v4
        with:
          path: my-artifact
          pattern: my-artifact-*
          merge-multiple: true

高级应用场景

跨仓库下载工件

download-artifact 支持从其他仓库或工作流运行下载工件：

jobs:
  build:
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: my-other-artifact
          github-token: ${{ secrets.GH_PAT }}
          repository: actions/toolkit
          run-id: 1234

多平台构建场景

在复杂的 CI/CD 流程中，您可能需要在多个平台上构建应用：

jobs:
  upload:
    strategy:
      matrix:
        runs-on: [ubuntu-latest, macos-latest, windows-latest]
    steps:
      - name: 创建文件
        run: echo "hello from ${{ matrix.runs-on }}" > file-${{ matrix.runs-on }}.txt
      - name: 上传工件
        uses: actions/upload-artifact@v4
        with:
          name: my-artifact-${{ matrix.runs-on }}
          path: file-${{ matrix.runs-on }}.txt
  download:
    needs: upload
    steps:
      - name: 下载所有工件
        uses: actions/download-artifact@v4
        with:
          path: my-artifact
          pattern: my-artifact-*
          merge-multiple: true

配置参数详解

主要输入参数

name: 要下载的工件名称，如不指定则下载所有工件
path: 目标路径，支持基本的波浪号扩展
pattern: 用于匹配应下载工件的 glob 模式
merge-multiple: 是否将多个工件合并到同一目录
github-token: 用于 GitHub API 身份验证的令牌
repository: 目标仓库（格式：owner/repo）
run-id: 工作流运行 ID

输出参数

download-path: 工件下载的绝对路径

最佳实践和注意事项

文件权限问题

需要注意的是，工件上传过程中文件权限不会保留。所有目录权限为 755，文件权限为 644。如果需要保留权限，建议使用 tar 打包：

- name: 打包文件
  run: tar -cvf my_files.tar /path/to/my/directory
- name: 上传工件
  uses: actions/upload-artifact@v4
  with:
    name: my-artifact
    path: my_files.tar

版本兼容性

v4 版本目前不支持 GitHub Enterprise Server (GHES)
v4 版本不支持从 v3 及以下版本上传的工件

性能优化技巧

download-artifact v4 版本相比之前版本有显著性能提升，下载速度最高可提升 90%。为了获得最佳性能，建议：

使用最新的 v4 版本
合理设置 pattern 参数减少不必要的下载
在自托管运行器上配置适当的防火墙规则

常见问题解决

下载失败排查

如果下载失败，请检查：

工件名称是否正确
目标路径是否可写
跨仓库下载时是否提供了有效的 github-token

总结

download-artifact 插件是 GitHub Actions 生态系统中不可或缺的工具，通过本指南的学习，您已经掌握了从基础到高级的各种使用技巧。无论是简单的单文件下载，还是复杂的多平台构建产物管理，都能轻松应对。

记住核心要点：合理使用 pattern 和 merge-multiple 参数，正确处理跨仓库下载场景，以及注意文件权限的维护。现在就开始在您的 CI/CD 工作流中应用这些知识，享受高效的构建产物管理体验！