setup-php：GitHub Actions 里装 PHP 扩展和工具的实用方式
项目速览：用于设置 PHP 扩展、php.ini 配置、覆盖驱动程序和各种工具的 GitHub 操作。
秒懂
- 它是什么？
- shivammathur/setup-php 是一个在 GitHub Actions 中配置 PHP 环境、扩展、覆盖驱动和 Composer 等工具的动作。它跨平台支持多种 runner，但也有一些边界需要你提前确认。
- 适合谁用？
- 如果你在 GitHub Actions 中跑 PHP 项目的测试，并且需要快速切换 PHP 版本、安装特定扩展或配置覆盖率工具，setup-php 是一个直接可用的选择。它覆盖了 GitHub-hosted 和 self-hosted 的常见系统，PHP 版本从 5.3 到 8.6，扩展列表也很长。
- 能商用吗？
- 可以。MIT 是宽松许可证：你可以使用、修改并销售基于它的软件，只需保留版权和许可证声明。
- 还在维护吗？
- 在维护。仓库最近一次提交在 1 天前。
- 用什么语言写的？
- 主要是 TypeScript（依据 GitHub 的语言统计）。
以上回答依据项目的 GitHub 数据（最近同步于 2026年9月15日）和我们的分析，不构成法律意见。
开源项目深度解析
它解决什么问题
在 GitHub Actions 里跑 PHP 测试，最烦的是环境不一致。每个 runner 预装的 PHP 版本可能不同，扩展也不全，覆盖率工具默认没启用。setup-php 就是来解决这个的：你用一个 action 指定 PHP 版本、扩展列表、php.ini 配置项、覆盖率驱动，以及 Composer 这类工具。它面向的是写 PHP 库或应用、需要在 CI 里跑单元测试和静态分析的开发者。文档里列出的支持范围很广，从 PHP 5.3 到 8.6，覆盖 Ubuntu、Windows、macOS 的多个版本。如果你只是想在本地跑一个 PHP 脚本，这个 action 帮不上忙，它是给 GitHub Actions 工作流用的。
工作机制：切换、安装、配置
根据 README 的描述，setup-php 的逻辑是：如果请求的 PHP 版本已经预装在 runner 上，它就切换到那个版本；如果没有，它就安装。这避免了重复下载。安装之后，它会处理扩展的启用和 php.ini 的修改。具体来说，它接受一个 php-version 输入，一个 extensions 输入，一个 coverage 输入（xdebug、pcov 或 none），还有 tools 输入来安装 Composer 等。文档里给了例子，比如用矩阵测试多个 PHP 版本，或者启用 nightly build。它不是一个编译器，它依赖 runner 上已有的包或预构建的二进制。这意味着对于老版本 PHP 5.3 到 5.5，它只在 GitHub-hosted runner 上支持，self-hosted 不支持，因为那些系统可能没有对应的包。
实际用法：一个最小工作流
要开始用，你只需要在 workflow 文件里加一个步骤。README 的 basic setup 部分给出了一个典型的例子，大致是：先 checkout 代码，然后用 actions/setup-php 指定 php-version 为 '8.2'，extensions 为 'mbstring, intl'，coverage 为 'xdebug'，然后运行 composer install 和 phpunit。具体输入名是 php-version、extensions、coverage、tools。例如 tools: 'composer:v2' 可以指定 Composer 版本。还有 flags 输入，比如 '--force' 可以强制更新，'--verbose' 输出更多日志。这些都在 README 的 Inputs 和 Flags 小节里有明确说明。如果你用 self-hosted runner，需要先运行一个 setup 步骤，文档里叫 self-hosted setup，它会准备依赖。
扩展和覆盖率的细节
扩展支持是 setup-php 的核心卖点。README 里有一个 PHP Extension Support 部分，列出了大量扩展，但具体列表被截断了，我只能确认它存在，不能列出全部。覆盖率方面，它支持 Xdebug 和 PCOV，通过 coverage 输入选择。如果你不设置 coverage，默认是不启用任何覆盖率驱动的，这可能导致 phpunit 报告说没有覆盖率驱动。文档里有一个 Disable Coverage 的选项，如果你不需要覆盖率，可以显式设置 coverage: none 来避免安装 Xdebug，加快 CI。这看起来简单，但有个坑：Xdebug 和 PCOV 是互斥的，你不能同时启用。如果你在扩展列表里写了 xdebug，又在 coverage 里写了 pcov，行为可能不是你想要的。
局限和容易踩的坑
第一个局限是 PHP 版本支持有平台差异。比如 macOS ARM64 runner（macos-14）不支持 PHP 5.3 到 5.5，只支持 5.6 以上。如果你在 macos-14 上跑老项目，会直接失败。第二个是 self-hosted runner 的支持依赖操作系统版本，Ubuntu 22.04 和 Debian 11 等，但文档说基于这些系统的其他版本是 best effort，不保证。第三个是扩展安装不是万能的，有些扩展可能需要系统库，action 不会帮你装 lib 包。如果你需要编译扩展，这个 action 不适合，它只是调用包管理器。最后，它默认不处理 Composer 的认证，但提供了 GitHub Composer Authentication 和 Private Packagist Authentication 的示例，你需要额外配置 token。
替代方案：直接调用系统包
如果你不想用这个 action，可以在 workflow 里直接运行 apt-get 或 brew 来安装 PHP 和扩展。比如在 Ubuntu runner 上，你可以用 sudo apt-get install php8.2-cli php8.2-mbstring，然后手动启用扩展。这种方式的区别在于：你完全控制安装过程，但需要自己处理版本切换和路径配置。setup-php 封装了这些，并且提供了跨平台的一致性，比如在 Windows 上你不需要知道 Chocolatey 的包名。另一个替代是使用 Docker 容器，比如 php:8.2-cli 镜像，在容器里跑测试。这能保证环境完全一致，但需要你管理 Docker 构建和缓存，而且 runner 上必须有 Docker。setup-php 的优势是轻量，直接修改当前环境，不需要额外容器层。
维护和升级成本
这个项目维护活跃，最近一次提交是 2026 年 6 月，版本号 2.37.2。它使用语义化版本，主版本 2 保持向后兼容。升级成本主要在跟随新版本：你可以在 workflow 里固定版本，比如 uses: shivammathur/setup-php@2.37.2，但这样会错过 bug 修复。常见做法是用 @v2 标签，但这会引入不兼容变更的风险，尽管 README 说主版本内保持兼容。许可证是 MIT，这意味着你可以自由使用和修改，但要注意它依赖的第三方项目可能有不同许可证。文档里有一个 Dependencies 部分，但没有列出具体依赖，所以你需要自己检查 action 的源码或发布说明来确认。如果你在商业项目中使用，MIT 许可通常没有障碍，但最好留意依赖的更新。
编辑结论
如果你在 GitHub Actions 中跑 PHP 项目的测试，并且需要快速切换 PHP 版本、安装特定扩展或配置覆盖率工具，setup-php 是一个直接可用的选择。它覆盖了 GitHub-hosted 和 self-hosted 的常见系统，PHP 版本从 5.3 到 8.6，扩展列表也很长。但如果你需要的是对 PHP 二进制本身的深度定制，比如自己编译扩展或修改内核参数，这个动作就不够用，它只是调用预构建的包或系统包。采用前先确认你的 runner 是否在支持列表里，特别是 macOS ARM64 的版本限制，以及你需要的扩展是否在默认列表中，否则可能需要用 inputs 里的额外参数去安装。还要注意它默认不启用 Xdebug，需要显式设置 coverage 输入，否则覆盖率会缺失。动手前读一遍 README 的 inputs 和 flags 部分，比猜更靠谱。
社区笔记