GitHub Actions无法读取环境密钥，Vite React部署变量为空

问题描述 #

我在基于Vite的React Web应用中使用GitHub Actions工作流部署到GitHub Pages时，遇到了环境变量无法正常传递的问题。已在GitHub仓库配置好环境密钥，且在deploy.yaml和Vite配置中引用了相关变量，但VITE_EMAIL_SERVICE、VITE_EMAIL_TEMPLATE、VITE_EMAIL_SERVICE_KEY这几个变量始终无法正确传递到构建环节——调试打印步骤显示这些变量为空，而secrets.GITHUB_TOKEN能正常读取。

相关配置文件 #

.env 文件

VITE_EMAIL_TEMPLATE = "example"
VITE_EMAIL_SERVICE = "example"
VITE_EMAIL_SERVICE_KEY = "example"

deploy.yaml 文件

name: Deploy

on:
  push:
    branches:
      - main

jobs:
  build:
    name: Build
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repo
        uses: actions/checkout@v3

      - name: Setup Node
        uses: actions/setup-node@v3

      - name: Install dependencies
        uses: bahmutov/npm-install@v1

      - name: Print environment variables
        env:
          VITE_EMAIL_SERVICE: ${{ secrets.VITE_EMAIL_SERVICE }}
          VITE_EMAIL_TEMPLATE: ${{ secrets.VITE_EMAIL_TEMPLATE }}
          VITE_EMAIL_SERVICE_KEY: ${{ secrets.VITE_EMAIL_SERVICE_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
            echo "VITE_EMAIL_SERVICE=$VITE_EMAIL_SERVICE"
            echo "VITE_EMAIL_TEMPLATE=$VITE_EMAIL_TEMPLATE"
            echo "VITE_EMAIL_SERVICE_KEY=$VITE_EMAIL_SERVICE_KEY"
            echo "GITHUBTOKEN=$GITHUB_TOKEN"

      - name: Build project
        run: npm run build
        env:
          VITE_EMAIL_SERVICE: ${{ secrets.VITE_EMAIL_SERVICE }}
          VITE_EMAIL_TEMPLATE: ${{ secrets.VITE_EMAIL_TEMPLATE }}
          VITE_EMAIL_SERVICE_KEY: ${{ secrets.VITE_EMAIL_SERVICE_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Upload production-ready build files
        uses: actions/upload-artifact@v3
        with:
          name: production-files
          path: ./dist

  deploy:
    name: Deploy
    needs: build
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'

    steps:
      - name: Download artifact
        uses: actions/download-artifact@v3
        with:
          name: production-files
          path: ./dist

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist

可能的原因及解决步骤 #

1. GitHub Secrets配置错误 #

• 问题：deploy.yaml中引用的secrets.VITE_EMAIL_SERVICE等变量，可能在GitHub仓库Secrets中名称拼写错误（大小写敏感），或未正确配置值。
• 解决：
  • 进入仓库的Settings > Secrets and variables > Actions页面
  • 确认三个Secret的名称与deploy.yaml中完全一致（包括大小写）
  • 检查Secret的值无多余空格、换行或格式错误

2. .env文件格式不符合Vite要求 #

• 问题：Vite解析环境变量时不允许变量名与值之间存在空格，你的.env文件中VITE_EMAIL_TEMPLATE = "example"这种格式会导致解析失败。另外，如果.env未加入.gitignore，本地测试值会被提交，覆盖GitHub Secrets的变量。
• 解决：
  • 修改.env文件格式，去掉变量名与值之间的空格：

    VITE_EMAIL_TEMPLATE="example"
    VITE_EMAIL_SERVICE="example"
    VITE_EMAIL_SERVICE_KEY="example"
    

  • 将.env添加到.gitignore中，避免本地文件干扰线上构建

3. GitHub Actions环境变量作用域问题 #

• 问题：当前在单个步骤中重复定义环境变量，可能导致变量未正确注入整个build流程。另外，若Secret权限不足（仓库级Secret需确保能被当前工作流访问）也会导致变量为空。
• 解决：
  • 将环境变量定义在jobs.build.env层级，作用于整个build job的所有步骤，避免重复配置：

    jobs:
      build:
        name: Build
        runs-on: ubuntu-latest
        env:
          VITE_EMAIL_SERVICE: ${{ secrets.VITE_EMAIL_SERVICE }}
          VITE_EMAIL_TEMPLATE: ${{ secrets.VITE_EMAIL_TEMPLATE }}
          VITE_EMAIL_SERVICE_KEY: ${{ secrets.VITE_EMAIL_SERVICE_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        steps:
          # 后续步骤无需再单独定义env
    

  • Vite默认会自动注入所有前缀为VITE_的系统环境变量，无需额外修改vite.config.js

4. 验证Vite变量注入结果 #

• 问题：若以上步骤均确认无误，可验证Vite是否在构建时正确注入变量。
• 解决：
  • 在React组件中添加调试代码：

    console.log('Email Service:', import.meta.env.VITE_EMAIL_SERVICE);
    

  • 构建后查看dist目录下的打包文件，搜索对应变量值，确认是否被正确注入

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