GitHub 操作/下载工件
4.1.8
@actions/download-artifact警告
actions/download-artifact@v3 计划于2024 年 11 月 30 日弃用。了解更多。同样，v1/v2 计划于2024 年 6 月 30 日弃用。请更新您的工作流程以使用工件操作的 v4。此弃用不会影响客户正在使用的 GitHub Enterprise Server 的任何现有版本。
从工作流程运行中下载操作工件。由 @actions/artifact 包内部供电。
另请参见上传工件。
@actions/download-artifact
权限丢失
下载单个神器
下载所有工件
将多个（已过滤的）工件下载到同一目录
从其他工作流程运行或存储库下载工件
输入
输出
改进
重大变化
v4 - 新功能
用法
示例
局限性
重要的
GHES 目前尚不支持 download-artifact@v4+。如果您使用 GHES，则必须使用 v3。
upload-artifact@v4和download-artifact@v4的发布是Artifacts后端架构的重大改变。他们有许多性能和行为方面的改进。
有关更多信息，请参阅@actions/artifact文档。
下载速度显着加快，在最坏的情况下可提高 90% 以上。
当提供 PAT 时，可以从其他工作流程运行和存储库下载工件。
在自托管运行器上，可能需要额外的防火墙规则。
不支持下载从action/upload-artifact@v3及以下版本创建的工件。
有关重大更改的帮助，请参阅 MIGRATION.md。
- 使用：actions/download-artifact@v4 with： # 要下载的工件的名称。 # 如果未指定，则下载运行的所有工件。 ＃ 选修的。 name: # 目标路径。支持基本波浪线扩展。 ＃ 选修的。默认为 $GITHUB_WORKSPACE 路径： # 应下载的工件的全局模式。 # 如果指定了名称则忽略。 ＃ 选修的。 pattern: # 当多个工件匹配时，这会更改目标目录的行为。 # 如果为 true，下载的工件将位于路径指定的同一目录中。 # 如果为 false，下载的工件将被提取到指定路径内的单独命名目录中。 ＃ 选修的。默认值为 'false' merge-multiple: # 用于通过 GitHub API 进行身份验证的 GitHub 令牌。 # 从不同的存储库或不同的工作流程运行下载工件时，这是必需的。 ＃ 选修的。如果未指定，该操作将从当前存储库和当前工作流程运行下载工件。 github-token: # 存储库所有者和存储库名称通过“/”连接在一起。 # 如果指定了 github-token，则这是将从中下载工件的存储库。 ＃ 选修的。默认为 ${{ github.repository }} repository: # 上传所需下载工件的工作流运行的 ID。 # 如果指定了 github-token，则这是将从中下载工件的运行。 ＃ 选修的。默认为 ${{ github.run_id }} 运行 ID：| 姓名 | 描述 | 例子 |
|---|---|---|
download-path | 下载工件的绝对路径 | /tmp/my/download/path |
下载到当前工作目录（ $GITHUB_WORKSPACE ）：
步骤： - 使用：actions/download-artifact@v4 with: name: my-artifact- name: 显示下载文件的结构运行：ls -R
下载到特定目录（也支持~扩展）：
步骤： - 使用：actions/download-artifact@v4 with: name: my-artifact path: your/destination/dir- name: 显示下载文件的结构 run: ls -R your/destination/dir
如果未提供name输入参数，则将下载所有工件。为了区分下载的工件，默认情况下将为每个单独的工件创建一个由工件名称表示的目录。可以使用merge-multiple输入参数更改此行为。
例如，如果有两个工件Artifact-A和Artifact-B ，并且目录为etc/usr/artifacts/ ，则目录结构将如下所示：
etc/usr/artifacts/ Artifact-A/ ... contents of Artifact-A Artifact-B/ ... contents of Artifact-B
将所有工件下载到当前工作目录：
步骤： - 使用：actions/download-artifact@v4- name：显示下载文件的结构运行：ls -R
将所有工件下载到特定目录：
步骤： - 使用：actions/download-artifact@v4 with：path：path/to/artifacts- name：显示下载文件的结构运行：ls -R path/to/artifacts
要将它们下载到同一目录：
步骤： - 使用：actions/download-artifact@v4 with：path：path/to/artifacts merge-multiple：true- name：显示下载文件的结构运行：ls -R path/to/artifacts
这将导致：
path/to/artifacts/ ... contents of Artifact-A ... contents of Artifact-B
在多个 arch/os 场景中，您可能在不同的作业中构建了 Artifacts。要将所有工件下载到同一目录（或匹配 glob 模式），您可以使用该pattern并merge-multiple输入。
作业：上传：策略：矩阵：运行：[ubuntu-latest，macos-latest，windows-latest]运行：${{matrix.runs-on}}步骤：
- name: 创建一个文件 run: echo "hello from ${{ matrix.runs-on }}" > file-${{ matrix.runs-on }}.txt
- 名称：上传工件使用：actions/upload-artifact@v4 with：名称：my-artifact-${{matrix.runs-on}}路径：file-${{matrix.runs-on}}.txt下载：需求：上传运行：ubuntu-最新步骤：
- 名称：下载所有工件 使用：actions/download-artifact@v4 与：路径：my-artifact 模式：my-artifact-* merge-multiple：true
- 运行：ls -R my-artifact这会产生一个像这样的目录：
my-artifact/ file-macos-latest.txt file-ubuntu-latest.txt file-windows-latest.txt
从其他工作流运行甚至其他存储库下载工件可能很有用。默认情况下，权限是有范围的，因此他们只能下载当前工作流程运行中的工件。要提升此场景的权限，您可以指定github-token以及其他存储库和运行标识符：
步骤：
- 使用： actions/download-artifact@v4 with: name: my-other-artifact github-token: ${{ Secrets.GH_PAT }} # token with actions: 对目标存储库的读取权限： actions/toolkit run-id: 1234在工件上传期间不会维护文件权限。所有目录将有755 ，所有文件将有644 。例如，如果您使用chmod使文件可执行，然后上传该文件，则下载后不再保证该文件被设置为可执行文件。
如果您必须保留权限，则可以在上传工件之前将所有文件tar在一起。下载后， tar文件将保持文件权限和区分大小写。
- name: 'Tar files' run: tar -cvf my_files.tar /path/to/my/directory- name: 'Upload Artifact' 使用： actions/upload-artifact@v4 with: name: my-artifact path: my_files.焦油
