本文聚焦于 Mac 上 PHP 启用 SQLite 模块的完整教程：环境准备、安装与验证，旨在帮助开发者在 macOS 环境中快速完成配置，确保应用能够稳定地使用 SQLite 数据库。
环境准备
系统与工具版本要求
在进行初步准备时，请确保你的 macOS 版本支持开发工具，并且具备基础的命令行能力。将 macOS 升级到兼容的版本可以避免潜在的库不兼容问题；同时确认 Xcode 命令行工具已安装，否则后续的编译与链接可能失败。
另外，请确保你具备一个稳定的网络环境，以便快速下载 Homebrew、PHP 运行时以及 sqlite3 相关的依赖。网络稳定性是顺利完成安装的关键，避免因中断导致的版本错位。
安装 Homebrew 与 Xcode 命令行工具
在 Mac 上推荐使用 Homebrew 作为包管理器来安装 PHP、SQLite 与其他开发工具，同时需要 Xcode 命令行工具支持编译与链接步骤。以下命令用于一次性准备环境：
# 安装 Xcode 命令行工具
xcode-select --install# 安装或更新 Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"# 更新 Homebrew 缓存与已安装的公式
brew update
完成后，可以通过执行 brew doctor 进行自检，确保系统处于良好状态。若显示任何警告，按提示处理即可，这有助于后续的模块安装与编译稳定性。
安装与配置 PHP 的 SQLite 模块
确认 PHP 安装来源与版本
在 macOS 上，一般有两种 PHP 安装来源：系统自带的 PHP 与 Homebrew 安装的 PHP。确认当前正在使用的 PHP 版本和来源，有助于后续扩展的定位与配置。可以查看版本信息与已加载的模块来判断来源：
php -v
php -m | egrep -i 'sqlite|pdo_sqlite'
php --ini
如果输出显示为 Homebrew 安装的路径（如 /opt/homebrew 或 /usr/local），那么后续的扩展管理就以 Homebrew 为主。确保 php.ini 路径正确，以便后续为 SQLite 模块做启用配置。
安装或更新 SQLite 相关库与扩展
SQLite 的核心库通常由系统或 Homebrew 提供。为确保 PHP 能正确链接到 SQLite 库，建议单独安装 SQLite 库并确保链接关系正常。以下命令可以在 Homebrew 环境中安装最新的 sqlite：
brew install sqlite
安装完成后，确认核心库已就绪，并观察是否存在冲突的版本。sqlite 库的正确版本与路径对 PHP 模块的链接至关重要，请在编译或加载扩展前确保库路径可用。你还可以查看库路径，如 /opt/homebrew/opt/sqlite 或 /usr/local/opt/sqlite，以确认实际位置。
启用 PHP 的 sqlite3 与 pdo_sqlite 模块
在大多数现代 PHP 发行版中，sqlite3 与 pdo_sqlite 两个模块要么作为核心要素内置，要么作为可加载的扩展。你需要确认它们是否已被加载，并在需要时进行显式开启。以下步骤适用于使用 Homebrew 安装的 PHP。
# 查找加载的配置文件（php.ini）
php -i | grep "Loaded Configuration File"# 基于 Homebrew 常见路径，定位并编辑 php.ini（请根据实际路径替换 /opt/homebrew/ 或 /usr/local/）
# 在该文件中添加以下两行以启用扩展
# extension=sqlite3.so
# extension=pdo_sqlite.so# 如系统提示扩展未找不到，请确认扩展文件是否存在于扩展目录中
php -m | egrep -i 'sqlite|pdo_sqlite'
如果你看到 sqlite3 与 pdo_sqlite 已在加载的模块列表中，表示启用已生效。若未出现，请按照实际的 PHP 版本和前缀路径调整命令中的 php.ini 路径，确保扩展能够被正确加载。
验证安装与常见问题
运行简单测试脚本
通过一个小型的 PHP 测试脚本来验证 SQLite 支持是否工作正常，包括创建表、写入数据以及查询。以下示例将创建一个本地数据库并执行简单操作：
// 简单的 SQLite 测试脚本
$db = new PDO('sqlite:sample.db');
$stm = $db->prepare('CREATE TABLE IF NOT EXISTS test (id INTEGER PRIMARY KEY, name TEXT)');
$stm->execute();
$stm = $db->prepare('INSERT INTO test (name) VALUES (:name)');
$stm->execute(['name' => '演示']);
$rows = $db->query('SELECT * FROM test')->fetchAll(PDO::FETCH_ASSOC);
var_export($rows);
运行上述脚本后，若能够正确创建表、写入数据并输出结果，说明 PDO_SQLITE 与 SQLite3 模块在 PHP 中工作正常。你也可以用命令行快速验证扩展是否加载：php -m 或 php -i。
使用命令行检查扩展
除了运行测试脚本，直接检查扩展加载状态也是高效的方式。以下命令可快速确认当前 PHP 环境中是否包含 sqlite3 与 pdo_sqlite：
php -m | egrep -i 'sqlite|pdo_sqlite'
php -i | grep -i sqlite
若命令输出显示 sqlite3、pdo_sqlite，并且 数据库驱动信息正常返回，表示配置已经就绪。若未输出，请返回上一步的路径与配置文件，确保扩展被正确加载。
常见问题与修复
在实际使用中，可能遇到以下常见问题及处理思路：链接错误、扩展加载失败、版本不兼容、权限问题等。下面列出一些排查要点，帮助你定位问题根源并进行修复：
一、链接错误：确认 sqlite 库路径已包含在 PHP 的编译/链接阶段，可通过 otool -L $(which php) 查看动态库依赖，确保 sqlite 库路径在系统库搜索路径中。
二、扩展加载失败：再次确认 php.ini 的修改位置正确，且扩展名拼写无误；如果系统存在多个 PHP 版本，请确保修改的是正在执行的 PHP 的 php.ini。
三、版本不兼容：若升级或切换 PHP 版本，请重新执行 brew install php@x.y 并进行对应版本的扩展启用配置，确保 sqlite3 与 pdo_sqlite 与当前 PHP 版本匹配。
四、权限与路径问题：确保 php.ini 所在目录对当前用户可读，且写入扩展配置的文件具有正确的权限；如遇权限阻塞，请在具有权限的目录下进行修改。
