说实话，我是从 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('张三', 'zhangsan@example.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-sqlite3 | better-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('李四', 'lisi@example.com');事务函数在内部执行过程中如果抛异常，会自动回滚，不需要你在外面 try/catch 后再手动ROLLBACK。这个特性让事务代码变得非常简洁。
嵌套事务也支持：外层事务函数里调用另一个事务函数，会在内部自动使用 savepoint。这在多个业务模块各写各的事务、最后组装成一个整体事务时非常有用。
const insertOrder = db.transaction(order => { insertUser(order.user.name, order.user.email); insertOrderItem(order.item); });你不需要手动管理 savepoint，better-sqlite3 会在嵌套事务边界自动处理。但有一点要注意：事务函数必须是同步函数，不能是 async。如果写成 async，SQLite 的事务可能在第一次 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 默认配置偏保守，如果不主动调，性能很吃亏。我每次新建项目，连接初始化时基本固定执行下面这几个 PRAGMA：
const 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 = ON：SQLite 默认不启用外键约束！不开启的话你在表结构里写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 PLAN：
const plan = db.prepare('EXPLAIN QUERY PLAN SELECT * FROM users WHERE email = ?').all('x@example.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 缓存起来。最简单的方式是模块初始化时统一 prepare：
const stmts = { getUserById: db.prepare('SELECT * FROM users WHERE id = ?'), getUserByEmail: db.prepare('SELECT * FROM users WHERE email = ?'), };这样既避免了重复解析 SQL，也让代码结构更清晰。缺点是你得维护这些语句集合，但收益大于成本。
5. 什么时候不该用 better-sqlite3
5.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 / Turso | SQLite 不是网络数据库 |
| 浏览器端存储 | 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 集中管理。这样你大概率会遇到的问题，在这篇文章里已经被提前解决掉一大半了。
