# 使用工作流工件存储和共享数据

使用工件在工作流中的作业之间共享数据，并在工作流完成后存储数据。

## 先决条件

在完成本教程之前，需要理解工作流工件。 请参阅“[工作流工件](/zh/enterprise-server@3.22/actions/concepts/workflows-and-actions/workflow-artifacts)”。

## 上传构建和测试构件

构建和测试代码的输出通常会生成可用于调试测试失败的文件和可部署的生产代码。 您可以配置一个工作流程来构建和测试推送到仓库中的代码，并报告成功或失败状态。 您可以上传构建和测试输出，以用于部署、调试失败的测试或崩溃以及查看测试套件范围。

可以使用 `upload-artifact` 操作上传工件。 上传构件时，您可以指定单个文件或目录，或多个文件或目录。 您还可以排除某些文件或目录，以及使用通配符模式。 建议为工件命名，如果没有命名，则会使用 `artifact` 作为默认名称。 有关语法的更多信息，请参阅 `actions/upload-artifact`（位于 GitHub Enterprise Server 上）。

### 示例

例如，您的仓库或 Web 应用程序可能包含必须转换为 CSS 和 JavaScript 的 SASS 和 TypeScript 文件。 假设生成配置输出 `dist` 目录中已编译的文件，如果所有测试均已成功完成，则可将 `dist` 目录中的文件部署到 Web 应用服务器。

```text
|-- hello-world (repository)
|   └── dist
|   └── tests
|   └── src
|       └── sass/app.scss
|       └── app.ts
|   └── output
|       └── test
|
```

此示例演示了如何创建 Node.js 项目的工作流，该项目在 `src` 目录中生成代码，在 `tests` 目录中运行测试。 可以假定运行 `npm test` 会生成一个名为 `code-coverage.html`、存储在 `output/test/` 目录中的代码覆盖率报告。

工作流上传 `dist` 目录中的生产工件，但不包括任何 Markdown 文件。 它还将 `code-coverage.html` 报表作为另一个工件上传。

```yaml copy
name: Node CI

on: [push]

jobs:
  build_and_test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v6
      - name: npm install, build, and test
        run: |
          npm install
          npm run build --if-present
          npm test
      - name: Archive production artifacts
        uses: actions/upload-artifact@v3
        with:
          name: dist-without-markdown
          path: |
            dist
            !dist/**/*.md
      - name: Archive code coverage results
        uses: actions/upload-artifact@v3
        with:
          name: code-coverage-report
          path: output/test/code-coverage.html
```

## 配置自定义构件保留期

您可以为工作流程创建的单个构件自定义保留期。 使用工作流创建新工件时，可以同时使用 `retention-days` 和 `upload-artifact` 操作。 此示例演示如何为名为 `my-artifact` 的工件设置 5 天的自定义保留期：

```yaml copy
  - name: 'Upload Artifact'
    uses: actions/upload-artifact@v3
    with:
      name: my-artifact
      path: my_file.txt
      retention-days: 5
```

`retention-days` 值不能超过存储库、组织或企业设置的保留限制。

## 在工作流程运行期间下载构件

可使用 [`actions/download-artifact`](https://github.com/actions/download-artifact) 操作在工作流运行期间下载以前上传的工件。

> \[!NOTE]
> 您只能下载在同一工作流运行中上传的构件。

指定构件的名称以下载单个构件。 如果在未指定名称的情况下上传了工件，则默认名称为 `artifact`。

```yaml
- name: Download a single artifact
  uses: actions/download-artifact@v3
  with:
    name: my-artifact
```

您还可以不指定名称而下载工作流程运行中的所有构件。 如果您在处理大量工件，这会非常有用。

```yaml
- name: Download all workflow run artifacts
  uses: actions/download-artifact@v3
```

如果下载所有工作流运行的工件，则会为每个工件使用其名称创建一个目录。

有关语法的详细信息，请参阅 `actions/download-artifact` 操作（位于 GitHub Enterprise Server 上）。

## 在工作流中的作业间传递数据

可以使用 `upload-artifact` 和 `download-artifact` 操作在工作流中的作业间共享数据。 此示例工作流程说明如何在相同工作流程中的任务之间传递数据。 更多信息，请参阅 `actions/upload-artifact`以及 `download-artifact` 在 GitHub Enterprise Server 上的操作。

依赖于以前作业构件的作业必须等待依赖项成功完成。 此工作流使用 `needs` 密钥来确保 `job_1`、`job_2` 和 `job_3` 按顺序运行。 例如，`job_2` 需要 `job_1`，方法是使用 `needs: job_1` 语法。

作业1执行以下步骤：

* 执行数学计算并将结果保存到名为 `math-homework.txt` 的文本文件。
* 使用 `upload-artifact` 操作上传 `math-homework.txt` 文件，工件名称为 `homework`。

作业 2 使用上一个作业的结果：

* 下载在上一个作业中上传的 `homework` 构件。 默认情况下，`download-artifact` 操作会将工件下载到该步骤执行的工作区目录中。 可以使用 `path` 输入参数指定不同的下载目录。
* 读取 `math-homework.txt` 文件中的值，执行数学计算，并再次将结果保存到 `math-homework.txt`，覆盖其内容。
* 上传 `math-homework.txt` 文件。
  此次上传会覆盖之前上传的工件，因为它们的名称相同。

作业 3 显示上一个作业中上传的结果：

* 从作业 2 下载 `homework` 构件。
* 将数学方程式的结果打印到日志中。

在此工作流示例中执行的完整数学运算是 `(3 + 7) x 9 = 90`。

```yaml copy
name: Share data between jobs

on: [push]

jobs:
  job_1:
    name: Add 3 and 7
    runs-on: ubuntu-latest
    steps:
      - shell: bash
        run: |
          expr 3 + 7 > math-homework.txt
      - name: Upload math result for job 1
        uses: actions/upload-artifact@v3
        with:
          name: homework
          path: math-homework.txt

  job_2:
    name: Multiply by 9
    needs: job_1
    runs-on: windows-latest
    steps:
      - name: Download math result for job 1
        uses: actions/download-artifact@v3
        with:
          name: homework
      - shell: bash
        run: |
          value=`cat math-homework.txt`
          expr $value \* 9 > math-homework.txt
      - name: Upload math result for job 2
        uses: actions/upload-artifact@v3
        with:
          name: homework
          path: math-homework.txt

  job_3:
    name: Display results
    needs: job_2
    runs-on: macOS-latest
    steps:
      - name: Download math result for job 2
        uses: actions/download-artifact@v3
        with:
          name: homework
      - name: Print the final result
        shell: bash
        run: |
          value=`cat math-homework.txt`
          echo The result is $value
```

工作流程运行将会存档它生成的任何工件。 有关下载已存档项目的详细信息，请参阅“[下载工作流程构件](/zh/enterprise-server@3.22/actions/how-tos/manage-workflow-runs/download-workflow-artifacts)”。