当前位置：首页 > news >正文

GitHub Actions下载工件全攻略：从基础到高级应用

news 2026/6/28 8:11:44

GitHub Actions下载工件全攻略：从基础到高级应用

【免费下载链接】download-artifact项目地址: https://gitcode.com/gh_mirrors/do/download-artifact

在持续集成和持续部署（CI/CD）流程中，工件（Artifacts）的管理是至关重要的一环。GitHub Actions的download-artifact插件为开发者提供了强大的工件下载能力，让您能够高效地管理和复用构建产物。本文将全面解析这个工具的使用方法和最佳实践。

什么是GitHub Actions工件下载？

GitHub Actions的download-artifact是一个专门用于下载工作流中生成的文件和目录的动作。无论是编译后的二进制文件、测试报告、文档还是其他构建产物，都可以通过这个插件进行统一管理。

核心价值：

实现构建产物的跨工作流复用
支持多平台构建结果的整合
提供灵活的下载路径和命名管理

快速上手：基本下载操作

下载单个工件到当前目录

这是最简单的使用场景，适合快速获取特定构建产物：

steps: - uses: actions/download-artifact@v4 with: name: my-artifact - name: 显示下载文件结构 run: ls -R

下载到指定目录

如果需要将工件下载到特定位置，可以使用path参数：

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

高级应用场景

批量下载所有工件

当需要下载当前工作流运行中的所有工件时，可以省略name参数：

steps: - uses: actions/download-artifact@v4 with: path: path/to/artifacts

默认情况下，每个工件会被下载到以工件名命名的独立目录中。例如，如果有两个工件Artifact-A和Artifact-B，下载后的目录结构如下：

path/to/artifacts/ Artifact-A/ ... Artifact-A的内容 Artifact-B/ ... Artifact-B的内容

合并多个工件到同一目录

在多架构、多操作系统场景中，可能需要将来自不同作业的工件合并到同一目录：

jobs: upload: strategy: matrix: runs-on: [ubuntu-latest, macos-latest, windows-latest] runs-on: ${{ matrix.runs-on }} 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 runs-on: ubuntu-latest steps: - name: 下载所有工件 uses: actions/download-artifact@v4 with: path: my-artifact pattern: my-artifact-* merge-multiple: true - run: ls -R my-artifact

这种配置将产生如下目录结构：

my-artifact/ file-macos-latest.txt file-ubuntu-latest.txt file-windows-latest.txt

跨工作流和仓库下载

从其他工作流运行下载

有时候需要从不同的工作流运行中下载工件，这需要使用github-token来提升权限：

steps: - uses: actions/download-artifact@v4 with: name: my-other-artifact github-token: ${{ secrets.GH_PAT }} # 在目标仓库上具有actions:read权限的token repository: actions/toolkit run-id: 1234

关键参数详解

输入参数配置

参数名称	描述	是否必需	默认值
`name`	要下载的工件名称。如果未指定，将下载运行中的所有工件	否	-
`path`	目标路径。支持基本的波浪号扩展	否	$GITHUB_WORKSPACE
`pattern`	匹配应下载工件的glob模式。如果指定了name，则忽略此参数	否	-
`merge-multiple`	当匹配到多个工件时，改变目标目录的行为	否	false
`github-token`	用于GitHub API身份验证的GitHub令牌	否	-
`repository`	仓库所有者和仓库名称，用"/"连接	否	${{ github.repository }}
`run-id`	所需下载工件的上传工作流运行的id	否	${{ github.run_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