如何在 ServBay 中加载第三方 PHP 扩展

ServBay 是一款强大的本地 Web 开发环境，它预置了许多常用的 PHP 扩展。用户通常只需在 ServBay 的软件包 (Packages) -> 语言 (Languages) -> PHP 版本 -> 扩展中进行配置和启用即可。

然而，开发者有时需要加载 ServBay 默认未包含的第三方或自定义编译的 PHP 扩展。本文将详细指导您如何在 ServBay 中为指定的 PHP 版本加载这类扩展，以 ionCube Loader 为例进行演示。此过程同样适用于其他 Zend 扩展或您自己编译的 .so 扩展文件。

关于 Zend 扩展的特别说明: ionCube Loader 是一个 Zend 扩展，这类扩展与 PHP 的 Zend 引擎交互更深。因此，在配置时需要使用 zend_extension 指令，而不是用于普通扩展的 extension 指令。请务必区分并正确使用。

前提条件

您已经在 macOS 系统上安装并运行了 ServBay。
您拥有管理员权限，可以访问系统文件和 ServBay 配置界面。
您熟悉使用 macOS 的终端（Terminal）应用程序。
您已确定需要加载的第三方 PHP 扩展文件（通常是 .so 文件），并且该文件与您 ServBay 中目标 PHP 版本的 PHP 版本、架构 (Intel 或 Apple Silicon) 以及编译选项（如 NTS/ZTS）完全兼容。

注意：架构兼容性至关重要

ServBay 为 Intel (x86_64) 和 Apple Silicon (ARM64, 如 M1/M2/M3/M4 芯片) 架构均提供了原生架构的 PHP 软件包。在加载 .so 扩展文件时，务必确认您所加载的 .so 文件编译架构与 ServBay 中对应 PHP 软件包的架构一致。

不同架构的文件不能混用，架构不一致将导致 PHP 无法启动或崩溃。

您可以使用 file 命令来确定可执行文件或 .so 文件的架构：

确定 ServBay 附带的 PHP 软件包架构（请将 8.3 替换为您实际使用的 PHP 版本）：

bash

file /Applications/ServBay/package/php/8.3/current/bin/php

输出信息类似：

/Applications/ServBay/package/php/8.3/current/bin/php: Mach-O 64-bit executable arm64 # 表示 Apple Silicon ARM64 架构

或

/Applications/ServBay/package/php/8.3/current/bin/php: Mach-O 64-bit executable x86_64 # 表示 Intel x86_64 架构

确定您下载或编译的 .so 扩展文件架构（请将 xdebug.so 替换为您的扩展文件名）：
bash
```
file xdebug.so
```
1
输出信息类似：
```
xdebug.so: Mach-O 64-bit bundle arm64 # 表示 Apple Silicon ARM64 架构
```
1
或
```
xdebug.so: Mach-O 64-bit bundle x86_64 # 表示 Intel x86_64 架构
```
1
确保步骤 1 和步骤 2 中的架构信息完全匹配。

操作步骤

步骤 1：下载第三方扩展文件 (以 ionCube Loader 为例)

访问 ionCube Loader 的官方下载页面。请根据您的 macOS 架构选择合适的版本。对于 macOS ARM64 (Apple Silicon M 系列芯片)，请下载 Darwin ARM64 版本。您可以直接使用以下链接（请注意检查官方网站是否有更新版本，以下链接为示例）： https://downloads.ioncube.com/loader_downloads/ioncube_loaders_dar_arm64.tar.gz
下载完成后，您会得到一个 .tar.gz 压缩文件，例如 ioncube_loaders_dar_arm64.tar.gz。

步骤 2：确定目标 PHP 版本和 ServBay 的扩展安装目录

打开 ServBay 应用程序。
在左侧导航栏中，点击 软件包 (Packages) 下的 语言 (Languages)。
在右侧列表中，找到您想要为其安装 ionCube Loader 的 PHP 版本（例如，本例中为 PHP 8.3）。请记下这个版本号。
确定 ServBay 中该 PHP 版本的扩展安装目录 (extension_dir)。这是存放 .so 文件的标准位置。ServBay 的 PHP 扩展通常存放在特定路径下，具体路径取决于 ServBay 安装位置、PHP 版本和编译选项。
最可靠的方法是通过终端命令查找：
打开终端（Terminal）应用程序，并运行以下命令（请务必将 /Applications/ServBay/package/php/8.3/current/bin/php 替换为您目标 PHP 版本的实际 php 可执行文件路径）：
bash
```
/Applications/ServBay/package/php/8.3/current/bin/php -i | grep extension_dir
```
1
命令输出会显示 extension_dir => /path/to/extension/directory。例如，输出可能类似：
```
extension_dir => /Applications/ServBay/package/php/8.3/8.3.16/lib/php/extensions/no-debug-non-zts-20230831
```
1
请记下这个确切的路径，后续步骤将需要用到它。

步骤 3：解压并放置 Loader 文件

打开终端（Terminal）应用程序。
使用 cd 命令进入您下载 .tar.gz 文件的目录（通常是 ~/Downloads 目录）。
bash
```
cd ~/Downloads
```
1
解压缩下载的文件：
bash
```
tar -zxvf ioncube_loaders_dar_arm64.tar.gz
```
1
这会在当前目录创建一个名为 ioncube 的新目录。
进入 ioncube 目录：
bash
```
cd ioncube
```
1
在此目录中，您会看到对应不同 PHP 版本的 .so 文件，例如 ioncube_loader_dar_8.3.so。找到与您目标 PHP 版本（步骤 2 中确定的版本，例如 8.3）匹配的文件。
将这个匹配的 .so 文件复制到您在步骤 2 中确定的 PHP 扩展安装目录。例如，如果目标目录是 /Applications/ServBay/package/php/8.3/8.3.16/lib/php/extensions/no-debug-non-zts-20230831/，并且您要安装 PHP 8.3 的 Loader：
bash
```
cp ioncube_loader_dar_8.3.so /Applications/ServBay/package/php/8.3/8.3.16/lib/php/extensions/no-debug-non-zts-20230831/
```
1
- 请务必将命令中的目标路径 /Applications/ServBay/.../no-debug-non-zts-20230831/ 替换为您在步骤 2 中通过 php -i 命令获取的 实际扩展安装目录路径。
- 确保您复制的是与目标 PHP 版本完全匹配的 .so 文件，并且文件的架构与 PHP 软件包架构一致（参见前提条件中的架构检查）。

步骤 4：在 ServBay 中配置 PHP

回到 ServBay 应用程序界面。
确保左侧 语言 (Languages) 已选中，然后在右侧列表中点击您要配置的 PHP 版本（例如 PHP 8.3）。
在右侧展开的配置区域中，点击 PHP 标签页。
向下滚动找到 Additional Parameters（附加参数）文本框。
在此文本框中，添加以下一行配置指令，指定 ionCube Loader 文件名：
ini
```
zend_extension = ioncube_loader_dar_8.3.so
```
1
- 重要： 请务必将 ioncube_loader_dar_8.3.so 替换为您实际复制到扩展目录中的文件名。
- 使用 zend_extension 而不是 extension，因为 ionCube Loader 是 Zend 扩展。
- 由于您已将 .so 文件放置在 extension_dir 中，这里只需要写文件名即可，无需填写完整路径。
- 如果此文本框中已有其他配置（每行一条指令），请在新的一行添加此指令。
(截图仅为示例，实际界面可能因版本略有差异)
点击右下角的 Save 按钮保存配置。

步骤 5：重启 PHP 服务

在 ServBay 中点击 Save 按钮后，ServBay 会自动检测配置更改并尝试平滑重启相关的服务（包括 PHP）。通常情况下，您无需手动执行额外的重启步骤。

步骤 6：验证加载是否成功

可以通过以下两种常用方式验证 ionCube Loader 是否已成功加载：

通过命令行验证:
- 打开终端。
- 运行以下命令，列出已加载的 PHP 模块（确保使用目标 PHP 版本的完整路径）：
  bash
```
/Applications/ServBay/package/php/8.3/current/bin/php -m | grep -i ioncube
```
  1
  如果成功加载，您应该能看到类似 ionCube Loader 的输出行。
- 您也可以运行 php -v 命令查看 PHP 版本信息，通常加载了 ionCube Loader 后，其信息会显示在 Zend Engine 的版本信息下方：
  bash
```
/Applications/ServBay/package/php/8.3/current/bin/php -v
```
  1
  成功加载后的输出示例（具体的版本号可能不同）：
```
PHP 8.3.16 (cli) (built: Jan 31 2025 15:09:39) (NTS)
Copyright (c) The PHP Group
Zend Engine v4.3.16, Copyright (c) Zend Technologies
    with the ionCube PHP Loader v14.4.0, Copyright (c) 2002-2024, by ionCube Ltd.
```
  1
  2
  3
  4
  注意 with the ionCube PHP Loader ... 这一行。
通过 phpinfo() 函数验证:
- 在您的网站根目录（例如 /Applications/ServBay/www/servbay.demo/ 或您配置的其他网站路径）中创建一个新的 PHP 文件，例如 info.php。
- 在该文件中仅包含以下内容：
  php
```
<?php
phpinfo();
?>
```
  1
  2
  3
- 通过浏览器访问该文件，例如 http://servbay.demo/info.php (请替换为您的本地网站域名)。
- 在浏览器中打开的 phpinfo() 输出页面中，搜索 "ionCube" (使用浏览器的查找功能，通常是 Cmd + F 或 Ctrl + F)。如果加载成功，您会看到一个专门的 ionCube Loader 信息区块，显示其版本、许可信息等详细内容。

如果上述验证步骤显示 ionCube Loader 信息，则表示扩展已成功加载。

常见问题与故障排除

PHP 启动失败或崩溃: 这最常见的原因是扩展文件的架构与 PHP 软件包架构不匹配。请严格按照前提条件中的步骤检查并确保架构一致。此外，PHP 版本或编译选项不兼容也可能导致此问题。
extension_dir 路径错误: 确保您将 .so 文件复制到了 ServBay 中该 PHP 版本的实际 extension_dir 路径下。使用 php -i | grep extension_dir 命令获取的路径是最准确的。
配置指令错误: 检查 ServBay 中 Additional Parameters 中添加的指令是否正确。对于 Zend 扩展，必须使用 zend_extension = filename.so；对于普通扩展，使用 extension = filename.so。文件名必须与复制到 extension_dir 中的文件名完全一致（包括大小写）。
文件权限问题: 确保 ServBay 运行用户（通常是您的 macOS 用户）对复制的 .so 文件及其所在的目录有读取权限。通常复制到 ServBay 软件包目录中不会有权限问题，但如果手动更改过权限需要检查。
ServBay 未重启: 尽管 ServBay 通常会自动重启，但如果发现配置未生效，可以尝试手动在 ServBay 界面中停止并重新启动相关服务，或直接重启 ServBay 应用。
在 phpinfo() 中找不到信息: 确保您访问的是 ServBay 管理的、并且已配置了该扩展的 PHP 版本的 phpinfo() 页面。如果您有多个 PHP 版本或多个网站，请确认您正在检查正确的环境。

总结

通过遵循以上详细步骤，您应该能够成功地为 ServBay 管理的特定 PHP 版本加载 ionCube Loader 或其他第三方 .so 格式的 PHP 扩展。关键在于准确识别目标 PHP 版本、找到正确的扩展安装目录 (extension_dir)、将兼容的扩展文件放置到该目录中，并在 ServBay 配置界面的 Additional Parameters 中使用正确的指令 (zend_extension 或 extension) 指定扩展文件名。如果在过程中遇到问题，请参照故障排除章节仔细检查每个环节，特别是架构兼容性和文件路径。

如何在 ServBay 中加载第三方 PHP 扩展 ​

前提条件 ​

操作步骤 ​

步骤 1：下载第三方扩展文件 (以 ionCube Loader 为例) ​

步骤 2：确定目标 PHP 版本和 ServBay 的扩展安装目录 ​

步骤 3：解压并放置 Loader 文件 ​

步骤 4：在 ServBay 中配置 PHP ​

步骤 5：重启 PHP 服务 ​

步骤 6：验证加载是否成功 ​

常见问题与故障排除 ​

总结 ​