说实话我是从 node-sqlite3 切到 better-sqlite3 的而且切得很晚。早几年看到 better-sqlite3 的 README 第一行写着“同步 API”时我下意识觉得这违背了 Node.js 的异步精神心想这种库在真实服务里怎么可能靠谱。后来在一个内部工具项目里被 node-sqlite3 的回调地狱和高昂的线程切换开销逼烦了才抱着试一试的心态换过去。结果只跑了半天我就后悔当初没早点用。这篇文章不是单纯吹 better-sqlite3而是把它的优势、用法、性能调优手段和适用边界一次性说清楚。我会从底层原理讲到实际代码再讲我踩过的坑。如果你正在 node-sqlite3 和 better-sqlite3 之间纠结或者刚接手一个用了 better-sqlite3 的项目这篇文章应该能帮你省下不少时间。1. 为什么 better-sqlite3 比 node-sqlite3 快三个核心原因1.1 同步与异步之争性能反而站在同步这边大多数人以为 node-sqlite3 的异步 API 是优势因为不会阻塞事件循环。但实际上 node-sqlite3 的每个 SQL 操作都要经历一层完整的事件循环往返你把 SQL 语句丢给 libuv 线程池线程池里的 C 代码执行 SQLite执行完后再把结果通过回调传回 JS 主线程。这个过程涉及线程切换、队列排队、V8 参数装箱/拆箱开销并不小。而 better-sqlite3 采取的是同步直调JS 代码直接进入 C 原生绑定执行 SQLite 查询然后带着结果返回。全程不需要线程池介入自然也省掉了线程切换的代价。单看一次查询两者相差可能只有几十微秒但累计到几万次查询差距会非常明显。你可以这么理解node-sqlite3 像是在餐厅里用外卖平台下单每一次下单都要经历“接单、通知厨房、打包、骑手配送”的流程better-sqlite3 则像直接站在窗口点单点完立刻拿走。单次可能差不了多少但你要是连续点 100 次后者的效率优势就出来了。1.2 预编译语句的缓存与复用更自然node-sqlite3 最常见的用法是db.all(sql, params, callback)很多项目甚至不会手动 prepare 语句每次查询都让 SQLite 重新解析一遍 SQL生成执行计划再执行。这样写起来方便但性能上吃了大亏。better-sqlite3 的核心 API 强制你先prepare再执行而这种 prepare 出的Statement对象天然是可以复用的。SQLite 在解析一次 SQL 后会缓存语法树和执行计划后续复用只需要绑定新参数并执行省掉的解析和优化时间很可观。这在循环里尤为明显。我做过一次批量插入测试同样插入 5000 行数据直接用字符串拼接 SQL 逐条执行和预先 prepare 好语句再循环执行两者耗时能差 2 到 3 倍。这是 SQLite 本身的特性不是 better-sqlite3 独有的只是 better-sqlite3 的 API 设计更容易让你写出正确的复用代码。1.3 稳定 ABI 带来的安装与运行体验better-sqlite3 使用 N-API 编写原生绑定这意味只要 Node.js 的 N-API 版本兼容它就不必针对每个 Node 小版本重新编译。node-sqlite3 用的是 V8 私有 API升级 Node 版本后通常要重新npm rebuild在 Electron 等环境里尤其痛苦。安装体验直接影响到开发效率。better-sqlite3 默认会下载预编译好的二进制省去本地编译环境配置。node-sqlite3 在某些环境里一旦没有预编译产物就需要 node-gyp、Python、C 工具链全套登场很劝退。2. better-sqlite3 安装与接入实操2.1 安装避坑与原生模块注意事项安装本身很简单npm install better-sqlite3但有几个细节值得关注。首先是 Electron 场景。如果你在 Electron 主进程里使用 better-sqlite3预编译的 Node 二进制不一定兼容 Electron 的 V8 版本通常需要借助electron/rebuild重新编译npm install --save-dev electron/rebuild npx electron-rebuild -f -w better-sqlite3其次如果你在 Docker 里构建且基础镜像缺少 Python 和编译工具链预编译下载失败时会回退到源码编译这时候非常依赖python3、make、g这些工具。建议在 Dockerfile 里提前装好或者使用带 build-essential 的基础镜像。还有一个相对冷门但实用的知识点better-sqlite3 的配置文件里可以通过db.pragma查询 SQLite 版本但如果你要检查 better-sqlite3 当前二进制版本直接用const Database require(better-sqlite3); console.log(better-sqlite3 version:, Database.getVersion()); // 实际上是数据库版本?这里我纠正一下官方提供了Database.getVersion()用于获取 SQLite 底层版本号模块自身的版本可以通过require(better-sqlite3/package.json).version拿到。2.2 最小接入流程从打开数据库到建表下面这个例子基本覆盖了接入一个项目的最小步骤打开数据库、设置 PRAGMA、建表、插入一条数据。const Database require(better-sqlite3); const db new Database(app.db); db.pragma(journal_mode WAL); db.pragma(foreign_keys ON); // 直接执行一条语句建表 db.exec( CREATE TABLE IF NOT EXISTS users ( id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, email TEXT NOT NULL UNIQUE, created_at TEXT DEFAULT (datetime(now)) ) ); // 插入数据 const insert db.prepare(INSERT INTO users (name, email) VALUES (?, ?)); const result insert.run(张三, zhangsanexample.com); console.log(插入的 ID:, result.lastInsertRowid);注意db.pragma(journal_mode WAL)是有返回值的如果你在 Node 里打印它会看到一个数组比如[{ journal_mode: wal }]。如果你执行时结果不是wal而是delete或off说明 WAL 没有启用成功常见原因是文件系统不支持或数据库已经处于其他锁定状态。2.3 从 node-sqlite3 迁移API 对照和思维转变迁移的核心不是 API而是思维。node-sqlite3 是异步回调模型而 better-sqlite3 是同步模型这意味着所有依赖回调的代码都要重写成直接返回值。下面是常用 API 的对照表操作node-sqlite3better-sqlite3打开数据库new sqlite3.Database(path, cb)new Database(path)查询全部行db.all(sql, params, cb)db.prepare(sql).all(...params)查询单行db.get(sql, params, cb)db.prepare(sql).get(...params)增删改db.run(sql, params, cb)db.prepare(sql).run(...params)多语句执行db.exec(sql, cb)db.exec(sql)事务手动BEGIN/COMMIT 回调db.transaction(fn)一个从 node-sqlite3 迁移的最小例子// node-sqlite3 老代码 db.get(SELECT * FROM users WHERE id ?, [1], (err, row) { if (err) throw err; console.log(row); }); // better-sqlite3 新代码 const row db.prepare(SELECT * FROM users WHERE id ?).get(1); console.log(row);迁移过程中最大的坑是异步上下文。比如原来的代码里从db.all回调拿到数据后再去调用其他异步函数发 HTTP 请求、读文件等现在 better-sqlite3 是同步返回原本在回调里执行的逻辑会提前执行。这不是坏事但重构时要仔细梳理依赖关系避免遗漏。3. better-sqlite3 核心 API 与事务的正确写法3.1 prepare、get、all、iterate 怎么选better-sqlite3 的 statement 方法不多但每个都有明确的使用场景.get(...params)只取第一行适合按主键查询、判断记录是否存在。它内部做了优化找到第一行后就会停止不会扫描完整结果集。.all(...params)取出所有行到内存适合数据量控制在可接受范围的查询。.iterate(...params)惰性返回迭代器逐行读取适合处理很大的结果集。比如导出全部用户数据到 CSV用all可能内存飙升用iterate就很稳。const stmt db.prepare(SELECT * FROM users); for (const row of stmt.iterate()) { // 逐行处理内存占用稳定 }选择顺序建议是能用get就别用all数据量大时用iterate而不是all。另外所有来自用户的参数都必须通过?或命名参数绑定千万不要拼字符串进 SQL否则既有注入风险还会破坏 SQLite 的语句缓存。3.2 db.transaction 的封装与嵌套事务better-sqlite3 的 transaction 是我最推荐的功能,它不只是简单地BEGIN/COMMIT,还解决了异常回滚问题。const insertUser db.transaction((name, email) { db.prepare(INSERT INTO users (name, email) VALUES (?, ?)).run(name, email); }); insertUser(李四, lisiexample.com);事务函数在内部执行过程中如果抛异常会自动回滚不需要你在外面 try/catch 后再手动ROLLBACK。这个特性让事务代码变得非常简洁。嵌套事务也支持外层事务函数里调用另一个事务函数会在内部自动使用 savepoint。这在多个业务模块各写各的事务、最后组装成一个整体事务时非常有用。const insertOrder db.transaction(order { insertUser(order.user.name, order.user.email); insertOrderItem(order.item); });你不需要手动管理 savepointbetter-sqlite3 会在嵌套事务边界自动处理。但有一点要注意事务函数必须是同步函数不能是 async。如果写成 asyncSQLite 的事务可能在第一次 await 时就丢了上下文而且报错信息非常迷惑。我的规则很简单所有 async 操作全部放到事务函数外部完成事务函数内部只做数据库读写。3.3 批量写入的性能差距真实的例子我见过太多人抱怨“SQLite 写入慢”结果是因为逐条插入且没有包事务。SQLite 默认情况下每条INSERT都会自动开启一个事务并 Commit而每次 Commit 都要触发磁盘同步这个同步的开销远大于插入本身的 CPU 开销。一个能直接感受到差距的例子批量插入 1 万条数据。const insert db.prepare(INSERT INTO users (name, email) VALUES (?, ?)); // 错误示范不包事务 for (let i 0; i 10000; i) { insert.run(user${i}, user${i}example.com); } // 正确示范包事务 const insertAll db.transaction((n) { for (let i 0; i n; i) { insert.run(user${i}, user${i}example.com); } }); insertAll(10000);在我自己的测试机上第一种方式耗时在秒级以上第二种方式通常在几百毫秒内完成具体数字和磁盘类型、WAL 配置有关但差距基本是数量级的。如果你还在用 node-sqlite3想提升批量写入性能也优先检查是不是缺了事务包裹。4. 性能调优那些必须设置的 PRAGMA 和索引4.1 必开 PRAGMA 组合SQLite 默认配置偏保守如果不主动调性能很吃亏。我每次新建项目连接初始化时基本固定执行下面这几个 PRAGMAconst db new Database(app.db); db.pragma(journal_mode WAL); db.pragma(synchronous NORMAL); db.pragma(busy_timeout 5000); db.pragma(foreign_keys ON); db.pragma(cache_size -64000);为什么是这一套journal_mode WAL启用预写日志允许读操作和写操作并发执行写入性能提升非常明显。代价是磁盘上会多出-wal和-shm文件不算什么大问题。synchronous NORMAL在 WAL 模式下NORMAL已经能保证足够的持久性同时减少磁盘 fsync 次数。它的含义是不要求每次 checkpoint 都同步但关键 WAL 文件同步点仍然保留。若数据库写入要求极高可靠性比如财务流水可以保守用FULL但性能会下降。busy_timeout 5000当其他连接持有写锁时SQLite 等待 5 秒而不是直接报SQLITE_BUSY。对偶发锁冲突很有效。foreign_keys ONSQLite 默认不启用外键约束不开启的话你在表结构里写REFERENCES xxx都是摆设。cache_size -64000把 SQLite 页缓存设置到 64MB负号表示 KB。注意是每个连接的缓存不要设得过大。还有一个容易被忽视的temp_store MEMORY把临时表和排序结果放到内存里能提升带ORDER BY和GROUP BY的查询速度。但如果你有超大排序内存占用会明显上升必须按场景取舍。4.2 不需要连接池单连接才是最优解node-sqlite3 时代养成的习惯是管理连接池因为异步并发场景下多个连接可以并行处理请求。但 better-sqlite3 是同步 API一个进程内真的不太需要多连接。原因有二第一SQLite 本身是单写者模型多个连接同时写会产生锁竞争写性能不升反降。第二better-sqlite3 建立连接的开销不小但如果只建一个连接并在模块内部共享反而最简单可靠。官方文档也明确建议“一个进程一个数据库实例”。你可以把数据库实例放在一个模块里导出// db.js const Database require(better-sqlite3); const db new Database(process.env.DATABASE_PATH || app.db); module.exports db;这样其他模块直接require(./db)永远拿的是同一个实例。唯一要注意的是如果你开了多个 better-sqlite3 连接指向同一个数据库文件必须设置好busy_timeout和 WAL否则并发写时大概率会频繁遇到锁错误。4.3 索引设计与执行计划检查better-sqlite3 不提供慢查询日志但你可以用原生 SQLite 的能力来分析执行计划。最常用的是EXPLAIN QUERY PLANconst plan db.prepare(EXPLAIN QUERY PLAN SELECT * FROM users WHERE email ?).all(xexample.com); console.log(plan);如果输出里出现SCAN users说明这条查询是全表扫描数据量大时就要考虑加索引。判断标准很简单查询条件里的字段只要不是主键且查询频率足够高就加索引。db.exec(CREATE INDEX IF NOT EXISTS idx_users_email ON users(email));加完索引后再执行一遍EXPLAIN QUERY PLAN应该能看到SEARCH users USING INDEX idx_users_email。这是我在定位慢查询时最常用的手段比各种 profiling 工具都直观。另外SQLite 一个常见的隐性开销是动态生成 SQL 后频繁 prepare。如果某个查询模式很固定强烈建议把 prepared statement 缓存起来。最简单的方式是模块初始化时统一 prepareconst stmts { getUserById: db.prepare(SELECT * FROM users WHERE id ?), getUserByEmail: db.prepare(SELECT * FROM users WHERE email ?), };这样既避免了重复解析 SQL也让代码结构更清晰。缺点是你得维护这些语句集合但收益大于成本。5. 什么时候不该用 better-sqlite35.1 多进程或多服务器并发直连同一个文件SQLite 本身支持多进程访问同一文件但引入 WAL 后锁竞争依然存在。如果你的应用是多个 Node.js 进程同时打开同一个 SQLite 文件例如 PM2 集群模式下的多个 Worker一旦有写操作其他进程的写请求就会排队等待。遇到高峰期SQLITE_BUSY会频繁出现。这种情况下busy_timeout只能缓解排队不能根治并发写瓶颈。如果并发写是常态更好的方案是把 SQLite 封装在一个独立服务里通过 IPC 或 HTTP 接口让其他进程访问或者直接迁移到 PostgreSQL、MySQL 这类具备服务端并发能力的数据库。better-sqlite3 文档里的建议是“一个进程一个数据库实例”这也说明它默认使用场景不是多进程共享。如果你必须用多进程又不想换数据库可以试试 single-writer 模型只有一个进程负责写其他进程只读。只读并发在 WAL 模式下表现很稳定。5.2 慢查询会阻塞事件循环的高并发服务虽然 better-sqlite3 同步 API 在大多数查询场景下够快但如果某个查询特别复杂数据量特别大它会卡住整个事件循环。在对外 API 服务中这意味着其他请求的响应会被一起拖慢。node-sqlite3 的优势恰好体现在这里因为查询在线程池执行主线程的事件循环还能继续处理其他请求。注意这只对慢查询有意义微秒级别的快查询在线程池里反而会因为线程切换变慢。如果项目里存在“慢查询 高并发服务端”的组合你可以这样处理把 SQLite 查询封装到worker_threads子线程里子线程用 better-sqlite3通过postMessage将结果传回主线程。这样既能享受 better-sqlite3 的高性能又不会阻塞主事件循环。代价是代码复杂度上升。5.3 跨网络访问数据库的场景SQLite 是嵌入式数据库不是网络数据库。把 db 文件放在 NFS 或 SMB 网络共享目录上让多台服务器同时访问是非常危险的做法。网络文件系统的锁语义和本地文件系统不一致轻则性能极差重则数据库损坏。这种场景下应该直接考虑 PostgreSQL、MySQL、MariaDB或者使用 libSQL 的 Turso 这种提供同步服务的方案。better-sqlite3 局限于单机场景跨机器访问不是它的适用领域。5.4 与异步生态强绑定的 ORM 或框架场景如果你的项目依赖 Sequelize 这类 ORM并且你希望保持异步模型统一那么 better-sqlite3 会带来集成困难。虽然 Sequelize 支持通过dialectModule传自定义驱动但 better-sqlite3 的同步 API 本身就和 ORM 的异步接口设计相悖强行适配会出现很多边角问题。这种情况要么继续用 node-sqlite3 作为驱动要么换一个原生支持 better-sqlite3 的查询构建器比如 Kysely 有对应的 dialect要么干脆放弃 SQLite 改成 PostgreSQL。我的建议是工具适配生态不要让生态适配工具。下面这张表是我自己选型时的参考场景推荐方案原因单机工具脚本、桌面应用、嵌入式中小型存储better-sqlite3快、简单、可靠单实例 Node 服务端查询量中等且快速better-sqlite3同步 API 清晰性能足够多进程共享同一 SQLite 文件better-sqlite3 单写进程或换数据库避免锁竞争对延迟极敏感的高并发 API 服务node-sqlite3 / worker_threads / PostgreSQL避免阻塞事件循环多台服务器共享数据PostgreSQL / MySQL / TursoSQLite 不是网络数据库浏览器端存储sql.js / WASM 方案better-sqlite3 无法在浏览器运行5.5 BigInt 精度坑与大整数存储这块很多人没意识到。SQLite 的 INTEGER 最大可以存 64 位整数但 better-sqlite3 默认会把整数读成 JavaScript Number。Number 能精确表示的范围只有Number.MAX_SAFE_INTEGER也就是 9007199254740991。如果数据库里存了超出这个范围的数值比如某些 ID 生成策略或第三方系统返回的大整数读出来会丢精度。better-sqlite3 提供了全局配置db.defaultSafeIntegers(true);开启后所有读取的整数都会变成 BigInt保证不会丢精度。代价是代码里所有整数判断都要兼容 BigInt比较麻烦。我的习惯是只在确实需要读取超大整数时才开启或者干脆在设计表时避免使用超过安全范围的整数主键。6. 常见错误与排查经验6.1 SQLITE_BUSY 与连接“忙”的处理这是 better-sqlite3 用户最常见的问题报错信息有两种第一种是SqliteError: database table is locked。这种通常来自其他进程或连接持有写锁当前连接等待超过busy_timeout后放弃。排查步骤确认是否只有一个 db 实例、是否开启了 WAL、busy_timeout是否设置合理。第二种是SqliteError: This database connection is busy executing a query。这种比较特殊它发生在同一个 db 实例上你尝试在一个 statement 还没执行完时又执行另一个 statement。better-sqlite3 是同步 API正常情况下不会并行但如果你在代码里用 Promise 或setImmediate做了奇怪的调用顺序或者你在事务函数里await了另一个 async 函数就可能触发。例如下面这段代码就会踩坑db.transaction(() { db.prepare(UPDATE users SET name ?).run(hello); someAsyncFunction().then(() { db.prepare(INSERT INTO logs ...).run(); }); })();事务还没结束内部又发起异步任务并在回调里执行同一条连接上的新语句直接报 busy。修复方式很简单别在事务里做异步操作把所有异步逻辑挪到事务结束之后。6.2 参数绑定错误这是一个容易忽略的细节better-sqlite3 的.run()、.get()、.all()接受可变参数传数组时需要用展开运算符或者直接传入多个参数const stmt db.prepare(SELECT * FROM users WHERE id ? AND status ?); stmt.get(1, active); // 正确 stmt.get([1, active]); // 错误这里会把数组当作第一个参数如果你习惯 node-sqlite3 的db.all(sql, [params], cb)风格迁移时很容易写错。我的建议是全项目统一用可变参数形式不要在调用时传数组。如果参数本身是数组需要动态展开用展开运算符const params [1, active]; stmt.get(...params);6.3 参数过多与 SQLITE_RANGE 报错SQLite 默认单条 SQL 语句最多支持 999 个参数SQLITE_MAX_VARIABLE_NUMBER。如果你一次性插入一行有上千列或者用IN (?, ?, ?, ...)传超大数组会直接报SqliteError: too many SQL variables。解决思路有两个一是分批插入每批限制在几百个参数二是对于批量插入还是回到事务循环的老路避免单条 SQL 参数爆炸。这个错误在生成动态同步脚本时特别常见写个循环包一层事务就能解决。6.4 外键约束为什么没有生效这是所有 SQLite 新手几乎都会遇到的问题明明在表结构里写了FOREIGN KEY删除父表记录时子表却没有被约束。原因不是代码错了而是 SQLite 默认不启用外键约束。你必须在连接初始化后执行db.pragma(foreign_keys ON);这个 PRAGMA 是每个连接独立的不是全局配置。如果你开了多个连接忘了在某一个连接上设置那这个连接的所有操作都不会检查外键。这一点在 with better-sqlite3 多连接场景下尤其危险。6.5 WAL 模式与文件系统的兼容问题WAL 模式在大多数文件系统上表现良好但在某些网络文件系统NFS、SMB上会无法正常工作甚至抛错。如果你发现设置journal_mode WAL后返回结果不是wal最好检查一下数据库文件所在目录的写权限和文件系统类型。另外WAL 模式会生成临时的-wal和-shm文件如果你在部署环境里做了容器化不要漏掉和数据库文件同目录下的这两个文件否则备份或持久化可能不完整。6.6 内存泄漏的排查方向better-sqlite3 项目做久了偶尔会遇到内存持续上涨的问题。常见的元凶不是连接本身而是 prepared statement 没有释放。每次db.prepare(sql)都会创建一个新的语句对象如果你在循环里反复 prepare 而不复用SQLite 会为每条语句缓存执行计划内存占用会慢慢涨上去。排查思路也比较简单检查代码里是否有动态拼接 SQL 或高频调用db.prepare的地方改成模块启动时统一 prepare 并缓存。如果确实需要动态条件可以引入查询构建器在构建完 SQL 后再 prepare而不是每次请求都生成新的 SQL 字符串。关于 better-sqlite3 使用心得回到我自己的项目里现在凡是单机工具、桌面应用、内部管理后台这类场景我基本默认选 better-sqlite3。它在绝大多数查询上的性能表现都好于 node-sqlite3同步 API 也减少了回调嵌套和思维负担。但到了多进程并发、跨机器访问、异步高并发服务这些场景我不会硬上该换数据库就换数据库。如果让我说一个最重要的实践建议那就是提前写好连接初始化把 WAL、synchronous、busy_timeout、foreign_keys、cache_size 这些 PRAGMA 统一设置好再把所有 prepared statement 集中管理。这样你大概率会遇到的问题在这篇文章里已经被提前解决掉一大半了。