.github/workflows/ci.yml 是 GitHub Actions 的持续集成（CI）工作流配置文件，它定义了代码提交后自动执行的测试、构建、质量检查等任务。对 PHP 开发者而言，它是保障代码质量、防止回归、提升协作效率的“数字守门人”。

---

一、文件结构：YAML 的五大核心区块

▶ 1. name：工作流名称

name: PHP CI  # 显示在 GitHub Actions 页面

▶ 2. on：触发事件

on:
  push:
    branches: [ main ]      # 推送到 main 分支时触发
  pull_request:
    branches: [ main ]      # PR 到 main 分支时触发

• 常用事件：
  • push：代码推送
  • pull_request：PR 创建/更新
  • schedule：定时任务（如每日凌晨）

▶ 3. jobs：任务定义

jobs:
  test:                    # 任务 ID（可自定义）
    runs-on: ubuntu-latest # 运行环境
    steps:                 # 步骤列表
      - ...

▶ 4. steps：具体操作

每个步骤是 Action（复用模块） 或 Shell 命令：

steps:
  - name: Checkout code
    uses: actions/checkout@v4  # 官方 Action

  - name: Run tests
    run: vendor/bin/phpunit    # Shell 命令

▶ 5. strategy：矩阵测试（可选）

strategy:
  matrix:
    php-version: ['8.1', '8.2']

• 作用：并行测试多个 PHP 版本

💡 核心认知：
YAML = 事件 → 任务 → 步骤 的声明式流水线

---

二、PHP 项目典型配置（含注释）

# .github/workflows/ci.yml
name: PHP CI

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

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        php-version: ['8.1', '8.2', '8.3']  # 多版本测试

    steps:
      # 1. 拉取代码
      - name: Checkout code
        uses: actions/checkout@v4

      # 2. 安装 PHP
      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: ${{ matrix.php-version }}
          extensions: mbstring, xml, curl  # 启用扩展
          coverage: none                   # 禁用 Xdebug（加速）

      # 3. 缓存 Composer 依赖
      - name: Cache Composer packages
        uses: actions/cache@v4
        with:
          path: ~/.composer/cache
          key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.lock') }}
          restore-keys: |
            ${{ runner.os }}-composer-

      # 4. 安装依赖
      - name: Install dependencies
        run: |
          composer install --no-progress --prefer-dist --optimize-autoloader

      # 5. 代码风格检查
      - name: Check coding style
        run: vendor/bin/phpcs

      # 6. 静态分析
      - name: Static analysis
        run: vendor/bin/phpstan analyse

      # 7. 运行单元测试
      - name: Run tests
        run: vendor/bin/phpunit --coverage-text

---

三、关键机制解析

▶ 1. actions/checkout@v4

• 作用：将仓库代码拉取到 Runner 虚拟机
• 必要性：所有后续步骤依赖此步骤

▶ 2. setup-php Action

• 功能：
  • 安装指定 PHP 版本
  • 启用扩展（如 pdo_mysql）
  • 配置 php.ini
• 优势：比手动 apt install php 更可靠

▶ 3. 缓存机制（actions/cache）

• 原理：
  • 首次运行：保存 ~/.composer/cache
  • 后续运行：若 composer.lock 未变 → 直接恢复缓存
• 效果：
  • 依赖安装时间从 60s → 5s

▶ 4. 矩阵测试（matrix）

• 执行效果：
  • GitHub 自动创建 3 个并行 Job：
    • test (8.1)
    • test (8.2)
    • test (8.3)
• 价值：确保代码兼容多版本

---

四、避坑指南（新手必看）

陷阱	破局方案
YAML 缩进错误	用 2 空格缩进，禁止 Tab
忘记 checkout	所有 workflow 必须包含 actions/checkout
扩展未启用	在 setup-php 中显式声明 extensions
缓存失效	key 必须包含 hashFiles('**/composer.lock')

▶ 调试技巧

• 查看环境变量：

  - run: env | sort
  

• 临时 SSH 调试：

  - uses: mxschmitt/action-tmate@v3
  

---

五、工程价值

场景	价值
个人项目	自动捕获低级错误（如语法错误）
团队协作	PR 必须通过 CI 才能合并 → 保证主干健康
开源贡献	展示项目专业性 → 提升社区信任度

---

六、终极心法

**“ci.yml 不是配置，
而是质量的契约——

• 当你 定义矩阵，
  你在覆盖边界；
• 当你 缓存依赖，
  你在优化速度；
• 当你 强制检查，
  你在守护底线。

真正的工程能力，
始于对自动化的敬畏，
成于对细节的精控。”

---

结语

从今天起：

1. 所有 PHP 项目添加 .github/workflows/ci.yml
2. 必须包含：代码风格 + 静态分析 + 单元测试
3. 用 matrix 测试目标 PHP 版本

因为最好的代码，
不是能跑就行，
而是每次提交都经过自动化验证。