PHP 7.4 源码编译：解决 DOMDocument 扩展缺失问题

日期：2025-11-03 00:00 / 作者：霞舞

本文详细阐述了在从源码编译 PHP 7.4 时，如何在禁用所有默认扩展（`--disable-all`）的情况下正确启用 `DOMDocument` 功能。核心在于，除了依赖库 `libxml` 外，`DOM` 扩展本身也需要通过 `--enable-dom` 明确激活，以避免编译后 `DOMDocument` 类缺失的错误。本教程将提供完整的编译步骤、正确的配置选项及验证方法，帮助开发者高效定制 PHP 环境。

引言：PHP 源码编译与扩展管理

从源码编译 PHP 允许开发者根据特定需求对 PHP 环境进行高度定制，例如选择性地启用或禁用扩展、优化编译参数以提升性能。然而，这种灵活性也带来了配置上的挑战。当使用 --disable-all 选项时，PHP 编译器会默认禁用所有内置和捆绑的扩展，这意味着即使是常用功能也需要显式地启用。DOMDocument 便是其中一个常被误解的扩展，它在处理 XML 和 HTML 文档时至关重要。

DOMDocument 缺失的根源分析

许多开发者在编译 PHP 时，认为只要通过 --with-libxml 选项引入了 libxml2 库，DOMDocument 功能就会自动可用。然而，这是一个常见的误区。libxml2 是 DOM 扩展的底层依赖库，提供了 XML 解析和操作的核心能力，但 DOM 扩展本身是一个独立的 PHP 模块，需要单独的配置指令来激活。

当编译命令中包含 --disable-all 时，所有默认扩展（包括 DOM 扩展）都会被禁用。此时，即使指定了 --with-libxml，也仅仅是告诉编译器 libxml2 库的位置，而没有指示它编译和启用 DOM 扩展。因此，最终生成的 PHP 二进制文件将无法识别 DOMDocument 类，导致运行时出现 Fatal error: Uncaught Error: Class 'DOMDocument' not found 的错误。

正确启用 DOMDocument 的编译配置

要确保在 --disable-all 的配置下 DOMDocument 可用，除了 --with-libxml 外，还必须明确添加 --enable-dom 选项。这将指示 PHP 编译器在构建过程中包含 DOM 扩展。

正确的 configure 命令示例如下：

./configure --disable-all --enable-cli --with-curl --with-libxml --enable-dom

在此配置中：

--disable-all: 禁用所有默认扩展。
--enable-cli: 启用命令行接口 SAPI。
--with-curl: 启用 cURL 扩展（此处作为示例，可根据需求增减其他扩展）。
--with-libxml: 指定 libxml2 库的路径，它是 DOM 扩展的依赖。
--enable-dom: 明确启用 DOM 扩展，从而使 DOMDocument 类可用。

完整的 PHP 7.4 源码编译与 DOMDocument 启用步骤

以下是在类似 Amazon Linux 2 环境下，从源码编译 PHP 7.4 并确保 DOMDocument 可用的完整步骤：

安装编译依赖 首先，确保系统安装了所有必要的编译工具和库。
```
sudo yum install -y autoconf bison re2c libxml2-devel gcc git
```
注意：libxml2-devel 提供了编译 libxml2 相关的头文件和静态库，对于源码编译至关重要。

获取 PHP 源码 从 GitHub 克隆 PHP 7.4 的源码仓库。

rm -rf php-src && \
git clone -b 'PHP-7.4' --depth 1 https://github.com/php/php-src.git && \
cd 'php-src'

配置与编译 运行 buildconf 生成 configure 脚本，然后使用正确的配置选项运行 configure，最后进行编译。
```
./buildconf && \
./configure --disable-all --disable-cgi --enable-cli --with-curl --with-libxml --enable-dom && \
make clean && \
make -j $(nproc)
```
- --disable-cgi: 禁用 CGI SAPI，通常在现代应用中不常用。
- --enable-cli: 启用命令行 SAPI，这是最常见的用法。
- -j $(nproc): 利用所有可用的 CPU 核心进行并行编译，加快编译速度。
部署 PHP 二进制文件 将编译好的 PHP CLI 二进制文件复制到目标路径。
```
rm -rfv ../php && \
cp -v ./sapi/cli/php ../php
```
现在，您可以在 ../php 路径下找到编译好的 PHP 7.4 CLI 二进制文件。

验证 DOMDocument 扩展

编译完成后，可以通过以下方法验证 DOM 扩展是否已成功加载：

使用 php -m 命令 运行编译后的 PHP 二进制文件，并列出所有已加载的模块。
```
../php -m | grep dom
```
如果输出中包含 dom，则表示 DOM 扩展已成功启用。
编写测试脚本 创建一个简单的 PHP 脚本来实例化 DOMDocument 类：
```
getMessage() . "\n";
}
?>
```
保存为 test_dom.php，然后运行：
```
../php test_dom.php
```
如果输出 DOMDocument 类已成功实例化。，则表示 DOMDocument 功能正常。

注意事项与最佳实践

--disable-all 的谨慎使用：虽然 --disable-all 有助于构建最小化的 PHP 环境，但它要求开发者对所需的所有扩展有清晰的认识，并逐一启用。在不确定时，可以考虑不使用此选项，让 PHP 默认启用常用扩展，然后通过 php.ini 或 configure 选项禁用不需要的。
区分 --with- 和 --enable-：
- --with-EXTENSION[=DIR]：通常用于指定外部库的路径，该库是某个 PHP 扩展的依赖。例如 --with-libxml。
- --enable-EXTENSION：用于启用 PHP 内部捆绑的扩展，这些扩展通常不依赖外部库（或依赖的库已通过 --with- 指定）。例如 --enable-dom。
查阅 config.log：在编译过程中遇到问题时，php-src 目录下的 config.log 文件是重要的调试工具。它记录了 configure 脚本执行的所有检查和错误信息，能帮助定位缺失的库、不兼容的选项等问题。
生产环境考量：在生产环境中部署自定义编译的 PHP 时，务必进行彻底的测试，并确保所有必要的扩展都已正确启用。同时，考虑使用 php-fpm SAPI 而不是 cli SAPI 来服务 Web 请求。

总结

在从源码编译 PHP 7.4 并使用 --disable-all 选项时，要确保 DOMDocument 功能可用，关键在于理解 libxml 是其依赖，而 DOM 扩展本身需要通过 --enable-dom 明确激活。遵循本教程提供的步骤和配置，开发者可以成功构建一个定制化的 PHP 环境，并避免因扩展缺失导致的运行时错误。掌握这些编译技巧对于维护和优化 PHP 应用至关重要。