# GitHub Actions 的工作流命令

您可以在工作流程或操作代码中运行 shell 命令时使用工作流程命令。

## 关于工作流程命令

操作可以与运行器机器进行通信，以设置环境变量，其他操作使用的输出值，将调试消息添加到输出日志和其他任务。

大多数工作流程命令使用特定格式的 `echo` 命令，而其他工作流程则通过写入文件被调用。 有关详细信息，请参阅“[环境文件](#environment-files)”。

### 工作流命令的示例

<div class="ghd-tool bash">

```bash copy
echo "::workflow-command parameter1={data},parameter2={data}::{command value}"
```

</div>

<div class="ghd-tool powershell">

```powershell copy
Write-Output "::workflow-command parameter1={data},parameter2={data}::{command value}"
```

</div>

> \[!NOTE]
> 工作流命令和参数名称不区分大小写。

> \[!WARNING]
> 如果使用命令提示符，则使用工作流命令时会忽略双引号字符 (`"`)。

## 使用工作流程命令访问工具包函数

[操作/工具包](https://github.com/actions/toolkit)包含许多可作为工作流命令执行的函数。 使用 `::` 语法来运行你的 YAML 文件中的工作流程命令；然后，通过 `stdout` 将这些命令发送给运行器。

例如，不使用代码创建错误注释，可以如下所示：

```javascript copy
core.error('Missing semicolon', {file: 'app.js', startLine: 1})
```

### 示例：为错误创建注释

可以在工作流中使用 `error` 命令来创建相同的错误注释：

<div class="ghd-tool bash">

```yaml copy
      - name: Create annotation for build error
        run: echo "::error file=app.js,line=1::Missing semicolon"
```

</div>

<div class="ghd-tool powershell">

```yaml copy
      - name: Create annotation for build error
        run: Write-Output "::error file=app.js,line=1::Missing semicolon"
```

</div>

下表显示了在工作流程中可用的工具包功能：

| 工具包函数                 | 等效工作流程命令                         |
| --------------------- | -------------------------------- |
| `core.addPath`        | 可使用环境文件 `GITHUB_PATH` 访问         |
| `core.debug`          | `debug`                          |
| `core.notice`         | `notice`                         |
| `core.error`          | `error`                          |
| `core.endGroup`       | `endgroup`                       |
| `core.exportVariable` | 可使用环境文件 `GITHUB_ENV` 访问          |
| `core.getInput`       | 可使用环境变量 `INPUT_{NAME}` 访问        |
| `core.getState`       | 可使用环境变量 `STATE_{NAME}` 访问        |
| `core.isDebug`        | 可使用环境变量 `RUNNER_DEBUG` 访问        |
| `core.summary`        | 可使用环境文件 `GITHUB_STEP_SUMMARY` 访问 |
| `core.saveState`      | 可使用环境文件 `GITHUB_STATE` 访问        |
| `core.setCommandEcho` | `echo`                           |
| `core.setFailed`      | 用作 `::error` 和 `exit 1` 的快捷键     |
| `core.setOutput`      | 可使用环境文件 `GITHUB_OUTPUT` 访问       |
| `core.setSecret`      | `add-mask`                       |
| `core.startGroup`     | `group`                          |
| `core.warning`        | `warning`                        |

## 设置调试消息

将调试消息打印到日志。 必须创建一个名为 `ACTIONS_STEP_DEBUG` 且值为 `true` 的机密，才能在日志中查看此命令设置的调试消息。 有关详细信息，请参阅“[启用调试日志记录](/zh/actions/how-tos/monitor-workflows/enable-debug-logging)”。

```text copy
::debug::{message}
```

### 示例：设置调试消息

<div class="ghd-tool bash">

```bash copy
echo "::debug::Set the Octocat variable"
```

</div>

<div class="ghd-tool powershell">

```powershell copy
Write-Output "::debug::Set the Octocat variable"
```

</div>

## 设置通知消息

创建通知消息并将该消息打印到日志。 此消息将创建注释，该注释可将消息与存储库中的特定文件相关联。 或者，消息可以指定文件中的位置。

```text copy
::notice file={name},line={line},endLine={endLine},title={title}::{message}
```

| 参数          | 值          | 必须 | 默认        |
| :---------- | :--------- | :- | :-------- |
| `title`     | 自定义标题      | 否  | 无         |
| `file`      | Filename   | 否  | `.github` |
| `col`       | 列号（从 1 开始） | 否  | 无         |
| `endColumn` | 结束列号       | 否  | 无         |
| `line`      | 行号（从 1 开始） | 否  | `1`       |
| `endLine`   | 结束行号       | 否  | `1`       |

### 示例：设置通知消息

<div class="ghd-tool bash">

```bash copy
echo "::notice file=app.js,line=1,col=5,endColumn=7::Missing semicolon"
```

</div>

<div class="ghd-tool powershell">

```powershell copy
Write-Output "::notice file=app.js,line=1,col=5,endColumn=7,title=YOUR-TITLE::Missing semicolon"
```

</div>

## 设置警告消息

创建警告消息并将该消息打印到日志。 此消息将创建注释，该注释可将消息与存储库中的特定文件相关联。 或者，消息可以指定文件中的位置。

```text copy
::warning file={name},line={line},endLine={endLine},title={title}::{message}
```

| 参数          | 值          | 必须 | 默认        |
| :---------- | :--------- | :- | :-------- |
| `title`     | 自定义标题      | 否  | 无         |
| `file`      | Filename   | 否  | `.github` |
| `col`       | 列号（从 1 开始） | 否  | 无         |
| `endColumn` | 结束列号       | 否  | 无         |
| `line`      | 行号（从 1 开始） | 否  | `1`       |
| `endLine`   | 结束行号       | 否  | `1`       |

### 示例：设置警告消息

<div class="ghd-tool bash">

```bash copy
echo "::warning file=app.js,line=1,col=5,endColumn=7,title=YOUR-TITLE::Missing semicolon"
```

</div>

<div class="ghd-tool powershell">

```powershell copy
Write-Output "::warning file=app.js,line=1,col=5,endColumn=7,title=YOUR-TITLE::Missing semicolon"
```

</div>

## 设置错误消息

创建错误消息并将该消息打印到日志。 此消息将创建注释，该注释可将消息与存储库中的特定文件相关联。 或者，消息可以指定文件中的位置。

```text copy
::error file={name},line={line},endLine={endLine},title={title}::{message}
```

| 参数          | 值          | 必须 | 默认        |
| :---------- | :--------- | :- | :-------- |
| `title`     | 自定义标题      | 否  | 无         |
| `file`      | Filename   | 否  | `.github` |
| `col`       | 列号（从 1 开始） | 否  | 无         |
| `endColumn` | 结束列号       | 否  | 无         |
| `line`      | 行号（从 1 开始） | 否  | `1`       |
| `endLine`   | 结束行号       | 否  | `1`       |

### 示例：设置错误消息

<div class="ghd-tool bash">

```bash copy
echo "::error file=app.js,line=1,col=5,endColumn=7,title=YOUR-TITLE::Missing semicolon"
```

</div>

<div class="ghd-tool powershell">

```powershell copy
Write-Output "::error file=app.js,line=1,col=5,endColumn=7,title=YOUR-TITLE::Missing semicolon"
```

</div>

## 对日志行分组

在日志中创建一个可扩展的组。 若要创建组，请使用 `group` 命令并指定一个 `title`。 在 `group` 和 `endgroup` 命令之间打印到日志的任何内容都嵌套在日志的可扩展条目中。

```text copy
::group::{title}
::endgroup::
```

### 示例：对日志行进行分组

<div class="ghd-tool bash">

```yaml copy
jobs:
  bash-example:
    runs-on: ubuntu-latest
    steps:
      - name: Group of log lines
        run: |
            echo "::group::My title"
            echo "Inside group"
            echo "::endgroup::"
```

</div>

<div class="ghd-tool powershell">

```yaml copy
jobs:
  powershell-example:
    runs-on: windows-latest
    steps:
      - name: Group of log lines
        run: |
            Write-Output "::group::My title"
            Write-Output "Inside group"
            Write-Output "::endgroup::"
```

</div>

![工作流步骤日志的屏幕截图。 第二行“我的标题”是一个展开的组。 下一行“内部组”在下面缩进。](/assets/images/help/actions/actions-log-group.png)

## 在日志中屏蔽值

```text copy
::add-mask::{value}
```

屏蔽值可阻止在日志中打印字符串或变量。 用空格分隔的每个屏蔽的词均替换为 `*` 字符。 可以使用环境变量或字符串作为掩码的 `value`。 对于每项作业中的每个值，都必须执行一次此操作。 当屏蔽某个值时，它将被视为机密，并将在运行器上进行修订。 例如，屏蔽某个值后，将无法将该值设置为输出。

### 示例：屏蔽字符串

在日志中打印 `"Mona The Octocat"` 时，你将看到 `"***"`。

<div class="ghd-tool bash">

```bash copy
echo "::add-mask::Mona The Octocat"
```

</div>

<div class="ghd-tool powershell">

```powershell copy
Write-Output "::add-mask::Mona The Octocat"
```

</div>

> \[!WARNING]
> 请确保先将机密注册到“add-mask”，然后再将其输出到生成日志中，或在任何其他工作流命令中使用它。

### 示例：屏蔽环境变量

在日志中打印变量 `MY_NAME` 或值 `"Mona The Octocat"` 时，你将看到 `"***"` 而不是 `"Mona The Octocat"`。

<div class="ghd-tool bash">

```yaml copy
jobs:
  bash-example:
    runs-on: ubuntu-latest
    env:
      MY_NAME: "Mona The Octocat"
    steps:
      - name: bash-version
        run: echo "::add-mask::$MY_NAME"
```

</div>

<div class="ghd-tool powershell">

```yaml copy
jobs:
  powershell-example:
    runs-on: windows-latest
    env:
      MY_NAME: "Mona The Octocat"
    steps:
      - name: powershell-version
        run: Write-Output "::add-mask::$env:MY_NAME"
```

</div>

### 示例：在单个作业中屏蔽生成的输出

如果不需要将机密从一个作业传递到另一个作业，则可以：

1. 生成机密（但不输出机密）。
2. 使用 `add-mask` 屏蔽。
3. 使用 `GITHUB_OUTPUT` 可将机密用于作业中的其他步骤。

<div class="ghd-tool bash">

```yaml copy
on: push
jobs:
  generate-a-secret-output:
    runs-on: ubuntu-latest
    steps:
      - id: sets-a-secret
        name: Generate, mask, and output a secret
        run: |
          the_secret=$((RANDOM))
          echo "::add-mask::$the_secret"
          echo "secret-number=$the_secret" >> "$GITHUB_OUTPUT"
      - name: Use that secret output (protected by a mask)
        run: |
          echo "the secret number is ${{ steps.sets-a-secret.outputs.secret-number }}"
```

</div>

<div class="ghd-tool powershell">

```yaml copy
on: push
jobs:
  generate-a-secret-output:
    runs-on: ubuntu-latest
    steps:
      - id: sets-a-secret
        name: Generate, mask, and output a secret
        shell: pwsh
        run: |
          Set-Variable -Name TheSecret -Value (Get-Random)
          Write-Output "::add-mask::$TheSecret"
          "secret-number=$TheSecret" >> $env:GITHUB_OUTPUT
      - name: Use that secret output (protected by a mask)
        shell: pwsh
        run: |
          Write-Output "the secret number is ${{ steps.sets-a-secret.outputs.secret-number }}"
```

</div>

### 示例：在作业或工作流之间屏蔽和传递机密

如果要在作业或工作流之间传递屏蔽的机密，则应将该机密存储在某个存储位置，然后在后续作业或工作流中检索该机密。

#### 设置

1. 设置机密存储以存储将在工作流期间生成的机密。 例如，Vault。
2. 生成用于读取和写入该机密存储的密钥。 将密钥存储为存储库机密。 在以下示例工作流中，机密名称为 `SECRET_STORE_CREDENTIALS`。 有关详细信息，请参阅“[在 GitHub Actions 中使用机密](/zh/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets)”。

#### Workflow

> \[!NOTE]
> 此工作流使用虚构机密存储 `secret-store`，其中包含虚构命令 `store-secret` 和 `retrieve-secret`。
> `some/secret-store@ 27b31702a0e7fc50959f5ad993c78deac1bdfc29` 是一个虚构的操作，用于安装 `secret-store` 应用程序并将其配置为使用 `instance` 连接到 `credentials`。

<div class="ghd-tool bash">

```yaml copy
on: push

jobs:
  secret-generator:
    runs-on: ubuntu-latest
    outputs:
      handle: ${{ steps.generate-secret.outputs.handle }}
    steps:
    - uses: some/secret-store@27b31702a0e7fc50959f5ad993c78deac1bdfc29
      with:
        credentials: ${{ secrets.SECRET_STORE_CREDENTIALS }}
        instance: ${{ secrets.SECRET_STORE_INSTANCE }}
    - name: generate secret
      id: generate-secret
      shell: bash
      run: |
        GENERATED_SECRET=$((RANDOM))
        echo "::add-mask::$GENERATED_SECRET"
        SECRET_HANDLE=$(secret-store store-secret "$GENERATED_SECRET")
        echo "handle=$SECRET_HANDLE" >> "$GITHUB_OUTPUT"
  secret-consumer:
    runs-on: macos-latest
    needs: secret-generator
    steps:
    - uses: some/secret-store@27b31702a0e7fc50959f5ad993c78deac1bdfc29
      with:
        credentials: ${{ secrets.SECRET_STORE_CREDENTIALS }}
        instance: ${{ secrets.SECRET_STORE_INSTANCE }}
    - name: use secret
      shell: bash
      run: |
        SECRET_HANDLE="${{ needs.secret-generator.outputs.handle }}"
        RETRIEVED_SECRET=$(secret-store retrieve-secret "$SECRET_HANDLE")
        echo "::add-mask::$RETRIEVED_SECRET"
        echo "We retrieved our masked secret: $RETRIEVED_SECRET"
```

</div>

<div class="ghd-tool powershell">

```yaml copy
on: push

jobs:
  secret-generator:
    runs-on: ubuntu-latest
    steps:
    - uses: some/secret-store@27b31702a0e7fc50959f5ad993c78deac1bdfc29
      with:
        credentials: ${{ secrets.SECRET_STORE_CREDENTIALS }}
        instance: ${{ secrets.SECRET_STORE_INSTANCE }}
    - name: generate secret
      shell: pwsh
      run: |
        Set-Variable -Name Generated_Secret -Value (Get-Random)
        Write-Output "::add-mask::$Generated_Secret"
        Set-Variable -Name Secret_Handle -Value (Store-Secret "$Generated_Secret")
        "handle=$Secret_Handle" >> $env:GITHUB_OUTPUT
  secret-consumer:
    runs-on: macos-latest
    needs: secret-generator
    steps:
    - uses: some/secret-store@27b31702a0e7fc50959f5ad993c78deac1bdfc29
      with:
        credentials: ${{ secrets.SECRET_STORE_CREDENTIALS }}
        instance: ${{ secrets.SECRET_STORE_INSTANCE }}
    - name: use secret
      shell: pwsh
      run: |
        Set-Variable -Name Secret_Handle -Value "${{ needs.secret-generator.outputs.handle }}"
        Set-Variable -Name Retrieved_Secret -Value (Retrieve-Secret "$Secret_Handle")
        echo "::add-mask::$Retrieved_Secret"
        echo "We retrieved our masked secret: $Retrieved_Secret"
```

</div>

## 停止和启动工作流程命令

停止处理任何工作流程命令。 此特殊命令可让您记录任何内容而不会意外运行工作流程命令。 例如，您可以停止记录，然后输出带有注释的整个脚本。

```text copy
::stop-commands::{endtoken}
```

要停止处理工作流程命令，请将唯一的令牌传递给 `stop-commands`。 要继续处理工作流程命令，请传递用于停止工作流程命令的同一令牌。

> \[!WARNING]
> 请确保你使用的令牌是随机生成的，且对每次运行唯一。

```text copy
::{endtoken}::
```

### 示例：停止和启动工作流程命令

<div class="ghd-tool bash">

```yaml copy
jobs:
  workflow-command-job:
    runs-on: ubuntu-latest
    steps:
      - name: Disable workflow commands
        run: |
          echo '::warning:: This is a warning message, to demonstrate that commands are being processed.'
          stopMarker=$(uuidgen)
          echo "::stop-commands::$stopMarker"
          echo '::warning:: This will NOT be rendered as a warning, because stop-commands has been invoked.'
          echo "::$stopMarker::"
          echo '::warning:: This is a warning again, because stop-commands has been turned off.'
```

</div>

<div class="ghd-tool powershell">

```yaml copy
jobs:
  workflow-command-job:
    runs-on: windows-latest
    steps:
      - name: Disable workflow commands
        run: |
          Write-Output '::warning:: This is a warning message, to demonstrate that commands are being processed.'
          $stopMarker = New-Guid
          Write-Output "::stop-commands::$stopMarker"
          Write-Output '::warning:: This will NOT be rendered as a warning, because stop-commands has been invoked.'
          Write-Output "::$stopMarker::"
          Write-Output '::warning:: This is a warning again, because stop-commands has been turned off.'
```

</div>

## 将值发送到预处理和后处理操作

可以通过向位于 `pre:` 的文件写入内容来创建环境变量，以便与工作流的 `post:` 或 `GITHUB_STATE` 操作共享。 例如，可以使用 `pre:` 操作创建文件，将文件位置传递给 `main:` 操作，然后使用 `post:` 操作删除该文件。 或者，可以使用 `main:` 操作创建文件，将文件位置传递给 `post:` 操作，同样使用 `post:` 操作删除文件。

如果有多个 `pre:` 或 `post:` 操作，则只能访问写入 `GITHUB_STATE` 的操作中保存的值。 有关 `post:` 操作的详细信息，请参阅“[元数据语法参考](/zh/actions/reference/workflows-and-actions/metadata-syntax#runspost)”。

`GITHUB_STATE` 文件仅在操作中可用。 保存的值将作为环境值存储，带 `STATE_` 前缀。

此示例使用 JavaScript 写入 `GITHUB_STATE` 文件。 生成的环境变量名为 `STATE_processID`，值为 `12345`：

```javascript copy
import * as fs from 'fs'
import * as os from 'os'

fs.appendFileSync(process.env.GITHUB_STATE, `processID=12345${os.EOL}`, {
  encoding: 'utf8'
})
```

然后，`STATE_processID` 变量仅可用于在 `main` 操作下运行的清理脚本。 此示例在 `main` 中运行并使用 JavaScript 显示分配给 `STATE_processID` 环境变量的值：

```javascript copy
console.log("The running PID from the main action is: " + process.env.STATE_processID);
```

## 环境文件

在工作流程执行期间，运行器生成可用于执行某些操作的临时文件。 可以使用 GitHub 的默认环境变量访问和编辑这些文件的路径。 请参阅“[变量参考](/zh/actions/reference/workflows-and-actions/variables#default-environment-variables)”。 写入这些文件时，您需要使用 UTF-8 编码，以确保正确处理命令。 多个命令可以写入同一个文件，用换行符分隔。
要在 GitHub Action 中使用环境变量，请使用特定的 GitHub Actions 命令创建或修改 `.env` 文件。

操作步骤如下：

```yaml copy
name: Example Workflow for Environment Files

on: push

jobs:
  set_and_use_env_vars:
    runs-on: ubuntu-latest
    steps:
      - name: Set environment variable
        run: echo "MY_ENV_VAR=myValue" >> $GITHUB_ENV

      - name: Use environment variable
        run: |
          echo "The value of MY_ENV_VAR is $MY_ENV_VAR"

```

另一个示例是使用它来存储生成时间戳、提交 SHA 或项目名称等元数据：

```yaml copy
steps:
  - name: Store build timestamp
    run: echo "BUILD_TIME=$(date +'%T')" >> $GITHUB_ENV

  - name: Deploy using stored timestamp
    run: echo "Deploying at $BUILD_TIME"
```

<div class="ghd-tool powershell">

> \[!NOTE]
> PowerShell 5.1 及更低版本 (`shell: powershell`) 默认不使用 UTF-8，因此必须指定 UTF-8 编码。 例如：
>
> ```yaml copy
> jobs:
>   legacy-powershell-example:
>     runs-on: windows-latest
>     steps:
>       - shell: powershell
>         run: |
>           "mypath" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append
> ```
>
> PowerShell Core 版本 6 及更高版本 (`shell: pwsh`) 默认使用 UTF-8。 例如：
>
> ```yaml copy
> jobs:
>   powershell-core-example:
>     runs-on: windows-latest
>     steps:
>       - shell: pwsh
>         run: |
>           "mypath" >> $env:GITHUB_PATH
> ```

</div>

## 设置环境变量

> \[!NOTE]
> 为了避免问题，无论所用操作系统和 shell 的行为为何，最好将环境变量视为区分大小写。

<div class="ghd-tool bash">

```bash copy
echo "{environment_variable_name}={value}" >> "$GITHUB_ENV"
```

</div>

<div class="ghd-tool powershell">

* 使用 PowerShell 版本 6 及更高版本：

  ```powershell copy
  "{environment_variable_name}={value}" >> $env:GITHUB_ENV
  ```

* 使用 PowerShell 版本 5.1 及更低版本：

  ```powershell copy
  "{environment_variable_name}={value}" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
  ```

</div>

通过定义或更新环境变量并将其写入 `GITHUB_ENV` 环境文件，可以使环境变量用于工作流程作业中的任何后续步骤。 创建或更新环境变量的步骤无法访问新值，但在作业中的所有后续步骤均可访问。

不能覆盖名为 `GITHUB_*` 和 `RUNNER_*` 的默认环境变量的值。 目前可以覆盖 `CI` 变量的值。 但是，并不能保证这总是可行。 有关默认环境变量的详细信息，请参阅 [变量参考](/zh/actions/reference/workflows-and-actions/variables#default-environment-variables)。

> \[!NOTE]
> 由于安全限制，`GITHUB_ENV` 不能用于设置 `NODE_OPTIONS` 环境变量。

### 有关将环境变量写入 `GITHUB_ENV` 的示例

<div class="ghd-tool bash">

```yaml copy
steps:
  - name: Set the value
    id: step_one
    run: |
      echo "action_state=yellow" >> "$GITHUB_ENV"
  - name: Use the value
    id: step_two
    run: |
      printf '%s\n' "$action_state" # This will output 'yellow'
```

</div>

<div class="ghd-tool powershell">

```yaml copy
steps:
  - name: Set the value
    id: step_one
    run: |
      "action_state=yellow" >> $env:GITHUB_ENV
  - name: Use the value
    id: step_two
    run: |
      Write-Output "$env:action_state" # This will output 'yellow'
```

</div>

### 多行字符串

对于多行字符串，您可以使用具有以下语法的分隔符。

```text copy
{name}<<{delimiter}
{value}
{delimiter}
```

> \[!WARNING]
> 确保您使用的分隔符不会出现在值中的一行上。 如果值是完全任意的，则不应使用此格式。 请改为将值写入文件。

#### 多行字符串的示例

此示例使用 `EOF` 作为分隔符，并将 `JSON_RESPONSE` 环境变量设置为 `curl` 响应的值。

<div class="ghd-tool bash">

```yaml copy
steps:
  - name: Set the value in bash
    id: step_one
    run: |
      {
        echo 'JSON_RESPONSE<<EOF'
        curl https://example.com
        echo EOF
      } >> "$GITHUB_ENV"
```

</div>

<div class="ghd-tool powershell">

```yaml copy
steps:
  - name: Set the value in pwsh
    id: step_one
    run: |
      $EOF = (New-Guid).Guid
      "JSON_RESPONSE<<$EOF" >> $env:GITHUB_ENV
      (Invoke-WebRequest -Uri "https://example.com").Content >> $env:GITHUB_ENV
      "$EOF" >> $env:GITHUB_ENV
    shell: pwsh
```

</div>

## 设置输出参数

设置步骤的输出参数。 请注意，此步骤需要定义一个 `id` 以稍后检索输出值。 可以使用“[多行字符串](/zh/actions/reference/workflows-and-actions/workflow-commands#multiline-strings)”部分中用于定义多行环境变量的相同技术设置多行输出值。

<div class="ghd-tool bash">

```bash copy
echo "{name}={value}" >> "$GITHUB_OUTPUT"
```

</div>

<div class="ghd-tool powershell">

```powershell copy
"{name}=value" >> $env:GITHUB_OUTPUT
```

</div>

### 有关设置输出参数的示例

<div class="ghd-tool bash">

此示例演示如何设置 `SELECTED_COLOR` 输出参数，然后检索它：

```yaml copy
      - name: Set color
        id: color-selector
        run: echo "SELECTED_COLOR=green" >> "$GITHUB_OUTPUT"
      - name: Get color
        env:
          SELECTED_COLOR: ${{ steps.color-selector.outputs.SELECTED_COLOR }}
        run: echo "The selected color is $SELECTED_COLOR"
```

</div>

<div class="ghd-tool powershell">

此示例演示如何设置 `SELECTED_COLOR` 输出参数，然后检索它：

```yaml copy
      - name: Set color
        id: color-selector
        run: |
            "SELECTED_COLOR=green" >> $env:GITHUB_OUTPUT
      - name: Get color
        env:
          SELECTED_COLOR: ${{ steps.color-selector.outputs.SELECTED_COLOR }}
        run: Write-Output "The selected color is $env:SELECTED_COLOR"
```

</div>

## 添加作业摘要

<div class="ghd-tool bash">

```bash copy
echo "{markdown content}" >> $GITHUB_STEP_SUMMARY
```

</div>

<div class="ghd-tool powershell">

```powershell copy
"{markdown content}" >> $env:GITHUB_STEP_SUMMARY
```

</div>

可以为每个作业设置自定义 Markdown，以便这些内容显示在工作流任务的摘要页上。 可以使用作业摘要来显示和分组唯一内容，例如测试结果摘要，以便查看工作流运行结果的某人无需进入日志即可查看与运行相关的重要信息，例如失败。

任务摘要支持 [GitHub 风格的 Markdown](https://github.github.com/gfm/)，您可以将某个步骤的 Markdown 内容添加到 `GITHUB_STEP_SUMMARY` 环境文件中。
`GITHUB_STEP_SUMMARY` 对于作业中的每个步骤都是唯一的。 有关 `GITHUB_STEP_SUMMARY` 引用的每步文件的详细信息，请参阅“[环境文件](#environment-files)”。

作业完成后，作业中所有步骤的摘要将分组到单个作业摘要中，并在工作流运行摘要页上显示。 如果多个作业生成摘要，则作业摘要按作业完成时间排序。

### 有关添加作业摘要的示例

<div class="ghd-tool bash">

```bash copy
echo "### Hello world! :rocket:" >> $GITHUB_STEP_SUMMARY
```

</div>

<div class="ghd-tool powershell">

```powershell copy
"### Hello world! :rocket:" >> $env:GITHUB_STEP_SUMMARY
```

</div>

![工作流运行摘要页的屏幕截图。 在“示例摘要”下是“Hello world!” 和一个火箭表情符号。](/assets/images/help/actions/actions-job-summary-simple-example.png)

### 多行 Markdown 内容

对于多行 Markdown 内容，可以使用 `>>` 为当前步骤连续附加内容。 每次追加操作时，都会自动添加换行符。

#### 多行 Markdown 内容的示例

<div class="ghd-tool bash">

```yaml
- name: Generate list using Markdown
  run: |
    echo "This is the lead in sentence for the list" >> $GITHUB_STEP_SUMMARY
    echo "" >> $GITHUB_STEP_SUMMARY # this is a blank line
    echo "- Lets add a bullet point" >> $GITHUB_STEP_SUMMARY
    echo "- Lets add a second bullet point" >> $GITHUB_STEP_SUMMARY
    echo "- How about a third one?" >> $GITHUB_STEP_SUMMARY
```

</div>

<div class="ghd-tool powershell">

```yaml
- name: Generate list using Markdown
  run: |
    "This is the lead in sentence for the list" >> $env:GITHUB_STEP_SUMMARY
    "" >> $env:GITHUB_STEP_SUMMARY # this is a blank line
    "- Lets add a bullet point" >> $env:GITHUB_STEP_SUMMARY
    "- Lets add a second bullet point" >> $env:GITHUB_STEP_SUMMARY
    "- How about a third one?" >> $env:GITHUB_STEP_SUMMARY
```

</div>

### 覆盖作业摘要

要清除当前步骤的所有内容，可以使用 `>` 覆盖 Bash 中任何以前添加的内容，或删除 PowerShell 中的 `-Append`

#### 有关覆盖作业摘要的示例

<div class="ghd-tool bash">

```yaml
- name: Overwrite Markdown
  run: |
    echo "Adding some Markdown content" >> $GITHUB_STEP_SUMMARY
    echo "There was an error, we need to clear the previous Markdown with some new content." > $GITHUB_STEP_SUMMARY
```

</div>

<div class="ghd-tool powershell">

```yaml
- name: Overwrite Markdown
  run: |
    "Adding some Markdown content" >> $env:GITHUB_STEP_SUMMARY
    "There was an error, we need to clear the previous Markdown with some new content." >> $env:GITHUB_STEP_SUMMARY
```

</div>

### 删除作业摘要

若要完全删除当前步骤的摘要，可以删除 `GITHUB_STEP_SUMMARY` 引用的文件。

#### 有关删除作业摘要的示例

<div class="ghd-tool bash">

```yaml
- name: Delete all summary content
  run: |
    echo "Adding Markdown content that we want to remove before the step ends" >> $GITHUB_STEP_SUMMARY
    rm $GITHUB_STEP_SUMMARY
```

</div>

<div class="ghd-tool powershell">

```yaml
- name: Delete all summary content
  run: |
    "Adding Markdown content that we want to remove before the step ends" >> $env:GITHUB_STEP_SUMMARY
    Remove-Item $env:GITHUB_STEP_SUMMARY
```

</div>

完成步骤后，将上传作业摘要，后续步骤无法修改以前上传的 Markdown 内容。 摘要会自动屏蔽可能意外添加的任何机密。 如果作业摘要包含必须删除的敏感信息，则可以删除整个工作流运行，以删除其所有作业摘要。 有关详细信息，请参阅“[删除工作流程运行](/zh/actions/how-tos/manage-workflow-runs/delete-a-workflow-run)”。

### 步骤隔离和限制

作业摘要在步骤之间隔离，每个步骤限制为最大大小 1MiB。 在步骤之间强制实施隔离，以便单个步骤中可能存在格式错误的 Markdown 无法中断后续步骤的 Markdown 呈现。 如果为步骤添加了超过 1MiB 的内容，则步骤的上传将失败，并且将创建错误注释。 作业摘要的上传失败不会影响步骤或作业的整体状态。 每个作业最多显示步骤中的 20 个作业摘要。

## 添加系统路径

为系统 `PATH` 变量预先设置一个目录，并自动使其可用于当前作业中的所有后续操作；当前运行的操作无法访问更新的路径变量。 要查看作业的当前定义路径，可以在步骤或操作中使用 `echo "$PATH"`。

### 有关添加系统路径的示例

<div class="ghd-tool bash">

此示例演示如何将用户 `$HOME/.local/bin` 目录添加到 `PATH`：

```bash copy
echo "$HOME/.local/bin" >> "$GITHUB_PATH"
```

</div>

<div class="ghd-tool powershell">

此示例演示如何将用户 `$env:HOMEPATH/.local/bin` 目录添加到 `PATH`：

```powershell copy
"$env:HOMEPATH/.local/bin" | Out-File -FilePath "$env:GITHUB_PATH" -Append
```

</div>