一个面向小程序与 Web 宿主的可插拔 SQLite driver workspace。
文档站：sqlite.weapp.dev。文档源码位于 apps/docs，使用 Fumadocs 构建为纯静态站点，并由 Cloudflare Worker 的 Static Assets 托管。
如果你是第一次使用，建议先阅读快速开始。本项目适合把数据保存在用户设备上，不是远程数据库或线上运营后台。
- Node.js 22.22.1+
- pnpm 12（使用 npm 时把
pnpm add换成npm install） - 一个可以正常运行的 weapp-vite 项目
- 验收微信时登录微信开发者工具
当前实现刻意分成七个边界：
@weapp-sqlite/core：定义异步连接、查询、事务和迁移协议，不依赖具体 SQLite 引擎。@weapp-sqlite/wasm：把可注入的 SQLite WASM 引擎（例如sql.js）接到 core，并通过存储回调持久化数据库文件。@weapp-sqlite/sqljs：提供默认 full 与裁剪后的 lite sql.js 引擎、WASM 资源和构建期资源解析。@weapp-sqlite/web：使用 IndexedDB 持久化 Web 二进制数据库，不回退到内存。@weapp-sqlite/miniprogram：六个小程序目标共用的文件系统、能力探测和 WebAssembly 实例化协议。@weapp-sqlite/debug：开发期表结构、分页数据、受控 SQL 和 SQLite 快照管理控制器。@weapp-sqlite/weapp-vite：构建期选择目标 adapter 和 WASM，运行时统一为openSqlite()。
业务代码可以保持一致，但各目标仍然是独立产物。插件只注入当前目标 runtime；支付宝、抖音、百度、京东和小红书虽已有可探测 adapter，在完成官方 DevTools 与 iOS/Android 宿主验收前仍不宣称正式支持。
weapp-vite 项目安装统一集成包：
pnpm add @weapp-sqlite/weapp-vite// vite.config.ts
import { weappSqlite } from '@weapp-sqlite/weapp-vite'
import { defineConfig } from 'weapp-vite'
export default defineConfig({ plugins: [weappSqlite()] })默认 full + main 保持原有行为。微信主包敏感的项目推荐改用 lite 自动分包：
weappSqlite({
wasm: {
variant: 'lite',
weappPackage: { mode: 'generated-subpackage' },
},
})lite 保留表、索引、事务、触发器、CTE、JSON1、ALTER、参数绑定、BLOB 和数据库导入导出，不提供 FTS3、normalize 与 sql.js 贡献数学/字符串函数。自动分包通过 weapp-vite 自动路由写入最终 app.json，应用配置可来自 app.json.ts、app.json.js 或 app.vue 中的 defineAppJson()；最终清单缺少生成分包时构建失败。静态 app.json 项目仍可绑定已有普通分包。详见小程序 SQLite 方案与包体选择。
import { openSqlite } from '@weapp-sqlite/weapp-vite/runtime'
const database = await openSqlite({ name: 'app.sqlite', migrations })
await database.exec('CREATE TABLE IF NOT EXISTS notes (id INTEGER PRIMARY KEY, body TEXT NOT NULL)')
await database.exec('INSERT INTO notes (body) VALUES (?)', ['hello'])
const result = await database.query<{ id: number, body: string }>('SELECT id, body FROM notes')
await database.close()所有数据库操作都是异步的。事务会串行执行，并在回调成功后提交；回调抛错时自动回滚。同名并发打开会合并，adapter 或迁移配置冲突时返回 SQLITE_OPEN_OPTIONS_CONFLICT，能力缺失时不会退回内存。
建议先掌握四个动作：定义迁移、openSqlite()、使用绑定参数读写、flush()/close()。完整解释见核心概念。
runtime 还提供事务化批量执行和只读迁移诊断：
import { execMany, getMigrationStatus } from '@weapp-sqlite/weapp-vite/runtime'
await execMany(database, 'INSERT INTO notes (body) VALUES (?)', [['第一条'], ['第二条']])
const status = await getMigrationStatus(database, migrations)
console.log(status.pending, status.conflicts)事务中任一操作失败都会整体回滚；提交成功但保存失败会抛出 SqlitePersistenceError，官方 adapter 会保留待保存状态，此时应重试 flush()，不要重复业务写入。自定义 WASM 引擎需要无副作用的 exportSnapshot()，自定义连接还需要保留失败后的待保存状态，详见升级指南。
开发数据工作台通过 WEAPP_SQLITE_DEBUG=1 编译开关启用，支持筛选、排序、分页、行 CRUD、表/列/索引管理、受控 SQL、单步撤销，以及 SQLite/CSV/JSON 导入导出。默认生产构建不生成工作台路由，也不打包写 SQL、codec 或宿主文件 API。详细操作见调试工作台。
需要独立 Devframe 面板时安装 @weapp-sqlite/devtools，并设置 debug.devtools: true。开发服务会输出带一次性认证 URL 的面板地址，面板先选运行实例再选数据库；Web 使用 loopback WebSocket，微信开发工具使用 wx.connectSocket，请求由应用真实连接执行。每库保留最近 50 条 SQL 历史和参数化 EXPLAIN QUERY PLAN 结果，watch 重建复用服务，退出时释放端口和调试会话。
weappSqlite({
debug: {
enabled: process.env.WEAPP_SQLITE_DEBUG === '1',
devtools: process.env.WEAPP_SQLITE_DEVTOOLS === '1',
page: {
route: '__weapp_sqlite_debug/index/index',
configFile: './src/sqlite-debug.config.ts',
},
},
})// src/sqlite-debug.config.ts
import { defineSqliteDebugWorkspace } from '@weapp-sqlite/weapp-vite/debug'
import { migrations } from './sqlite'
export default defineSqliteDebugWorkspace({
databases: [
{ databaseName: 'app.sqlite', migrations },
{ databaseName: 'analytics.sqlite', migrations: analyticsMigrations },
],
defaultDatabase: 'app.sqlite',
})生成页使用 weapp-vite 自动路由注册独立分包。采用静态 app.json 的项目需升级为 app.json.ts，从 weapp-vite/auto-routes 写入 subPackages；生产构建得到空数组，调试构建才包含工作台。
pnpm install
pnpm build
pnpm lint
pnpm typecheck
pnpm tsd
pnpm test依赖维护使用仓库统一命令：
pnpm deps:check # 查看可升级项和被兼容策略保护的依赖
pnpm deps:update # 升级可安全升级的直接依赖并刷新 pnpm-lock.yaml
pnpm validate # 升级后执行完整构建、类型、API 和测试门禁维护命令会保护已验证的框架边界：TypeScript 维持 6.x，Taro 维持 4.2.1 + React 18，MPX 维持 Vue 2.7 + Babel 7 + Webpack 5.110.2，uni-app 维持同一 Vue3 alpha 发布批次与 Vite 8.2.2。命令会在输出中列出每项保护原因；框架升级应先完成对应迁移和 demo 构建，再调整 scripts/dependency-policy.ts。
文档站本地开发与部署：
pnpm --filter @weapp-sqlite/docs dev
pnpm --filter @weapp-sqlite/docs build
pnpm --filter @weapp-sqlite/docs run deploy:dry
pnpm --filter @weapp-sqlite/docs run deploy当前测试使用 sql.js 验证 WASM adapter 的真实 SQL 链路，并使用 Playwright 对 Web 生产产物执行 IndexedDB 持久化验收。微信支持仍必须经过真实 DevTools 与 iOS/Android 真机门禁。
examples/ 提供同一个 migration + transaction 场景的四套实现，共享层只负责 SQLite 业务流程，各框架只负责宿主存储 API：
examples/weapp-vite-multi-platform：正式验收应用，可构建weapp、alipay、tt、swan、jd、xhs和 Web；Web 与真实 DevTools 自动验收已通过，微信真机仍需完成 iOS/Android 门禁。examples/taro：Taro 4 + React。examples/uni-app：uni-app Vue 3。examples/mpx：MPX + Webpack 5。
安装依赖后，可以分别运行 wiring 测试、类型检查和构建：
pnpm install
pnpm --filter @weapp-sqlite/demo-shared test
pnpm --filter @weapp-sqlite/demo-shared typecheck
pnpm --filter weapp-sqlite-demo-weapp-vite test
pnpm --filter weapp-sqlite-demo-weapp-vite typecheck
pnpm --filter weapp-sqlite-demo-weapp-vite build:weapp
pnpm --filter weapp-sqlite-demo-weapp-vite build:alipay
pnpm --filter weapp-sqlite-demo-weapp-vite build:tt
pnpm --filter weapp-sqlite-demo-weapp-vite build:swan
pnpm --filter weapp-sqlite-demo-weapp-vite build:jd
pnpm --filter weapp-sqlite-demo-weapp-vite build:xhs
pnpm --filter weapp-sqlite-demo-weapp-vite build:web
pnpm --filter weapp-sqlite-demo-taro test
pnpm --filter weapp-sqlite-demo-taro typecheck
pnpm --filter weapp-sqlite-demo-taro build:weapp
pnpm --filter weapp-sqlite-demo-uni-app test
pnpm --filter weapp-sqlite-demo-uni-app typecheck
pnpm --filter weapp-sqlite-demo-uni-app build:weapp
pnpm --filter weapp-sqlite-demo-mpx test
pnpm --filter weapp-sqlite-demo-mpx typecheck
pnpm --filter weapp-sqlite-demo-mpx build:weappweappSqlite() 会确定性发射当前 variant 所需的单个 WASM 文件。full 保持 Web 的 sql-wasm-browser.wasm 与小程序的 sql-wasm.wasm；lite 统一使用 sql-wasm-lite.wasm。微信可通过静态 require.async() 把初始化器与 WASM 放入同一普通分包，其余目标忽略 weappPackage。其余五个平台保持可构建，运行或文件交付能力未通过真实宿主门禁时返回结构化 unsupported，不得视为正式支持。
完整门禁命令为 pnpm acceptance:build、pnpm acceptance:web、pnpm acceptance:debug:web、pnpm acceptance:devtools:doctor、pnpm acceptance:devtools、pnpm acceptance:debug:devtools、pnpm acceptance:mobile:prepare 和 pnpm acceptance:verify。汇总器要求 Web，以及六个平台各自的官方 DevTools、当前稳定 iOS 和 Android 宿主报告；缺少任一当前 commit 证据的平台不得标记正式支持。