GitHub Actions 环境变量 #

环境变量是GitHub Actions中传递配置信息的重要方式。本节详细介绍环境变量的配置和使用。

环境变量概述 #

什么是环境变量？ #

环境变量是在工作流运行时可访问的键值对，用于：

存储配置信息
传递参数
设置运行时选项
存储敏感信息（通过Secrets）

变量作用域 #

text

工作流级 env
    │
    ├── 作业级 env
    │       │
    │       └── 步骤级 env
    │
    └── 默认环境变量（系统提供）

定义环境变量 #

工作流级 #

yaml

name: Workflow

env:
  CI: true
  NODE_VERSION: '20'
  REGISTRY: ghcr.io

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - run: echo $CI
      - run: echo $NODE_VERSION

作业级 #

yaml

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      JOB_VAR: job-value
      DATABASE_URL: postgresql://localhost:5432/test
    steps:
      - run: echo $JOB_VAR
      - run: echo $DATABASE_URL

步骤级 #

yaml

steps:
  - name: Step with env
    env:
      STEP_VAR: step-value
      API_KEY: ${{ secrets.API_KEY }}
    run: |
      echo $STEP_VAR
      echo $API_KEY

变量优先级 #

步骤级 > 作业级 > 工作流级

yaml

env:
  VAR: workflow-value

jobs:
  build:
    env:
      VAR: job-value
    steps:
      - env:
          VAR: step-value
        run: echo $VAR  # 输出: step-value
      
      - run: echo $VAR  # 输出: job-value

默认环境变量 #

GitHub Actions提供以下默认环境变量：

仓库信息 #

变量	描述
`GITHUB_REPOSITORY`	仓库所有者和名称 (owner/repo)
`GITHUB_REPOSITORY_OWNER`	仓库所有者
`GITHUB_REPOSITORY_ID`	仓库ID

工作流信息 #

变量	描述
`GITHUB_WORKFLOW`	工作流名称
`GITHUB_WORKFLOW_REF`	工作流引用
`GITHUB_WORKFLOW_SHA`	工作流SHA

运行信息 #

变量	描述
`GITHUB_RUN_ID`	运行ID
`GITHUB_RUN_NUMBER`	运行编号
`GITHUB_RUN_ATTEMPT`	运行尝试次数

事件信息 #

变量	描述
`GITHUB_EVENT_NAME`	触发事件名称
`GITHUB_EVENT_PATH`	事件payload文件路径
`GITHUB_SHA`	提交SHA
`GITHUB_REF`	分支或标签引用
`GITHUB_REF_NAME`	引用名称
`GITHUB_REF_TYPE`	引用类型 (branch/tag)

其他信息 #

变量	描述
`GITHUB_ACTOR`	触发用户
`GITHUB_TOKEN`	自动生成的令牌
`GITHUB_JOB`	当前作业ID
`GITHUB_ACTION`	当前Action ID
`GITHUB_ACTION_PATH`	Action路径
`GITHUB_ACTION_REPOSITORY`	Action仓库
`GITHUB_ACTION_REF`	Action引用
`GITHUB_WORKSPACE`	工作区路径
`GITHUB_SHA`	提交SHA
`GITHUB_SERVER_URL`	GitHub服务器URL
`GITHUB_API_URL`	GitHub API URL
`GITHUB_GRAPHQL_URL`	GitHub GraphQL URL

使用示例 #

yaml

steps:
  - name: Display GitHub context
    run: |
      echo "Repository: $GITHUB_REPOSITORY"
      echo "Workflow: $GITHUB_WORKFLOW"
      echo "Run ID: $GITHUB_RUN_ID"
      echo "Run Number: $GITHUB_RUN_NUMBER"
      echo "Event: $GITHUB_EVENT_NAME"
      echo "SHA: $GITHUB_SHA"
      echo "Ref: $GITHUB_REF"
      echo "Actor: $GITHUB_ACTOR"
      echo "Job: $GITHUB_JOB"

运行器环境变量 #

系统信息 #

变量	描述
`RUNNER_OS`	操作系统
`RUNNER_ARCH`	架构 (X64/ARM/ARM64)
`RUNNER_NAME`	运行器名称
`RUNNER_TOOL_CACHE`	工具缓存目录
`RUNNER_TEMP`	临时目录
`RUNNER_WORKSPACE`	工作区目录

使用示例 #

yaml

steps:
  - name: Display runner info
    run: |
      echo "OS: $RUNNER_OS"
      echo "Arch: $RUNNER_ARCH"
      echo "Name: $RUNNER_NAME"
      echo "Tool Cache: $RUNNER_TOOL_CACHE"
      echo "Temp: $RUNNER_TEMP"

动态设置环境变量 #

使用GITHUB_ENV #

yaml

steps:
  - name: Set env var
    run: echo "MY_VAR=hello" >> $GITHUB_ENV

  - name: Use env var
    run: echo $MY_VAR

多行环境变量 #

yaml

steps:
  - name: Set multiline env
    run: |
      {
        echo "MULTILINE_VAR<<EOF"
        echo "Line 1"
        echo "Line 2"
        echo "Line 3"
        echo "EOF"
      } >> $GITHUB_ENV

  - name: Use multiline env
    run: |
      echo "$MULTILINE_VAR"

从文件读取 #

yaml

steps:
  - name: Read from file
    run: |
      echo "FILE_CONTENT=$(cat config.json)" >> $GITHUB_ENV

  - name: Use file content
    run: echo "$FILE_CONTENT"

从命令输出设置 #

yaml

steps:
  - name: Set from command
    id: set-var
    run: echo "VERSION=$(git describe --tags)" >> $GITHUB_ENV

  - name: Use version
    run: echo "Version is $VERSION"

添加到PATH #

使用GITHUB_PATH #

yaml

steps:
  - name: Add to PATH
    run: echo "$HOME/mybin" >> $GITHUB_PATH

  - name: Use custom command
    run: my-custom-command

添加多个路径 #

yaml

steps:
  - name: Add multiple paths
    run: |
      echo "$HOME/bin" >> $GITHUB_PATH
      echo "$HOME/.local/bin" >> $GITHUB_PATH
      echo "./node_modules/.bin" >> $GITHUB_PATH

使用上下文 #

github上下文 #

yaml

steps:
  - name: Use github context
    env:
      REPO: ${{ github.repository }}
      BRANCH: ${{ github.ref_name }}
      SHA: ${{ github.sha }}
    run: |
      echo "Repository: $REPO"
      echo "Branch: $BRANCH"
      echo "SHA: $SHA"

runner上下文 #

yaml

steps:
  - name: Use runner context
    env:
      OS: ${{ runner.os }}
      ARCH: ${{ runner.arch }}
    run: |
      echo "OS: $OS"
      echo "Arch: $ARCH"

job上下文 #

yaml

jobs:
  build:
    runs-on: ubuntu-latest
    outputs:
      status: ${{ job.status }}
    steps:
      - name: Job info
        run: echo "Job status: ${{ job.status }}"

steps上下文 #

yaml

steps:
  - id: step1
    run: echo "result=success" >> $GITHUB_OUTPUT

  - name: Use step output
    run: echo "Step 1 result: ${{ steps.step1.outputs.result }}"

实际应用示例 #

配置多环境 #

yaml

name: Deploy

on:
  workflow_dispatch:
    inputs:
      environment:
        type: choice
        options:
          - staging
          - production

env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}

jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      ENVIRONMENT: ${{ github.event.inputs.environment }}
    steps:
      - name: Set environment-specific variables
        run: |
          if [ "$ENVIRONMENT" == "production" ]; then
            echo "API_URL=https://api.example.com" >> $GITHUB_ENV
            echo "DB_HOST=prod-db.example.com" >> $GITHUB_ENV
          else
            echo "API_URL=https://staging-api.example.com" >> $GITHUB_ENV
            echo "DB_HOST=staging-db.example.com" >> $GITHUB_ENV
          fi

      - name: Deploy
        run: |
          echo "Deploying to $ENVIRONMENT"
          echo "API URL: $API_URL"
          echo "DB Host: $DB_HOST"

版本管理 #

yaml

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Set version
        run: |
          if [ "${{ github.ref_type }}" == "tag" ]; then
            echo "VERSION=${{ github.ref_name }}" >> $GITHUB_ENV
          else
            echo "VERSION=$(git describe --tags --always)" >> $GITHUB_ENV
          fi

      - name: Build
        run: |
          echo "Building version $VERSION"
          npm version $VERSION
          npm run build

条件配置 #

yaml

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Configure based on OS
        run: |
          if [ "$RUNNER_OS" == "Linux" ]; then
            echo "PACKAGE_MANAGER=apt" >> $GITHUB_ENV
          elif [ "$RUNNER_OS" == "macOS" ]; then
            echo "PACKAGE_MANAGER=brew" >> $GITHUB_ENV
          elif [ "$RUNNER_OS" == "Windows" ]; then
            echo "PACKAGE_MANAGER=choco" >> $GITHUB_ENV
          fi

      - name: Install dependencies
        run: |
          echo "Using $PACKAGE_MANAGER"

最佳实践 #

1. 使用有意义的变量名 #

yaml

env:
  NODE_VERSION: '20'
  REGISTRY_URL: ghcr.io
  DEPLOY_ENVIRONMENT: production

2. 集中管理配置 #

yaml

env:
  CI: true
  NODE_VERSION: '20'
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}

jobs:
  build:
    env:
      BUILD_ENV: production

3. 不要在环境变量中存储敏感信息 #

yaml

# 错误
env:
  API_KEY: my-secret-key

# 正确
steps:
  - env:
      API_KEY: ${{ secrets.API_KEY }}

4. 使用上下文而非环境变量 #

yaml

# 推荐
- run: echo "Branch: ${{ github.ref_name }}"

# 也可以
- run: echo "Branch: $GITHUB_REF_NAME"

5. 文档化变量用途 #

yaml

env:
  # Node.js version for all jobs
  NODE_VERSION: '20'
  # Container registry URL
  REGISTRY: ghcr.io
  # Image name (repository name)
  IMAGE_NAME: ${{ github.repository }}

下一步学习 #

密钥管理 - 学习安全管理敏感信息
上下文与表达式 - 深入理解上下文
作业管理 - 学习作业配置

小结 #

环境变量分为工作流级、作业级和步骤级
GitHub提供默认环境变量
使用GITHUB_ENV动态设置环境变量
使用GITHUB_PATH添加到系统路径
变量优先级：步骤级 > 作业级 > 工作流级
不要在环境变量中存储敏感信息
使用有意义的变量名并文档化