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

ThinkPHP 配置 SQLite 必须同时满足四条件：启用 pdo_sqlite 或 sqlite3 扩展、安装 topthink/think-sqlite 包、dsn 为绝对路径格式 sqlite:/abs/path/db.db、配置中禁用 hostname 等无效参数并设置 PDO::ATTR_TIMEOUT。

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 [email protected]
• 验证代码：var_dump(PDO::getAvailableDrivers()) 输出数组里必须有 "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。

立即学习“PHP免费学习笔记（深入）”；

• 绝对路径是刚需：'dsn' => 'sqlite:' . __DIR__ . '/../runtime/db/app.db'（__DIR__ 指 config 目录）
• 禁止相对路径：./db/app.db 在 CLI 和 Web 环境下工作目录不同，行为不一致
• 禁止反斜杠（Windows）：runtimeapp.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/，拼出的路径完全不是同一个文件。