1. 环境准备
1.1 安装 Homebrew 与系统工具
在 macOS 上，Homebrew 是最便捷的包管理工具，它可以帮助你安装和管理 PHP、数据库以及开发工具。确保你的系统版本为最新的长期支持分支，并且具备命令行工具。若尚未安装 Homebrew，可以使用以下命令进行安装：请先执行以下命令以确保环境可用。
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"安装完成后，运行 brew doctor 以检查潜在问题，并使用 brew update、brew upgrade 保持软件最新。
1.2 验证并配置 PHP 环境
建议使用经过测试的稳定版本 PHP，并确保命令行环境与 Web 服务使用的 PHP 版本一致。你可以通过 php -v 查看当前版本，必要时使用 Homebrew 安装或切换版本。以下命令演示如何安装最新稳定版 PHP 并将其作为系统默认版本：
brew install php
brew link --overwrite --force php
php -v如果你使用的是搭建在 Apache/Nginx 上的环境，请确保与 PHP-FPM 的版本匹配，以避免扩展加载异常。
1.3 安装 Composer（PHP 依赖管理）
Composer 是管理 PHP 依赖的标准工具，在后续步骤中将用于安装 MongoDB 的官方 PHP 库。通过以下命令全局安装 Composer，并配置镜像源提升下载速度：建议配置国内镜像。
brew install composer
composer -V
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/2. 安装 MongoDB 服务
2.1 使用 Homebrew 安装 MongoDB Community
MongoDB 服务在本地开发环境中通常以社区版形式运行，通过 Homebrew 可以快速安装。执行以下命令安装 MongoDB Community：注意版本稳定性。
brew tap mongodb/brew
brew install mongodb-community安装完成后，你将获得 mongod 服务的可执行命令以及相关工具。
2.2 启动 MongoDB 服务
启动 MongoDB 服务是连接数据库的前提，你可以按需启动单机实例，或设置随系统启动：推荐使用社区版默认端口 27017。
brew services start mongodb-community
# 或者手动启动 mongod（需要创建数据目录）
mongod --config /usr/local/etc/mongod.conf启动后，确保日志中显示服务器就绪信息，且没有端口冲突。
2.3 验证 MongoDB 服务是否正常运行
用 mongo shell 或简单连接测试来确认服务可用，你可以使用以下命令进行快速校验：
mongo --eval "db.runCommand({ connectionStatus: 1 })"如果输出包含 ok: 1，表示服务可用；接下来可以使用 PHP 连接测试数据库。
3. 安装 PHP MongoDB 驱动与库
3.1 安装 MongoDB PHP 扩展（驱动）
MongoDB 官方提供的 PHP 驱动通过 PECL 下载并安装，这是与 MongoDB 交互的核心扩展。执行以下步骤完成安装：确保 PHP 版本与扩展兼容。
pecl install mongodb安装完成后，记得在 php.ini 中加载该扩展，或者在正确的 PHP 版本的配置中启用扩展。
3.2 安装 MongoDB PHP 库（官方 ODM/客户端）
除驱动外，还需要客户端库来简化操作。使用 Composer 将官方 MongoDB 库添加到项目中：这是推荐的 PHP 客户端。
composer require mongodb/mongodb该库提供 MongoDB\Client 等对象，便于进行数据库及集合操作。
3.3 验证扩展已加载及依赖关系
确认 php.ini 已加载 mongodb.so，以及 Composer 依赖已经安装完毕。你可以创建一个临时脚本测试扩展是否生效，或直接查看 PHP 配置：
php -m | grep mongodb
composer show mongodb/mongodb若看到输出中包含 mongodb，且 Composer 已显示 mongodb/mongodb 包，则表示准备就绪。
4. 配置 PHP 以加载 MongoDB 扩展
4.1 修改 PHP 配置，启用 mongodb 扩展
在 PHP 的配置文件中添加扩展加载指令，确保在 CLI 与 Web 服务器使用的 php.ini 中都包含相同的配置。常见的位置是 /usr/local/etc/php/7.x/php.ini 或 /etc/php.ini。以下是示例：请替换为实际路径。
; PHP 配置示例
extension=mongodb.so保存后，重新加载 Web 服务器或重启 PHP-FPM，以使变更生效。
4.2 重启 PHP 服务与 Web 服务器
确保新加载的扩展生效，你可以通过重启 Web 服务来应用更改。示例命令如下，视你的环境而定：重启 Web 服务后再跑一次连接测试。
# 对于 Homebrew 安装的 PHP
brew services restart httpd # 如果你使用的是 Apache
brew services restart nginx # 如果你使用的是 Nginx + php-fpm
brew services restart php # 如果你直接使用 PHP-FPM4.3 设置环境变量与连接认证（如需）
若 MongoDB 设置了认证、用户名和密码，请在连接字符串中包含认证信息，例如：mongodb://用户名:密码@localhost:27017/数据库名。未启用认证时，可以使用本地无认证的连接字符串。以下是一个带认证的示例片段：请替换实际凭据。
# 连接示例的说明：请在实际项目中不要把凭据硬编码在代码中，使用环境变量或配置管理工具
mongodb://user:password@localhost:270175. 编写测试脚本并进行连接测试
5.1 编写测试脚本
使用 Composer 安装的 MongoDB 客户端库，创建一个简单的测试脚本，用于验证能正确列出数据库。以下示例使用自动加载并输出数据库名称。确保脚本放在项目目录中，并已执行 composer install。
listDatabases();foreach ($databases as $db) {echo $db->getName() . PHP_EOL;}
} catch (Exception $e) {echo "连接失败: " . $e->getMessage() . PHP_EOL;
}
?> 该脚本演示了基础连接与数据库枚举能力，如果你看到数据库名称逐个输出，说明连接测试通过。
5.2 运行测试脚本
在终端中执行 PHP 脚本进行测试，如：php test_mongo.php。确保你在包含脚本的目录下执行，且已安装依赖。
php test_mongo.php如果出现输出了数据库列表且无错误信息，表示连接测试成功；如果出现错误，请根据异常信息定位问题，例如网络、端口、认证、扩展加载等。
5.3 常见错误排查
常见问题包括扩展未加载、PHP 版本不匹配、MongoDB 服务未启动、连接字符串错误等。请按以下要点排查：逐项确认以定位问题。
# 确认模块加载
php -m | grep mongodb# 确认 MongoDB 服务状态
brew services list | grep mongodb# 查看连接字符串是否正确（如有认证、TLS 选项）
