PHP 8.2 版本为开发者带来了一项显著便利：默认内置了 sqlite3 和 pdo_sqlite 扩展。这意味着，在大多数标准配置下，您可以无需额外安装驱动或依赖外部服务，直接开箱即用地连接 SQLite 数据库，极大简化了轻量级应用的部署流程。
如何确认 SQLite 扩展已正确启用
许多开发者误以为“PHP 8.2 自带 SQLite”就意味着万事大吉，但在实际调用 new SQLite3('db.db') 时，却可能遭遇“Class not found”的错误。这通常并非扩展缺失，而是其未被成功加载。
- 命令行快速验证：运行
php -m | grep -i sqlite命令。您必须在输出结果中同时看到sqlite3和pdo_sqlite两行。若只出现一行，使用 PDO 连接时可能报“could not find driver”，而 SQLite3 类也可能无法使用。 - Windows 用户配置：检查
php.ini文件，确保extension=php_sqlite3.dll和extension=php_pdo_sqlite.dll这两行前的分号已被移除。 - Linux/macOS 用户配置：检查
extension=sqlite3.so和extension=pdo_sqlite.so是否已启用。需注意，部分通过 phpEnv 或自行编译的 PHP 版本可能默认未包含 SQLite 扩展，此时需要重新编译并加入--with-sqlite3 --with-pdo-sqlite参数。 - 脚本内验证：在代码中执行
var_dump(extension_loaded('sqlite3') && extension_loaded('pdo_sqlite'));，只有当返回结果为true时，才表明扩展已加载到位。
使用 SQLite3 类连接：规避路径与权限陷阱
SQLite3 类是 PHP 8.2 中连接 SQLite 数据库最轻量、最直接的方式。然而，它对文件路径和系统权限极其敏感——路径写错可能导致静默创建空文件，权限不足则会直接抛出“unable to open database file”错误。
- 务必使用绝对路径：推荐写法如
new SQLite3(__DIR__ . '/data/app.db')。避免使用'app.db'这类相对路径，因为当前工作目录（可通过getcwd()获取）会受 CLI 或 Web 服务器启动方式影响。 - 确保目录存在且可写：例如，
__DIR__ . '/data/'目录需提前创建并设置适当权限（如mkdir -p data && chmod 755 data）。同时，Web 服务器运行用户（如www-data或_www）必须对该目录拥有写入权限。 - 注意自动创建行为：首次执行
new SQLite3(...)时会自动创建数据库文件，但不会自动创建其所在目录。若目录不存在或不可写，操作可能静默失败并返回false。 - 明确定义主键：建表时，请使用
id INTEGER PRIMARY KEY明确定义主键。否则，后续调用$db->lastInsertRowID()可能返回 0 或无效值。
使用 PDO 连接 SQLite：掌握 DSN 与错误处理
PDO 方式更适合需要事务支持、预处理语句或未来可能迁移数据库的项目。但其默认错误处理模式可能掩盖真实问题，例如 SQL 语法错误可能仅返回笼统的 SQLSTATE[HY000] 错误码。
- 正确书写 DSN 字符串：格式应为
sqlite:/abs/path/to/db.sqlite（Linux/macOS）或sqlite:C:\path\to\db.sqlite（Windows）。开头的sqlite:协议标识符不可遗漏，路径也必须使用绝对路径。 - 必须设置错误模式：连接后立即执行
$pdo->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION)。若不设置，当exec()等方法失败时，仅返回false而不抛出异常，给调试带来困难。 - 考虑禁用模拟预处理：可通过
setAttribute(PDO::ATTR_EMULATE_PREPARES, false)禁用模拟预处理。否则，当绑定参数数量与 SQL 占位符不匹配时，PDO 可能静默失败。 - 利用错误信息调试：调试时，
$pdo->errorCode()和$pdo->errorInfo()提供的信息有时比异常对象的$e->getMessage()更精确，能帮助定位如字段名包含短横线（user-id）却未用反引号包裹等细节问题。
启用 WAL 模式：提升并发写入性能的关键
SQLite 默认的回滚日志（rollback journal）模式在并发写入时极易触发“database is locked”错误。在 PHP 8.2 配合 SQLite 3.26+ 版本的环境中，启用 WAL（Write-Ahead Logging）模式几乎是应对并发写入的必备配置，能有效避免小流量应用出现卡顿。
- 连接后立即执行：无论是使用 PDO 还是 SQLite3 类，建立连接后都应立即执行
$pdo->exec("PRAGMA journal_mode = WAL")或$db->exec("PRAGMA journal_mode = WAL")。 - 验证模式是否生效：执行
$db->query("PRAGMA journal_mode")->fetchArray()[0]，返回值应为wal。 - 确保文件系统一致性：WAL 模式会生成
-wal和-shm两个辅助文件。这三个文件（主库文件、-wal、-shm）必须位于同一个文件系统（挂载点）内。若跨不同挂载点，WAL 模式会自动退化为 DELETE 模式，此过程可能不易察觉。 - 注意设置的非持久性：WAL 设置不会持久化，每次新建数据库连接时都需要重新设置，不可一劳永逸。
总而言之，使用 SQLite 的真正挑战往往不在于“如何连接”，而在于“为何连上后读不到数据”或“为何并发时锁死”。路径错误、权限不足、WAL 模式因跨文件系统失效、错误模式未开启——这四点几乎覆盖了 90% 的线上 SQLite 故障场景。在动手编码前，花几秒钟运行 php -m | grep sqlite 确认扩展状态，再用 ls -l data/ 检查目录权限，通常比反复修改代码要高效得多。
