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

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%。为了获得最佳性能，建议：

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

常见问题解决

下载失败排查

如果下载失败，请检查：

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

总结

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

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