GitHub Actions 中 setup-php 的 php-version 字段不支持环境变量插值，必须硬编码（如 '8.4'）；环境变量仅可用于后续命令（如 composer config platform.php ${{ env.PHP_VERSION }}）、条件判断（if: startsWith(env.PHP_VERSION, '8.')）或本地 act 调试。
直接在 GitHub Actions 工作流中用环境变量动态传 PHP 版本是可行的，但需注意：环境变量本身不能直接替换 with: 下的 php-version 值——因为该字段不支持上下文插值（如 ${{ env.PHP_VERSION }}）；必须改用 matrix 策略或硬编码版本。真正能用环境变量控制的，是后续命令中与 PHP 版本强相关的部分，比如 composer install 的平台模拟、测试命令参数、扩展启用逻辑等。
PHP 版本必须显式声明在 setup-php 中
shivammathur/setup-php@v2 的 php-version 字段只接受字面量字符串（如 '8.3'），不接受表达式。尝试写成：
with:
php-version: ${{ env.PHP_VERSION }}
会导致工作流报错 Invalid workflow file。
✅ 正确做法是：
立即学习“PHP免费学习笔记（深入）”；
- 在
jobs.<job_id>.strategy.matrix中定义多版本测试矩阵 - 或在工作流顶层/作业级用
env:定义PHP_VERSION，仅用于后续 shell 命令（如php -v、composer config platform.php） - 若只需单版本，直接写死
php-version: '8.4'，再用环境变量同步其他环节
用环境变量统一约束 Composer 平台版本
避免因 composer.json 中 require.php 与 CI 环境不一致导致依赖安装失败。可在工作流中用环境变量驱动平台配置：
env:
PHP_VERSION: '8.4'
<p>steps:</p><ul><li><p>name: Setup PHP
uses: shivammathur/setup-php@v2
with:
php-version: '8.4'
extensions: mbstring, xml, pdo</p></li><li><p>name: Configure Composer platform
run: composer config platform.php ${{ env.PHP_VERSION }}</p></li><li><p>name: Install dependencies
uses: php-actions/composer@v6
with:
args: install --no-interaction --prefer-dist --optimize-autoloader
这样即使 composer.json 写的是 "^8.3"，Composer 也会按 8.4 解析依赖，防止装入不兼容扩展。
运行时检测与条件执行
某些扩展或命令需按 PHP 版本分支处理。可用 if + startsWith 判断：
- name: Enable opcache for PHP 8.0+
if: startsWith(env.PHP_VERSION, '8.')
run: echo "opcache.enable=1" >> $GITHUB_ENV
<ul><li>name: Skip Xdebug on PHP 8.3+
if: ${{ !startsWith(env.PHP_VERSION, '8.3') && !startsWith(env.PHP_VERSION, '8.4') }}
uses: shivammathur/setup-php@v2
with:
coverage: xdebug
注意：if 条件中可安全使用 ${{ env.PHP_VERSION }}，它在运行器上解析，不影响 YAML 结构校验。
本地调试时用 act 注入版本变量
用 act 本地运行工作流时，可通过 --env 模拟不同 PHP 版本行为：
# 测试 PHP 8.2 行为 act -j test --env PHP_VERSION=8.2 <h1>测试 PHP 8.4 行为（同时覆盖多个变量）</h1><p>act -j test --env PHP_VERSION=8.4 --env DB_DRIVER=pdo_mysql
这些变量会在步骤中以 $PHP_VERSION 形式被 shell 使用，也可在 if 条件里引用，但依然不能用于 setup-php 的 php-version 字段。
