同一服务器部署Dev和Prod环境的GitHub Actions配置疑问

关键问题逐一解答 #

1. 配置文件：单文件或多文件均可 #

两种方案各有优劣，按需选择：

• 多文件方案：分别创建dev.yml和prod.yml，各自对应分支触发，逻辑拆分清晰，适合环境部署流程差异较大的场景。
• 单文件方案：在同一个YAML中通过分支判断触发不同部署逻辑，减少文件数量，适合环境流程高度相似的场景。

2. 指定分支触发对应环境 #

核心是通过on.push.branches或on.pull_request.branches配置触发分支，同时在jobs中区分环境参数（如环境名、部署路径等），确保不同分支触发对应环境的部署流程。

3. 服务器只需一个自托管Runner #

单个Runner即可支持多环境部署，GitHub Actions会自动为每个job创建独立的临时工作目录，执行过程相互隔离，不会出现分支代码干扰的问题。

4. _work目录的分支存储处理 #

无需手动维护_work目录的分支代码：每个job执行时，Runner会自动拉取对应分支的代码到独立临时目录，执行完成后默认会清理目录。若需要保留部署后的代码，直接将代码复制到服务器的不同目标目录即可（如Dev环境部署到/var/www/dev，Prod环境部署到/var/www/prod）。

具体配置示例 #

方案一：多文件配置（推荐，逻辑清晰） #

1. 生产环境配置：.github/workflows/prod.yml

基于你现有的可运行配置调整，补充部署步骤：

name: Prod Deployment

on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

permissions:
  contents: read

jobs:
  build-deploy-prod:
    runs-on: [self-hosted, linux]
    
    environment:
      name: myprod-environment
      url: https://www.mywebsite.com

    steps:
    - uses: actions/checkout@v3

    - name: Validate composer.json and composer.lock
      run: composer validate --strict

    - name: Cache Composer packages
      id: composer-cache
      uses: actions/cache@v3
      with:
        path: vendor
        # 用prod标识缓存键，避免与Dev环境缓存冲突
        key: ${{ runner.os }}-php-prod-${{ hashFiles('**/composer.lock') }}
        restore-keys: |
          ${{ runner.os }}-php-prod-
    - name: Install dependencies
      run: composer install --prefer-dist --no-progress
      
    # 部署到Prod服务器目录
    - name: Deploy to Prod directory
      run: sudo cp -r . /var/www/prod

2. 开发环境配置：.github/workflows/dev.yml

复制Prod配置，修改触发分支、环境信息、缓存键和部署目录：

name: Dev Deployment

on:
  push:
    branches: [ "dev" ]
  pull_request:
    branches: [ "dev" ]

permissions:
  contents: read

jobs:
  build-deploy-dev:
    runs-on: [self-hosted, linux]
    
    environment:
      name: mydev-environment
      url: https://dev.mywebsite.com

    steps:
    - uses: actions/checkout@v3

    - name: Validate composer.json and composer.lock
      run: composer validate --strict

    - name: Cache Composer packages
      id: composer-cache
      uses: actions/cache@v3
      with:
        path: vendor
        key: ${{ runner.os }}-php-dev-${{ hashFiles('**/composer.lock') }}
        restore-keys: |
          ${{ runner.os }}-php-dev-
    - name: Install dependencies
      run: composer install --prefer-dist --no-progress
      
    # 部署到Dev服务器目录
    - name: Deploy to Dev directory
      run: sudo cp -r . /var/www/dev

方案二：单文件配置（合并逻辑） #

若两个环境部署流程几乎一致，可通过分支判断设置环境变量，用单个YAML完成双环境部署：

name: Multi-Environment Deployment

on:
  push:
    branches: [ "main", "dev" ]
  pull_request:
    branches: [ "main", "dev" ]

permissions:
  contents: read

jobs:
  build-deploy:
    runs-on: [self-hosted, linux]
    
    # 根据当前分支设置环境变量
    env:
      DEPLOY_DIR: ${{ github.ref == 'refs/heads/main' && '/var/www/prod' || '/var/www/dev' }}
      ENV_NAME: ${{ github.ref == 'refs/heads/main' && 'myprod-environment' || 'mydev-environment' }}
      ENV_URL: ${{ github.ref == 'refs/heads/main' && 'https://www.mywebsite.com' || 'https://dev.mywebsite.com' }}

    environment:
      name: ${{ env.ENV_NAME }}
      url: ${{ env.ENV_URL }}

    steps:
    - uses: actions/checkout@v3

    - name: Validate composer.json and composer.lock
      run: composer validate --strict

    - name: Cache Composer packages
      id: composer-cache
      uses: actions/cache@v3
      with:
        path: vendor
        # 用分支名区分缓存键，避免环境间缓存冲突
        key: ${{ runner.os }}-php-${{ github.ref_name }}-${{ hashFiles('**/composer.lock') }}
        restore-keys: |
          ${{ runner.os }}-php-${{ github.ref_name }}-
    - name: Install dependencies
      run: composer install --prefer-dist --no-progress
      
    - name: Deploy to target directory
      run: sudo cp -r . ${{ env.DEPLOY_DIR }}

常见问题排查 #

• 如果dev.yml未触发：
  1. 确认dev.yml已提交到dev分支的.github/workflows目录（GitHub Actions仅执行触发分支内的workflow文件）；
  2. 检查on.push.branches配置的分支名是否与实际分支完全一致（注意大小写）；
  3. 查看GitHub仓库的Actions页面，检查触发记录及错误日志定位问题。
• 分支代码冲突：每个job都是独立执行的，Runner会为每个job拉取对应分支的代码，无需手动管理_work目录，只需确保部署到服务器的不同目录即可。
• 权限问题：部署到系统目录（如/var/www）时，需确保Runner用户拥有对应权限，或配置Runner用户无需密码执行sudo。

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