把一个真正的关系型数据库跑在浏览器里，曾经只是个美好的设想。localStorage只有5MB容量且只能存字符串，IndexedDB虽然容量大但API繁琐、查询能力弱，复杂的关联查询和事务处理写起来相当痛苦。SQLite官方推出的WASM版本改变了这个局面，它不仅把完整的SQLite引擎编译成了WebAssembly，还针对浏览器环境设计了基于OPFS的持久化后端，让网页应用可以拥有一个高性能、支持SQL完整语法、数据真正落盘的本地数据库。本文将从OPFS的原理讲起，逐步完成一个可运行的SQLite实战项目。
一、OPFS是什么，为什么它对SQLite如此重要
OPFS全称Origin Private File System，即源私有文件系统。它是现代浏览器提供的一组文件系统API，属于File System Access API的扩展部分。与传统的用户可见文件系统不同，OPFS在浏览器内部开辟了一块沙箱化的存储空间，这块空间对用户不可见、对网页源（origin）私有，用户无法通过文件管理器直接浏览里面的内容。它存在的意义就是给Web应用提供一个高性能的文件读写通道，特别适合数据库这类需要频繁随机读写的场景。
OPFS之所以重要，关键在于它提供了两种访问句柄：普通句柄和同步访问句柄。普通句柄通过createWritable()写入数据，每次操作都要经历打开、写入、关闭的完整流程，性能开销不小。而同步访问句柄（SyncAccessHandle）只能在Web Worker中使用，通过createSyncAccessHandle()获取，读写操作是同步阻塞的，省去了异步调用的开销，更妙的是它允许多个Worker通过Atomics和SharedArrayLock机制协调对同一文件的访问。对于SQLite这种依赖大量小粒度随机读写的引擎来说，同步访问句柄的性能提升是数量级的，官方基准测试显示它比IndexedDB后端快出数倍甚至数十倍。
目前OPFS在Chrome 86+、Edge、Safari 15.2+和Firefox 111+中均已可用，但同步访问句柄的支持情况略有差异，Firefox直到较新版本才完整支持。因此在实际项目中，建议做能力检测并准备降级方案，比如降级到IndexedDB或者内存数据库。下面是标准的特性检测代码：
async function checkOpfsSupport() {
if ('storage' in navigator && 'getDirectory' in navigator.storage) {
try {
const root = await navigator.storage.getDirectory();
return { supported: true, root };
} catch (e) {
console.warn('OPFS 不可用：', e);
}
}
return { supported: false };
}
二、选择正确的SQLite WASM发行版
社区里常见的方案有两类：一类是sql.js，一类是SQLite官方的sqlite3 WASM。sql.js出现得早，使用简单，但它有一个致命缺陷——整个数据库必须完整加载到内存中，所有修改也只有导出二进制 blob 后手动保存才能落盘，数据量一大性能和内存都会崩。官方的sqlite3 WASM（从3.43版本起提供OPFS VFS支持）则实现了真正的增量读写，它通过一个运行在Worker中的OPFS代理（opfs-sahpool或旧的opfs VFS），把SQLite的文件操作直接映射到OPFS的同步访问句柄上，只在需要时读写对应的页，这正是数据库应有的工作方式。
官方发行版提供了几种构建形态，推荐使用@sqlite.org/sqlite-wasm这个npm包，引入其中的sqlite3-bundler-friendly.mjs。需要注意Worker的加载方式：如果用Vite或Webpack，需要以?url或?worker的方式引入Worker相关资源，避免打包器把WASM文件内联成base64导致初始化失败。下面是一个在Web Worker中初始化OPFS后端数据库的完整示例：
// db-worker.js
import { sqlite3Worker1Promiser } from '@sqlite.org/sqlite-wasm';
const promiser = sqlite3Worker1Promiser.v2();
async function openDb() {
const config = {
promiser,
// 指定使用 OPFS 持久化后端
vfs: 'opfs',
filename: 'app.sqlite3'
};
const { dbId } = await new Promise((resolve, reject) => {
promiser('open', {
...config,
callback: (result) => result.type === 'error'
? reject(result.result)
: resolve(result)
});
});
return dbId;
}
self.onmessage = async (e) => {
const { action, sql, params } = e.data;
if (action === 'exec') {
const result = await new Promise((resolve) => {
promiser('exec', {
dbId: e.data.dbId,
sql,
bind: params,
callback: (r) => resolve(r.result)
});
});
self.postMessage({ ok: true, result });
}
};
如果不想自己处理Worker通信的复杂度，官方还提供了opfs-sahpool这种更简单的VFS，它不需要专用的Worker代理，直接在当前Worker里就能用，代码量更少，兼容性也更好，代价是同一时刻只能有一个数据库连接实例访问它管理的文件池。对于单连接的典型前端应用，这反而是最省心的选择。
三、实战：封装一个带持久化的SQLite服务
实际项目中，主线程不应该直接操作数据库，正确姿势是把SQLite放进Worker，主线程通过消息通信调用。下面给出一个精简但可直接使用的封装，使用opfs-sahpool后端，省去了Worker代理的麻烦：
// worker.js
import { default as sqlite3InitModule } from '@sqlite.org/sqlite-wasm';
let db = null;
sqlite3InitModule().then((sqlite3) => {
return sqlite3.ioOpfsSAHPoolUtil
? sqlite3.ioOpfsSAHPoolUtil.setVerbose(1)
: null;
}).then(() => {
// 稍后用模块作用域的 sqlite3 打开数据库
});
// 更常见的写法：
sqlite3InitModule().then((sqlite3) => {
const poolUtil = sqlite3.ioOpfsSAHPoolUtil;
db = new sqlite3.oo1.OpfsSAHPoolDb('app.sqlite3');
db.exec(`
CREATE TABLE IF NOT EXISTS notes (
id INTEGER PRIMARY KEY AUTOINCREMENT,
title TEXT NOT NULL,
content TEXT,
updated_at INTEGER DEFAULT (unixepoch())
);
`);
self.postMessage({ type: 'ready' });
});
self.onmessage = (e) => {
const { type, payload } = e.data;
if (!db) return;
try {
if (type === 'insert') {
db.exec({
sql: 'INSERT INTO notes(title, content) VALUES(?, ?)',
bind: [payload.title, payload.content]
});
self.postMessage({ type: 'result', ok: true });
} else if (type === 'query') {
const rows = db.exec({
sql: 'SELECT * FROM notes ORDER BY updated_at DESC LIMIT ?',
bind: [payload.limit || 50],
rowMode: 'object'
});
self.postMessage({ type: 'result', ok: true, rows });
}
} catch (err) {
self.postMessage({ type: 'error', message: String(err) });
}
};
主线程侧再包一层Promise化的调用接口，隐藏消息通信细节，上层业务代码就像调用普通异步函数一样自然。这种架构的另一个好处是隔离性：即使某条慢查询把Worker卡住，主线程的渲染和交互完全不受影响，界面上最多显示一个加载状态，而不是整个页面冻结。
最后要提几个容易踩的坑。第一，OPFS的存储受浏览器配额管理，可以在注册Service Worker后通过navigator.storage.persist()申请持久化存储，降低数据被自动清理的概率。第二，OPFS数据与浏览器源绑定，用户清除站点数据时会一并删除，重要数据务必提供导出备份功能，可以用db.exportUint8Array()把数据库导出为文件下载。第三，开发环境如果通过HTTP而非HTTPS访问，某些浏览器会禁用相关API，本地调试建议用localhost或配置证书。掌握这些要点后，你就可以在纯前端环境里构建一个功能完整、性能可靠的本地数据库应用了。