环境变量与 Secrets#

三级环境变量#

环境变量可以在 Workflow 的三个层级定义，作用范围依次缩小。当三个层级定义了同名变量时，遵循 Step > Job > Workflow 的就近原则。

# 【层级一：Workflow 级】定义在所有 jobs 之外
# 作用域：整个工作流的所有 Job 和 Step 均可读取
# ⚠️ 注意：此处定义的值为字符串，数字需加引号
env:
  APP_NAME: my-app
  NODE_VERSION: '18'

jobs:
  build:
    runs-on: ubuntu-latest

    # 【层级二：Job 级】定义在单个 job 内部、steps 之外
    # 作用域：仅当前 Job 内的所有 Step 可访问，其他 Job 不可见
    # 优先级：同名变量会覆盖 Workflow 级定义
    env:
      BUILD_MODE: production

    steps:
      - name: 显示环境变量
        # 【层级三：Step 级】定义在具体 step 的 env 字段下
        # 作用域：仅限当前 Step，执行完毕后即失效
        # 优先级：同名变量会覆盖 Job 级和 Workflow 级定义
        env:
          STEP_VAR: hello
        run: |
          echo "应用名称：$APP_NAME"         # 继承自 Workflow 级
          echo "构建模式：$BUILD_MODE"        # 来自当前 Job 级
          echo "步骤变量：$STEP_VAR"          # 仅本 Step 可用
          echo "Node 版本：$NODE_VERSION"     # 继承自 Workflow 级

环境变量层级图#

┌─────────────────────────────────────────────────────────────┐
│                    环境变量优先级（从高到低）                    │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   ┌─────────────────────────────────────────────────────┐   │
│   │  Step 级环境变量                                      │   │
│   │  定义位置：step.env                                   │   │
│   │  作用域：仅当前 Step                                  │   │
│   └─────────────────────────────────────────────────────┘   │
│                          ↑ 覆盖                             │
│   ┌─────────────────────────────────────────────────────┐   │
│   │  Job 级环境变量                                       │   │
│   │  定义位置：jobs.<job>.env                             │   │
│   │  作用域：当前 Job 的所有 Step                          │   │
│   └─────────────────────────────────────────────────────┘   │
│                          ↑ 覆盖                             │
│   ┌─────────────────────────────────────────────────────┐   │
│   │  Workflow 级环境变量                                   │   │
│   │  定义位置：顶层 env                                    │   │
│   │  作用域：所有 Job 和 Step                              │   │
│   └─────────────────────────────────────────────────────┘   │
│                                                             │
└─────────────────────────────────────────────────────────────┘

GitHub 内置变量（github 上下文）#

GitHub Actions 提供了一组内置的上下文变量，可以在任意位置通过 ${{ }} 语法引用：

steps:
  - name: 打印常用内置变量
    run: |
      echo "仓库名称：${{ github.repository }}"       # 如：your-user/your-repo
      echo "触发事件：${{ github.event_name }}"        # 如：push、pull_request
      echo "当前分支：${{ github.ref_name }}"          # 如：main、develop
      echo "提交 SHA：${{ github.sha }}"               # 当前提交的完整 SHA 哈希值
      echo "提交者：${{ github.actor }}"               # 触发此次 Workflow 的用户名
      echo "工作目录：${{ github.workspace }}"         # 代码检出后所在的目录路径
      echo "运行 ID：${{ github.run_id }}"             # 本次 Workflow 运行的唯一 ID
      echo "运行编号：${{ github.run_number }}"        # 本次运行是该 Workflow 的第几次执行

常用内置变量速查#

变量	说明	示例值
`github.repository`	仓库全名	`user/repo`
`github.event_name`	触发事件名	`push`、`pull_request`
`github.ref_name`	分支或标签名	`main`、`v1.0.0`
`github.sha`	当前提交 SHA	`a1b2c3d...`
`github.actor`	触发用户名	`john-doe`
`github.workspace`	工作目录路径	`/home/runner/work/repo/repo`
`github.run_id`	运行唯一 ID	`123456789`
`github.run_number`	运行序号	`42`

Secrets（敏感信息管理）#

密码、API 密钥、服务器地址等敏感信息不能直接写在 yml 文件中（因为代码是公开的），必须存储在 GitHub 仓库的 Secrets 中。

设置 Secrets#

进入仓库页面
点击 Settings
选择 Secrets and variables → Actions
点击 New repository secret
填写名称和值后保存

使用 Secrets#

steps:
  # 【自定义 Secret】通过 ${{ secrets.名称 }} 引用
  # Secret 值在日志中自动脱敏为 ***
  - name: 部署到服务器
    env:
      SSH_KEY: ${{ secrets.SSH_PRIVATE_KEY }}       # SSH 私钥
      SERVER_IP: ${{ secrets.DEPLOY_SERVER_IP }}    # 目标服务器 IP
    run: |
      # 将私钥写入临时文件并设置严格权限
      # SSH 要求私钥仅所有者可读（权限 600）
      echo "$SSH_KEY" > ~/.ssh/id_rsa
      chmod 600 ~/.ssh/id_rsa
      # 远程执行部署命令
      ssh user@$SERVER_IP "cd /app && git pull && pm2 restart all"

  # 【内置 Token】GITHUB_TOKEN 由 GitHub Actions 运行时自动生成
  # 生命周期仅限当前 Workflow
  # 默认拥有本仓库的读写权限（可在 Workflow permissions 中收窄）
  - name: 推送变更到仓库
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    run: |
      # 配置 bot 身份，使提交记录可追溯
      git config user.name "github-actions[bot]"
      git config user.email "github-actions[bot]@users.noreply.github.com"
      git add .
      # [skip ci] 防止本次 push 再次触发工作流，避免无限循环
      git commit -m "自动更新 [skip ci]"
      # GITHUB_TOKEN 会自动被 git credential helper 识别
      git push

⚠️ 注意

Secrets 使用注意事项

不要在日志中打印 Secret：虽然 GitHub 会自动脱敏，但不要故意输出
不要将 Secret 写入文件：除非必要（如 SSH 密钥），且要及时清理
GITHUB_TOKEN 是特殊的：它由系统自动生成，无需手动创建
定期轮换密钥：定期更新 Secret 值，提高安全性

Secrets 与环境变量的区别#

特性	Secrets	环境变量
存储位置	GitHub 仓库设置中	yml 文件中
可见性	创建后无法查看值	明文存储在代码中
日志显示	自动脱敏为 `***`	正常显示
适用场景	密码、密钥、Token	配置项、开关、版本号
跨 fork 可用	否（fork 仓库无法访问原仓库的 Secrets）	是

相关笔记：

基础概念与工作流结构 — Workflow 基础结构
矩阵构建与权限管理 — 矩阵构建和权限声明