使用 GitHub Actions 在工作流中创建 .env 文件

1. 简介

在开发应用时，我们常常需要处理配置参数、API 密钥、数据库连接地址等敏感信息。这些信息通常以 .env 文件的形式存在，供应用在运行时读取。但在使用 GitHub Actions 进行部署或测试时，如何在工作流中动态生成这样的环境文件？这就是本文要解决的问题。

本文将重点讲解：

.env 文件的基本结构
如何在 GitHub Actions 工作流中创建 .env 文件
如何安全地注入 GitHub Secrets
创建多个 .env 文件的高级用法
安全最佳实践

2. 环境文件概述

.env 文件是一种纯文本格式的配置文件，通常用于存储键值对形式的环境变量：

DATABASE_URL=postgresql://localhost:5432/myapp
API_KEY=secret-api-key
NODE_ENV=production
PORT=3000

这些变量在应用启动时被加载，使得我们可以在不同环境中使用不同的配置，而无需将敏感信息硬编码在代码中。

3. 在 GitHub Actions 中创建 .env 文件

GitHub Actions 工作流中默认没有 .env 文件。因此，我们需要在工作流中动态生成它，以便应用在构建、测试或部署时能够正常运行。

3.1. 创建简单 `.env` 文件

最简单的方式是使用 echo 命令将环境变量写入 .env 文件：

name: Build and Test
on:
  - push
  - pull_request
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3
      - name: Create .env file
        run: |
          echo "NODE_ENV=production" >> .env
          echo "PORT=3000" >> .env
          echo "DATABASE_URL=postgresql://localhost:5432/testdb" >> .env
      - name: Install dependencies
        run: npm install
      - name: Run tests
        run: npm test

✅ 这种方式适用于非敏感信息。⚠️ 注意：所有写入的内容都会在工作流日志中明文显示，因此不适用于敏感数据。

3.2. 使用 GitHub Secrets 注入敏感信息

对于敏感信息（如 API Key、数据库密码等），应使用 GitHub Secrets：

进入仓库 Settings 页面
点击 "Secrets and variables" > "Actions"
添加需要的密钥，如 API_KEY, DATABASE_URL 等

然后在工作流中使用 ${{ secrets.SECRET_NAME }} 引用它们：

name: Deploy Application
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Create .env file
        run: |
          echo "NODE_ENV=production" >> .env
          echo "DATABASE_URL=${{ secrets.DATABASE_URL }}" >> .env
          echo "API_KEY=${{ secrets.API_KEY }}" >> .env
          echo "JWT_SECRET=${{ secrets.JWT_SECRET }}" >> .env
      - name: Build application
        run: npm run build
      - name: Deploy to server
        run: npm run deploy

✅ GitHub 会自动将这些值在日志中脱敏处理，确保敏感信息不泄露。

3.3. 在后续步骤中使用 `.env` 文件

创建 .env 文件后，可以在后续步骤中通过 source 加载变量：

- name: Run app with env vars
  run: |
    source .env
    echo "Running app with API key: $API_KEY"

⚠️ 注意：.env 文件默认应在项目根目录下，否则需手动指定路径。

4. 高级用法

4.1. 创建多个 `.env` 文件

在不同部署阶段（如开发、测试、生产）可能需要不同的环境配置。此时可以创建多个 .env 文件：

- name: Create test environment file
  run: |
    echo "NODE_ENV=test" >> .env.test
    echo "DATABASE_URL=${{ secrets.TEST_DATABASE_URL }}" >> .env.test
    echo "API_KEY=${{ secrets.TEST_API_KEY }}" >> .env.test

- name: Create production environment file
  run: |
    echo "NODE_ENV=production" >> .env.production
    echo "DATABASE_URL=${{ secrets.PROD_DATABASE_URL }}" >> .env.production
    echo "API_KEY=${{ secrets.PROD_API_KEY }}" >> .env.production

✅ 这样可以实现环境隔离，提升部署安全性。

4.2. 使用条件逻辑创建配置

根据触发工作流的分支或事件动态生成配置：

- name: Create environment file
  run: |
    if [ "${{ github.ref }}" == "refs/heads/main" ]; then
      echo "NODE_ENV=production" >> .env
      echo "DATABASE_URL=${{ secrets.PROD_DATABASE_URL }}" >> .env
    else
      echo "NODE_ENV=development" >> .env
      echo "DATABASE_URL=${{ secrets.DEV_DATABASE_URL }}" >> .env
    fi

✅ 这种方式可以实现“一套流程，多环境适配”，避免重复配置。

5. 最佳实践与安全建议

不要将真实敏感信息提交到仓库中。可以用占位符代替，如 DATABASE_PASSWORD=your_password_here。
命名要清晰明确。例如使用 DATABASE_PASSWORD 而不是 SECRET1。
按环境区分密钥。如 DEV_DATABASE_URL, PROD_DATABASE_URL，避免一个密钥泄露影响全局。
定期轮换密钥。特别是生产环境，定期更新 API Key 或 Token 是安全加固的重要手段。
避免写入不必要的变量。只将真正需要的变量写入 .env，减少攻击面。
注意环境变量加载路径。如果变量未生效，检查应用是否正确读取了 .env 文件。
避免在日志中打印敏感信息。调试时可临时打印，但上线前务必删除。

6. 总结

本文介绍了如何在 GitHub Actions 工作流中动态创建 .env 文件，并结合 GitHub Secrets 安全地注入敏感信息。

通过这种方式，我们可以在 CI/CD 流程中灵活管理配置，提高部署效率和安全性。无论是单个 .env 文件还是多个环境配置，GitHub Actions 都能很好地支持。

✅ 掌握这项技能，有助于构建更健壮、更安全的自动化部署流程。

Persistence

REST

Security