GitHub Actions无法识别配置变量，如何排查修复？

问题现象 #

在GitHub Actions工作流中：

• 硬编码环境变量（如REACT_APP_API_URL: MY_REACT_APP_API_URL）时，能正常输出变量值；
• 使用vars.REACT_APP_API_URL引用仓库预定义变量时，变量为空，输出为REACT_APP_API_URL=；
• 已在仓库Variables页面定义相关变量，但工作流无法识别。

核心错误原因 #

工作流中指定了environment: github-pages，当启用环境配置后，仓库级变量不会自动传入该环境，必须确保变量在对应环境中可见，或调整变量作用域。

修正步骤 #

方案1：将变量添加到指定环境

1. 进入仓库的「Settings」→「Environments」，找到github-pages环境；
2. 在该环境的「Variables」板块，添加REACT_APP_API_URL和CORS_ALLOWED_ORIGINS变量（与仓库级变量值一致即可）；
3. 保存后重新触发工作流，变量即可正常读取。

方案2：移除环境隔离（无需环境专属配置时）

如果不需要针对github-pages环境做隔离，直接删除工作流中的environment块：

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pages: write
      id-token: write
    # 移除以下environment配置块
    # environment:
    #   name: github-pages
    #   url: ${{ steps.deployment.outputs.page_url }}
    steps:
    # ... 后续步骤保持不变

方案3：检查变量名称大小写

GitHub变量名称严格区分大小写，确保工作流中引用的vars.REACT_APP_API_URL与仓库中定义的变量名称完全一致（比如不要写成小写的react_app_api_url）。

修正后的完整工作流示例 #

name: Deploy Frontend

env:
  REACT_APP_API_URL: ${{ vars.REACT_APP_API_URL }}
  CORS_ALLOWED_ORIGINS: ${{ vars.CORS_ALLOWED_ORIGINS }}

on:
  push:
    branches: [main, staging, frontend]
    paths:
      - 'frontend/**'
      - '.github/workflows/deploy_frontend.yml'
  workflow_dispatch:

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pages: write       # 用于GitHub Pages部署
      id-token: write    # actions/deploy-pages必需权限
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
    - uses: actions/checkout@v4

    - name: Debug environment variables
      shell: bash
      run: |
        echo -e "\e[32m@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@\e[0m"
        echo -e "\e[32mREACT_APP_API_URL=${REACT_APP_API_URL}\e[0m"
        echo -e "\e[32mCORS_ALLOWED_ORIGINS=${CORS_ALLOWED_ORIGINS}\e[0m"
        env

注：已修正原debug步骤中重复输出REACT_APP_API_URL的笔误

内容的提问来源于stack exchange，提问作者Gulzar