从源码构建到测试验证：php-src（PHP 解释器）官方仓库完整构建指南

本文以 php-src 仓库根目录的 README.md 为主体，系统讲解 PHP 解释器的源码获取、构建依赖安装、configure 生成与配置、并行编译、测试套件运行以及安装部署的全流程，并结合 buildconf、configure.ac、build/Makefile.global 等仓库源码，说明每一步背后真实的构建系统行为，帮助开发者完成从"拿到 Git 源码"到"产出可用 php 二进制并跑通测试"的完整闭环。

PHP 解释器仓库概览

PHP 是一种流行的通用脚本语言，尤其擅长 Web 开发。当前仓库（php-src）即 PHP 解释器本体，采用 Modified BSD License（LICENSE，SPDX-License-Identifier: BSD-3-Clause）分发。

从 configure.ac 中的初始化声明可以确认当前仓库的版本定位：

AC_INIT([PHP],[8.6.0-dev],[https://github.com/php/php-src/issues],[php],[https://www.php.net])

即这是 PHP 8.6 的开发线代码。仓库顶层目录的组织方式直接对应解释器的组成：

目录	职责
Zend/	Zend 虚拟机：字节码执行器（zend_vm_execute.skl 生成 handler）、编译器（zend_compile.c、zend_language_parser.y）、优化器（Zend/Optimizer/）、垃圾回收（zend_gc.c）等核心引擎
main/	运行时核心：I/O、流（streams）、SAPI 抽象层、main.c 入口
ext/	捆绑扩展：json、pcre、spl、standard 等，每个扩展自带 tests/ 下的 .phpt 用例
sapi/	服务器 API 实现：cli、fpm、cgi、apache2handler、phpdbg 等
tests/	引擎级测试套件，配套根目录的 run-tests.php 测试驱动
win32/	Windows 平台的系统调用兼容层

官方用户手册（PHP manual）是最终权威文档入口，仓库内则通过 CONTRIBUTING.md、CODING_STANDARDS.md、docs/release-process.md、docs/mailinglist-rules.md 等文件支撑开发协作流程。

安装方式选型：预编译包 vs 源码构建

README 给出了两条路线，适用场景不同：

• 预编译包/二进制：面向快速部署。Windows 从 windows.php.net 获取二进制包，解压后 *.exe 文件即可直接使用；其他发行版通过各自包管理器安装。
• 源码构建：面向需要定制扩展组合、参与开发调试、或使用 Git 主线的开发者。Windows 下源码构建需另查官方 Wiki 的分步指南，本文聚焦 *nix 体系（README 亦如此界定）。

源码构建对工具的最低要求（摘自 README）：

• 最小构建（minimal build）：autoconf、bison、re2c；
• 默认构建（default build）：在上述基础上再加 libxml2、libsqlite3。

各发行版的依赖安装命令（原文档完整保留）：

Ubuntu：

sudo apt install -y pkg-config build-essential autoconf bison re2c libxml2-dev libsqlite3-dev

Fedora：

sudo dnf install re2c bison autoconf make ccache libxml2-devel sqlite-devel

macOS（Homebrew）：

brew install autoconf bison re2c libiconv libxml2 sqlite

macOS（MacPorts）：

sudo port install autoconf bison re2c libiconv libxml2 sqlite3

第一步：buildconf 生成 configure 脚本

从 Git 仓库获取的源码不含现成的 configure 脚本，需要先执行：

./buildconf

这一步的真实行为可以直接在 buildconf 脚本中核对：

1. 区分开发线与发行包：脚本读取 configure.ac 中 AC_INIT 的版本串，若含 -dev 标记（当前仓库正是 8.6.0-dev）则视为开发源码，允许直接重新生成；对于非 dev 的发行包，若 configure 与 main/php_config.h.in 已存在则提示"已构建完成，直接运行 ./configure"，只有加 -f/--force 才会强制重新生成（对应 buildconf）。
2. 校验 autoconf 版本：从 configure.ac 提取 AC_PREREQ 声明的最低版本（当前为 AC_PREREQ([2.68])，见 configure.ac），与本机 autoconf --version 比对，不满足则报错退出（buildconf）。
3. 清理后重建：删除 aclocal.m4、autom4te.cache、config.cache、configure、main/php_config.h.in 等旧产物，然后依次调用 autoconf 与 autoheader 重新生成 configure 和 main/php_config.h.in（buildconf）。
4. 可定制的选项与环境变量：
   • -f, --force：强制在发行包上重新生成 configure 文件；
   • --debug：展示 Autoconf 发出的告警（等价于 -Wall）；
   • PHP_AUTOCONF / PHP_AUTOHEADER：覆盖 autoconf/autoheader 工具路径，例如 PHP_AUTOCONF=/path/to/autoconf ./buildconf。

注意：从 PHP.net 下载的正式发行包已内置 configure 脚本，无需安装 Autoconf、也无需执行 buildconf——这是 buildconf 帮助文本明确说明的适用边界。

第二步：configure 配置构建

生成后进入配置阶段。README 给出两条推荐基线：

# 开发用：启用调试断言与内存安全检查
./configure --enable-debug
# 生产用：默认优化构建
./configure

完整选项清单通过 ./configure --help 查看。由于 configure 由 autoconf 从 configure.ac 及 ext/、sapi/ 下各模块的 .m4 文件生成，--help 中会列出全部捆绑扩展与 SAPI 的 --with-*/--enable-* 开关，可按需裁剪。

第三步：make 编译

make -j4

-jN 指定最大并行任务数，README 建议让 N 与可用核心数一致，Linux 下用 nproc 查询：

make -j$(nproc)

第四步：make test 运行测试套件

编译成功后，README 说明用 make test 运行随源码分发的庞大测试套件。其执行链路在构建系统中有明确落点：build/Makefile.global 中的测试目标最终调用的是根目录的 run-tests.php：

$(PHP_EXECUTABLE) -n -c $(top_builddir)/tmp-php.ini $(PHP_TEST_SETTINGS) \
    $(top_srcdir)/run-tests.php -n -c $(top_builddir)/tmp-php.ini \
    -d extension_dir=$(top_builddir)/modules/ $(PHP_TEST_SHARED_EXTENSIONS) $(TESTS)

可以看到几个关键点：测试使用 -n（忽略外部 ini）配合构建目录内的 tmp-php.ini 运行，并通过 extension_dir 指向刚编译出的 modules/ 共享扩展目录；命令行尾部拼入的 $(TESTS) 变量正是"只测部分目录"的实现通道。

README 中的两个实用开关：

1）覆盖并行 worker 数。 测试默认并行执行，最多使用检测到的 10 个逻辑处理器。通过 TEST_PHP_ARGS（或 TESTS）传入 -jN 覆盖：

# 最多 4 个并发任务
make TEST_PHP_ARGS=-j4 test
# 串行执行（调试时常用）
make TEST_PHP_ARGS=-j1 test

2）只测指定目录。 利用 TESTS 变量直接传入测试路径，例如只跑语言特性测试：

make TESTS=tests/lang/ test

仓库中 .phpt 用例的分布可供组合选择：引擎级在 tests/（含 tests/lang/、tests/classes/、tests/basic/ 等），Zend 引擎专项在 Zend/tests/（覆盖 closures、generators、traits、fibers、lazy_objects 等特性），扩展级则在各扩展目录内，如 ext/json/tests/。更多测试与 QA 细节官方指引至 qa.php.net 站点。

第五步：make install 安装

构建（及测试）通过后安装：

make install

README 提醒：是否需要超级用户权限取决于你的用户权限与 configure 时设置的 --prefix；生产安装通常需 sudo，而装入用户目录（如 ./configure --prefix=$HOME/php-local）则可以免 root 完成。

扩展体系：内置扩展与第三方扩展

README 指出扩展为 PHP 提供额外能力，并区分三个来源：

1. 捆绑扩展：随源码树内置于 ext/（json、pcre、mbstring、sqlite3、zlib、openssl 等），默认构建即编译进来，可用 ./configure --help 查看完整清单；
2. 第三方扩展：扩展目录可查 PIE Extensions 列表，推荐使用 🥧 PIE（PHP Installer for Extensions）安装；旧渠道 PECL 已处于弃用状态。

仓库根的 EXTENSIONS 文件则是维护者视角的权威台账：按 Server API、数据库、文本处理等类别逐一列出每个扩展的主要维护者、维护状态（Maintained/Odd Fixes/Orphan/Obsolete）与运行状态（Working/Not Working），是判断某个内置扩展健康度、寻找可认领的"孤儿扩展"的直接依据。

贡献流程：从 PR 到合入

README 的 Contributing 一节定义了上游协作规则，要点如下：

• 入口：fork 仓库后提 Pull Request；讨论在 GitHub 进行，必要时经官方开发者邮件列表 [e-mail] 转达。
• 新功能必须先走 RFC 并获开发者投票接受；修 bug 不需要 RFC。
• 提交信息引用规范：GitHub issue 用 GH-NNNNNN，旧 bugs.php.net 工单用 #NNNNNN。README 给出的真实示例：

Fix GH-7815: php_uname doesn't recognise latest Windows versions
Fix #55371: get_magic_quotes_gpc() throws deprecation warning

• 配套文档（均为仓库内可读文件）：
  • CONTRIBUTING.md —— 贡献指南；
  • CODING_STANDARDS.md —— 编码规范：PHP 以 C11 实现，偏好 emalloc()/efree() 等带安全网的内存 API，字符串函数必须利用长度属性避免 strlen()、严禁 strncat()，PHP_* 宏用于 PHP 侧、ZEND_* 宏用于 Zend 侧等；
  • docs/release-process.md —— 发布流程；
  • docs/mailinglist-rules.md —— 邮件列表规则；
  • 内部文档站点 php.github.io/php-src 提供 Internals 文档（源在 docs/）。

完整流程速查

综合上述各节，一条 *nix 上从源码到可用的标准流水线为：

# 1. 安装依赖（以 Ubuntu 为例）
sudo apt install -y pkg-config build-essential autoconf bison re2c libxml2-dev libsqlite3-dev

# 2. 生成 configure（仅 Git 源码需要）
./buildconf

# 3. 配置
./configure --enable-debug   # 或 ./configure 用于生产

# 4. 编译
make -j$(nproc)

# 5. 测试
make test                     # 全量
make TESTS=tests/lang/ test   # 指定目录
make TEST_PHP_ARGS=-j1 test   # 串行调试

# 6. 安装
make install

适用前提与边界

• 本文所有命令与路径以当前仓库（PHP 8.6.0-dev 开发线，AC_INIT([PHP],[8.6.0-dev])）实测内容为准；正式发行包已含 configure，可跳过 buildconf 步骤。
• make test 的并行默认值（10 个逻辑处理器）与 README 描述一致，具体 worker 数仍受机器资源影响。
• Windows 源码构建流程不在本文范围内，README 明确指引至官方 Wiki 的分步文档。
• 扩展的可用性受 configure 阶段开关控制，最终以 php -m 输出为准。