pecl install mongodb 在 PHP 8.5.5 上会失败，因官方 PECL 截至 2026 年 6 月仍未提供适配包，必须手动编译源码：装依赖、克隆 mongo-php-driver、checkout 支持 PHP 8.5 的版本（如 1.19.3）、phpize、configure、make install，并在 php.ini 中用绝对路径启用 extension=/usr/lib/php/20251212/mongodb.so，同时 URI 必须完整（如 "mongodb://127.0.0.1:27017"），不可为空。
pecl install mongodb 在 PHP 8.5.5 上大概率会失败——官方 PECL 仓库截至 2026 年 6 月仍未发布适配 PHP 8.5 的预编译包，你必须手动编译源码。
为什么 pecl install mongodb 会报错
执行后常见错误包括：ERROR: failed to download pecl/mongodb 或编译时提示 PHP_VERSION_ID mismatch。这是因为 PHP 8.5 的内部 API 版本（如 20251212）尚未被 PECL 构建系统收录，所有预编译的 .so 包都只支持到 PHP 8.4。
- Ubuntu/Debian 的
apt install php-mongodb不提供 PHP 8.5 支持 - CentOS/RHEL 的
dnf install php-pecl-mongodb同样缺失 PHP 8.5 构建 - Windows 下目前没有任何可用的
php_mongodb.dll对应 PHP 8.5.5（连社区版都没有）
Linux/macOS 手动编译安装步骤
核心是用你本地的 PHP 8.5.5 环境构建驱动，不是下载现成包。
- 先确认 PHP 8.5.5 是源码编译安装的（否则缺
phpize和php-config）；若用phpbrew或asdf，运行phpbrew use 8.5.5切换后再操作 - 装依赖：
sudo apt-get install php8.5-dev autoconf pkg-config libsasl2-dev（Ubuntu/Debian）；macOS 用brew install autoconf pkg-config openldap - 克隆并 checkout 兼容分支：
git clone https://github.com/mongodb/mongo-php-driver.git && cd mongo-php-driver && git checkout 1.19.3（查 GitHub release 页面，选明确标注 “Supports PHP 8.5” 的版本） - 执行
phpize，再运行which phpize和phpize --version确保指向 PHP 8.5.5 的版本 -
./configure && make && sudo make install—— 成功后终端会输出类似Installing '/usr/lib/php/20251212/mongodb.so'，记住这个路径里的20251212（这是 PHP 8.5 的 ABI ID，不是年份）
配置 php.ini 必须写绝对路径
别写 extension=mongodb.so，PHP 8.5 会找不到。必须用完整路径：
extension=/usr/lib/php/20251212/mongodb.so
路径以你 make install 输出为准。改完后重启 php-fpm 或 Apache/Nginx，再用 php -m | grep mongodb 验证。
立即学习“PHP免费学习笔记（深入）”；
- 如果
php -m不显示mongodb，八成是路径写错，或php.ini不是当前 CLI/FPM 加载的那个（用php --ini确认） - 别漏掉
libsasl2-dev（Ubuntu）或openldap（macOS），否则 configure 阶段直接失败，报错含sasl.h not found
连接代码里 URI 不能为空字符串
PHP 8.5 强化了类型和参数校验，老写法会直接抛异常：
- ❌
new MongoDB\Driver\Manager("")→InvalidArgumentException - ✅ 必须写完整 URI：
new MongoDB\Driver\Manager("mongodb://127.0.0.1:27017") - 带认证时，
authSource参数必须显式加在 URI 查询串里："mongodb://user:pass@localhost:27017/admin?authSource=admin"，少一个?或拼错参数名都会静默失败
最易忽略的是 ABI 版本号（如 20251212）和 URI 格式细节——它们不报错但会让扩展加载失败或连接立即中断，排查时容易绕远路。
