ThinkPHP配置SQLite数据库：轻量级应用开发与本地测试的极简方案

ThinkPHP 配置 SQLite 的四个硬性条件，缺一不可

ThinkPHP 配置 SQLite，可不是简单改个 type 字段就能跑的。四个条件必须同时满足——扩展安装、DSN 格式、路径权限、环境一致性，一个不到位就报错。

先看第一个：PHP 层必须启用 pdo_sqlite 或 sqlite3 扩展。框架配置再对，PHP 本身不认识 SQLite，连接照样失败——这不是 ThinkPHP 的问题，而是底层依赖缺失。检查方法很简单：运行 php -m | grep sqlite，输出里必须出现 pdo_sqlite 或 sqlite3（两者任一个就行）。Windows 下要去 php.ini 取消注释 extension=php_pdo_sqlite.dll，注意不是 php_sqlite.dll 那个旧驱动。Linux/macOS 没输出的话，装包：sudo apt install php-sqlite3 或 brew install php@8.2-sqlite3。最后可以用 var_dump(PDO::getA vailableDrivers()) 验证，返回数组里必须有 "sqlite"。

第二个条件：ThinkPHP 6/8 必须装 topthink/think-sqlite 扩展。TP6 和 TP8 默认不带 SQLite 驱动适配器，光有 PHP 原生支持不够——框架启动直接报 Driver [sqlite] not supported。解决方案：执行 composer require topthink/think-sqlite（注意不是 think-orm 自带的那个），然后确认 vendor/topthink/think-sqlite 目录存在。配置里 'type' => 'sqlite' 必须和 'dsn' 同时出现，缺一不可。特别注意 TP8 里只配 type 不写 dsn 的话，会静默 fallback 到无效驱动，报 Driver not found: sqlite。

第三个关键点：dsn 必须是 sqlite:/absolute/path/to/db.db 格式。ThinkPHP 5.1+ 的 PDO SQLite 驱动只靠 DSN 字符串开头的 sqlite: 识别协议，任何偏差都会导致解析失败，报 SQLSTATE[HY000] Unable to open database file。绝对路径是刚需，推荐用 'dsn' => 'sqlite:' . __DIR__ . '/../runtime/db/app.db'（__DIR__ 指向 config 目录）。绝对不要用相对路径 ./db/app.db，因为 CLI 和 Web 环境下工作目录不同，行为完全不一致。Windows 下禁止反斜杠，runtime\app.db 会被 URI 解析器截断，必须统一用正斜杠。路径里不能有空格和中文，文件名建议全英文+下划线，比如 app_data.db。另外，hostname、username、password、database 这些字段必须留空或删掉，SQLite 根本不接受这些参数。

最后一个往往容易被忽略：并发写入必须加 PDO::ATTR_TIMEOUT。SQLite 的文件锁机制在高频率请求下极易阻塞，ThinkPHP 默认连接池为 1 且没有超时设置，表单重复提交或 AJAX 连发会立刻卡死。解决方法是配置中加入 'params' => [PDO::ATTR_TIMEOUT => 5]（单位是秒，别填毫秒）。还要避免在事务内做耗时操作，比如调外部 API、生成 PDF，否则锁持有时间远超预期。高频写场景尽量用批量插入 INSERT INTO table VALUES (),(),() 来减少锁竞争次数。最后一个小警告：千万把 .db 文件放在 public/ 目录里，既可能被 Web 服务器直接暴露，又难控制写权限。

最隐蔽的坑是 CLI 和 Web 环境路径不一致：命令行执行 php think migrate:run 时，__DIR__ 指向的是 config/，而 Apache/Nginx 下的 $_SERVER['DOCUMENT_ROOT'] 可能指向 public/，拼出的路径完全不是同一个文件。一旦踩过这个坑，你就会明白为什么我们反复强调“绝对路径”和“环境一致性”不是说说而已。