在 ServBay 中编译和安装自定义 PHP 模块（macOS）

ServBay 是一款专为 macOS 设计的强大本地 Web 开发环境，集成了广泛的软件包，以满足现代 Web 开发者的需求。它预置了 PHP、Node.js、Python、Go、Java、数据库（如 MySQL, PostgreSQL, MongoDB）、缓存（Redis）以及 Web 服务器（Caddy, Nginx, Apache）等多种技术栈。ServBay 为每个软件包提供多版本支持，让您可以根据项目需求灵活切换环境。

虽然 ServBay 已经包含了许多常用的 PHP 模块，但在某些特定的开发场景下，您可能需要编译并安装额外的 PHP 模块，以扩展 PHP 的功能或集成特定的第三方服务。

本文将提供一份详细的指南，介绍如何在 ServBay 环境中为您的 PHP 版本编译和安装自定义模块。我们将以编译常用的 imagick 图像处理模块和 sqlsrv Microsoft SQL Server 数据库驱动模块为例，详细阐述整个流程，帮助您顺利地为 ServBay 中的 PHP 环境添加所需功能。

前提条件

重要提示

在开始编译任何 PHP 模块之前，最关键的步骤是按照 ServBay 官方文档的指引，完成编译环境的初始化并正确设置系统环境变量。这是成功编译 ServBay 软件包（包括 PHP 模块）的基础。如果跳过或未正确执行此步骤，后续的编译过程将极大概率失败，出现找不到命令、库或头文件等错误。

ServBay 的编译环境初始化脚本会设置必要的环境变量，例如 PATH（指向 ServBay 内部的构建工具）、SERVBAY_PACKAGE_FULL_PATH（指向 ServBay 软件包根目录）和 CPU_NUMBER（用于多核编译）。这些变量对于后续的编译命令至关重要。

有关如何初始化 ServBay 编译环境的详细步骤，请务必参考文档：使用 ServBay 进行二次编译。请确保您已充分理解并严格按照该文档中的说明完成了所有必要设置。

在继续进行模块编译之前，请务必确认您已经成功完成了上述 ServBay 编译环境的初始化工作，并且相关的环境变量已在您的当前终端会话中正确设置。

指定 PHP 版本的重要性

ServBay 的一个核心特性是支持在同一系统上安装和运行多个 PHP 版本。这种灵活性使得开发者可以轻松地为不同的项目切换 PHP 环境。然而，当您需要编译 PHP 模块时，必须针对特定的 PHP 版本进行操作。用于准备编译环境和获取版本配置信息的关键工具 phpize 和 php-config 是与特定的 PHP 版本紧密关联的。

• phpize：这是一个用于准备 PHP 扩展模块编译环境的脚本。它会读取 config.m4 文件，并生成标准的 configure 脚本，这是编译 C/C++ 软件的常见第一步。
• php-config：这个脚本提供了关于特定 PHP 版本安装的详细配置信息，包括编译器标志、包含文件目录、库文件目录、扩展安装目录等。configure 脚本会调用 php-config 来获取这些信息，以确保模块能够与目标 PHP 版本正确地构建和链接。

因此，在使用 phpize、php-config 或其他与 PHP 构建相关的命令时，您必须通过其完整路径明确指定您希望为其编译模块的 PHP 版本。例如，如果您想为 ServBay 中安装的 PHP 8.3 编译模块，您需要使用 /Applications/ServBay/package/php/8.3/current/bin/phpize 和 /Applications/ServBay/package/php/8.3/current/bin/php-config。选择正确的版本可以确保编译出的模块与您的目标 PHP 环境兼容，避免编译错误和运行时出现“未找到符号”等问题。

本文档中的示例将以 ServBay 中安装的 PHP 8.3 版本为例进行说明。请在实际操作时，将其命令路径替换为您需要编译模块的 ServBay 中实际安装的 PHP 版本路径。

编译 PHP imagick 模块

imagick 模块是 PHP 中一个非常流行的扩展，它基于强大的 ImageMagick 命令行工具库，提供了丰富的图像处理功能。使用 imagick，您可以在 PHP 中执行缩放、裁剪、格式转换、添加水印、图像合成等多种复杂的图像操作。以下是在 ServBay 环境中为特定 PHP 版本编译和安装 imagick 模块的详细步骤：

步骤 1：安装 ImageMagick 依赖库

imagick PHP 模块依赖于系统上安装的 ImageMagick 库。在 macOS 上，推荐使用 Homebrew 包管理器进行安装。如果您尚未安装 Homebrew，请访问 Homebrew 官方网站 获取安装指南。

打开终端，运行以下命令安装 ImageMagick 及其开发库：

brew install imagemagick

步骤 2：获取 imagick 模块源码

接下来，您需要从 PHP 扩展库 (PECL) 官方网站下载 imagick 模块的源码包。访问 PECL imagick 页面 查找您需要的版本（通常选择最新稳定版），并获取其下载链接。以下示例使用撰写本文时的较新版本 3.7.0：

wget https://pecl.php.net/get/imagick-3.7.0.tgz

步骤 3：解压源码包并进入目录

下载完成后，使用 tar 命令解压源码包，然后使用 cd 命令进入解压后的模块源码目录：

tar zxvf imagick-3.7.0.tgz
cd imagick-3.7.0

步骤 4：准备编译环境（使用 phpize）

进入模块源码目录后，使用对应 PHP 版本的 phpize 工具准备编译环境。如前所述，务必使用您目标 PHP 版本的 phpize 完整路径。假设您要为 PHP 8.3 编译，并且您已正确设置 SERVBAY_PACKAGE_FULL_PATH 环境变量：

${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/phpize

成功执行 phpize 后，它会检查源码包中的 config.m4 文件，生成 configure 脚本以及其他必要的构建文件。终端会输出一些信息，表明编译环境已准备就绪。

步骤 5：配置编译选项

运行刚刚生成的 configure 脚本来配置模块的编译选项。在此步骤中，必须通过 --with-php-config 参数指定您目标 PHP 版本的 php-config 路径，以便 configure 脚本能够获取到正确的 PHP 构建配置信息，如编译器路径、包含目录、库目录等。

./configure --with-php-config=${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php-config

configure 脚本会执行一系列检查，包括查找依赖的 ImageMagick 库和头文件，并根据获取到的 PHP 配置信息生成用于编译的 Makefile 文件。如果出现错误，通常是依赖未安装或路径不正确。

步骤 6：编译和安装模块

配置成功并生成 Makefile 后，就可以开始编译模块了。使用 make 命令进行编译，然后使用 make install 命令将编译好的模块文件安装到 PHP 的扩展目录中。${CPU_NUMBER} 变量（通常在 ServBay 编译环境初始化时设置）用于指定并行编译的进程数，可以加快编译速度。

make -j ${CPU_NUMBER}
make install

make install 命令会自动根据 php-config 提供的信息，将编译生成的 imagick.so 文件复制到 ServBay 中对应 PHP 版本的标准扩展安装目录（例如 /Applications/ServBay/package/php/8.3/current/lib/php/extensions/no-debug-non-zts-YYYYMMDD/，具体路径取决于 PHP 版本和构建选项）。

步骤 7：启用模块

模块文件安装完成后，您需要在目标 PHP 版本的配置文件中启用它。ServBay 提供了图形界面的启用方式。

• 打开 ServBay 程序
• 左侧菜单导航到 语言 - PHP - PHP 8.3
• 在右侧页面选择 PHP 标签，下拉到最后，在“额外参数”中，输入extension=imagick.so
• 点击保存，PHP 进程会自动重启并读取新增加的模块

步骤 8：验证模块加载

启用模块后，您需要重启 ServBay 中的 PHP 软件包，使新的配置生效。您可以通过 ServBay 管理面板界面，找到对应的 PHP 版本软件包，然后点击重启按钮；或者使用 ServBay 提供的命令行工具来重启（具体命令请参考 ServBay 文档）。

重启 PHP 后，您可以使用命令行验证 imagick 模块是否已成功加载：

${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php -m | grep imagick

这里使用 $SERVBAY_PACKAGE_FULL_PATH/php/8.3/current/bin/php 命令是确保调用的是 ServBay 中特定版本的 PHP 可执行文件。-m 参数用于列出所有已加载的 PHP 模块。如果 imagick 模块成功加载，您应该会在输出结果中看到 imagick 字样。

更详细的验证方法是，在您的 Web 根目录（默认为 /Applications/ServBay/www）下创建一个 PHP 文件（例如 info.php），包含 <?php phpinfo(); ?> 代码。然后通过浏览器访问 http://localhost/info.php 或您配置的 ServBay 网站域名访问该文件。在 phpinfo() 输出页面中，搜索 "imagick" 即可确认其是否已启用，并查看其配置信息和版本号。

编译 PHP sqlsrv/pdo_sqlsrv 模块

sqlsrv 和 pdo_sqlsrv 模块是 PHP 的一个官方扩展，用于连接和操作 Microsoft SQL Server 数据库。它基于 Microsoft 提供的 ODBC 驱动程序。如果您需要在 ServBay 中的 PHP 环境中连接到 SQL Server 数据库，就需要编译和安装此模块。以下是在 ServBay 环境中编译和安装 sqlsrv/pdo_sqlsrv 模块的步骤：

注意：重要先决条件

在 macOS 环境下编译和安装 sqlsrv 模块，您必须首先安装 Microsoft 提供的 SQL Server ODBC 驱动 (msodbcsql18) 和相关的命令行工具 (mssql-tools18)。这些软件包不是 ServBay 自带的，需要您手动安装。

推荐使用 Homebrew 包管理器来安装这些依赖。如果您尚未安装 Homebrew，请访问 Homebrew 官方网站 进行安装。

安装 Microsoft ODBC 驱动和工具的 Homebrew 命令如下。请注意，您可能需要同意许可协议（通过设置 HOMEBREW_ACCEPT_EULA=Y 环境变量）。

brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release
brew update
HOMEBREW_ACCEPT_EULA=Y brew install msodbcsql18 mssql-tools18

请确保在尝试编译 sqlsrv 模块之前，这些依赖项已经成功安装。这些依赖通常会被安装到 /opt/homebrew/ 目录下（对于 Apple Silicon Macs）或 /usr/local/ 目录下（对于 Intel Macs）。编译时需要正确引用这些路径。

提示

sqlsrv 和 pdo_sqlsrv 是两个不同模块，需要分别编译，但编译步骤类似，下面以sqlsrv为例。

步骤 1：安装 Microsoft ODBC 驱动和工具

（如上所述，这是必要的前置步骤，确保您已使用 Homebrew 安装了 msodbcsql18 和 mssql-tools18。）

步骤 2：获取 sqlsrv 模块源码

从 PECL 官方网站下载 sqlsrv 和 pdo_sqlsrv 模块的源码包。访问 PECL sqlsrv 页面 获取最新或您需要的版本下载链接。以下示例使用撰写本文时的较新版本 5.12.0：

wget https://pecl.php.net/get/sqlsrv-5.12.0.tgz  # sqlsrv
wget https://pecl.php.net/get/pdo_sqlsrv-5.12.0.tgz  # pdo_sqlsrv

步骤 3：解压源码包并进入目录

下载完成后，解压源码包并进入解压后的模块源码目录：

tar zxvf sqlsrv-5.12.0.tgz
cd sqlsrv-5.12.0

# pdo_sqlsrv 也类似，以下步骤只以 sqlsrv 为例

步骤 4：准备编译环境（使用 phpize）

进入模块源码目录后，使用对应 PHP 版本的 phpize 工具准备编译环境。假设您要为 PHP 8.3 编译，并且您已正确设置 SERVBAY_PACKAGE_FULL_PATH 环境变量：

${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/phpize

步骤 5：配置编译选项（包含依赖路径）

运行 configure 脚本配置编译选项。由于 sqlsrv 严重依赖于 Homebrew 安装的 Microsoft ODBC 驱动及其相关的 unixODBC 库，您需要在运行 ./configure 命令前，通过设置环境变量 LDFLAGS 和 CPPFLAGS 来指定 Homebrew 库和头文件的搜索路径。这能帮助 configure 脚本找到所需的依赖文件。同时，仍然需要使用 --with-php-config 参数指定目标 PHP 版本的配置路径。

请根据您的 Homebrew 安装路径（Intel Mac 通常是 /usr/local，Apple Silicon Mac 通常是 /opt/homebrew）调整以下命令中的路径。以下示例假设 Homebrew 安装在 /opt/homebrew：

export LDFLAGS="-L/opt/homebrew/lib ${LDFLAGS}"
export CPPFLAGS="-I/opt/homebrew/opt/unixodbc/include -I/opt/homebrew/include ${CPPFLAGS}" # 添加 /opt/homebrew/include 确保找到所有头文件
./configure --with-php-config=${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php-config

• LDFLAGS: 用于指定链接器搜索库文件的路径。-L/opt/homebrew/lib 指向 Homebrew 安装库的默认路径。
• CPPFLAGS: 用于指定 C/C++ 预处理器搜索头文件的路径。-I/opt/homebrew/opt/unixodbc/include 指向 Homebrew 安装的 unixODBC（ODBC 驱动的依赖）头文件的路径。-I/opt/homebrew/include 可能包含其他必要的头文件。${CPPFLAGS} 和 ${LDFLAGS} 保留了 ServBay 编译环境可能已经设置的其他标志。

步骤 6：编译和安装模块

配置成功并生成 Makefile 后，使用 make 命令编译模块，然后使用 make install 命令将其安装到 PHP 的扩展目录中：

make -j ${CPU_NUMBER}
make install

make install 命令会将编译好的 sqlsrv.so 和 pdo_sqlsrv.so（如果一起编译）文件复制到 ServBay 中对应 PHP 版本的标准扩展安装目录。

步骤 7：启用模块

模块文件安装完成后，您需要在目标 PHP 版本的配置文件中启用它。ServBay 提供了图形界面的启用方式。

• 打开 ServBay 程序
• 左侧菜单导航到 语言 - PHP - PHP 8.3
• 在右侧页面选择 PHP 标签，下拉到最后，在“额外参数”中，输入extension=sqlsrv.so 和 extension=pdo_sqlsrv.so
• 点击保存，PHP 进程会自动重启并读取新增加的模块

步骤 8：验证模块加载

启用模块后，务必重启 ServBay 中的 PHP 软件包，使新的配置生效。

重启 PHP 后，使用命令行验证 sqlsrv 模块（以及 pdo_sqlsrv）是否已成功加载：

${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php -m | grep sqlsrv
${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php -m | grep pdo_sqlsrv

如果模块成功加载，您应该会在输出结果中看到 sqlsrv 和 pdo_sqlsrv 字样。同样，您也可以通过 phpinfo() 函数的输出来确认模块状态和详细信息。

常见问题 (FAQ)

• Q: 编译时出现 "Cannot find autoconf" 或类似错误？
  • A: 这几乎可以确定是 ServBay 编译环境未正确初始化的表现。请回到文档开头的“前提条件”部分，仔细检查并按照 使用 ServBay 进行二次编译 文档的指引，完成 ServBay 编译环境的设置。确保相关的构建工具（如 autoconf, automake, libtool 等）已安装并通过环境变量正确引用。通常，运行 ServBay 的编译环境初始化脚本并重启终端即可解决此问题。
• Q: configure 脚本执行失败，提示找不到某个库或头文件？
  • A: 这意味着模块依赖的某个系统库或头文件未安装，或者已安装但未被正确找到。
    • 对于 imagick，请确保您的系统安装了 ImageMagick 开发库。您可以使用 Homebrew 安装：brew install imagemagick。
    • 对于 sqlsrv，请务必检查是否已按照先决条件使用 Homebrew 安装了 Microsoft ODBC 驱动 (msodbcsql18) 和 mssql-tools18。同时，在运行 ./configure 命令前，请仔细检查 LDFLAGS 和 CPPFLAGS 环境变量是否设置正确，包含了 Homebrew 依赖的库和头文件路径（例如 /opt/homebrew/lib, /opt/homebrew/opt/unixodbc/include）。
    • 检查 ServBay 编译环境设置中是否包含了 Homebrew 的路径（如果依赖是通过 Homebrew 安装的），或者是否需要手动将 Homebrew 的 bin 目录添加到 ServBay 编译环境的 PATH 中。
• Q: make 或 make install 失败？
  • A: 编译或安装失败可能是由于多种原因：
    • 缺少编译依赖: 查看错误输出，它通常会提示缺少哪个文件或库。根据提示安装相应的依赖。
    • 配置错误: 回到 configure 步骤，检查参数是否正确，特别是 --with-php-config 路径是否指向了您目标 PHP 版本的 ServBay 安装路径。
    • 权限问题: make install 会将文件复制到 ServBay 的安装目录下的 PHP 扩展目录。如果 ServBay 编译环境脚本没有正确设置权限或路径，可能会遇到权限问题。尝试使用 sudo make install (需谨慎，并确保您了解其风险)。
    • 源码问题: 检查下载的模块源码包是否完整或损坏。
• Q: 模块 .so 文件已经生成并放在了扩展目录，也在 .ini 文件中启用了，但 php -m 或 phpinfo() 中看不到模块？
  • A:
    • 最常见原因： 没有重启 ServBay 中的 PHP 软件包。请确保在修改完 .ini 文件后，通过 ServBay 管理面板或 ServBay 命令行工具完全重启了目标 PHP 版本。简单的刷新网页或重启 Web 服务器（如 Caddy/Nginx）是不够的，必须重启 PHP 软件包本身。
    • .ini 文件语法错误：检查您创建的 .ini 文件内容是否有拼写错误或格式问题 (extension=modulename.so)。
    • 扩展目录路径错误：确认 php.ini 中 extension_dir 的设置是否正确指向了 ServBay 的 PHP 扩展目录。make install 会根据 php-config --extension-dir 的输出来安装，您可以通过此命令确认路径。
    • 模块文件损坏或与 PHP 版本不兼容：重新编译一次，确保过程无误。确认下载的源码版本与您的 PHP 版本兼容。检查 PHP 日志文件（通常在 ServBay 安装目录下的 logs 文件夹中）是否有关于模块加载失败的错误信息。

总结

通过遵循本文档提供的详细步骤，您应该能够在 ServBay macOS 本地开发环境中成功编译和安装自定义的 PHP 模块，如 imagick 和 sqlsrv。整个过程的关键在于：

1. 正确且完整地初始化 ServBay 编译环境：这是所有后续编译操作能够顺利进行的基础。
2. 指定并使用正确的 PHP 版本路径：在使用 phpize 和 php-config 时，务必通过完整路径指向您希望为其编译模块的 ServBay 中的 PHP 版本。
3. 解决模块的外部依赖问题：根据模块需求安装必要的系统库和工具（如 ImageMagick、Microsoft ODBC 驱动等），并在 ./configure 步骤中通过环境变量（如 LDFLAGS, CPPFLAGS）或配置参数指定其路径，确保 configure 脚本能找到所有必需的依赖。
4. 正确启用模块：在目标 PHP 版本的 conf.d 目录下创建或修改 .ini 文件，使用 extension=modulename.so 指令加载模块。
5. 重启 ServBay 中的 PHP 软件包：使新的模块配置和加载生效。

ServBay 作为一个全面的本地开发环境，提供了极大的灵活性来支持您的各种开发需求。除了本文介绍的 PHP 模块编译，ServBay 还全面支持和预集成了 MySQL, PostgreSQL, MongoDB, Redis, Caddy, Nginx, Apache, Node.js, Python, Go, Java, .NET, Ruby, Rust 等多种技术栈。此外，ServBay 还提供了一系列实用功能，如通过 ACME 申请真实 SSL 证书、简便的 CORS 配置、自动化数据备份（包括设置、网站、数据库、SSL 证书）、重置数据库 root 密码、以及 ServBay User CA 和 ServBay Public CA 用于本地 HTTPS 开发等，助您构建高效、便捷且功能强大的本地开发工作流。

希望这份指南能帮助您顺利地为 ServBay 中的 PHP 环境添加所需的功能，更高效地进行 Web 开发。如果您遇到其他问题，建议查阅 ServBay 的官方文档或社区支持资源。