---
title: "从 sql.js 迁移到 node:sqlite：WAL 与多源后台同步"
description: "在 Node.js 24 与 Electron 中用内置 node:sqlite WAL 替换 sql.js 全库导出：详解零重写兼容层、Gzip 懒加载缓存与 Worker 解析池，打通 Claude Code、Cursor、Codex 等 32 源本地会话同步。"
image: "https://zengliangyi.com/og/blog/migrate-sqljs-to-node-sqlite-wal-sync.png"
---

在 Node.js 与 Electron 本地优先（Local-First）应用中，`sql.js` 凭借纯 WASM 零原生编译的优势非常适合早期快速交付；但当本地 AI 编程数据源从 5 个扩展到 32 个（涵盖 Claude Code、Cursor、Codex、OpenCode、Cline 等客户端及 Windows WSL 目录）时，“主线程逐个解析 + `sql.js` 整库 `db.export()` 重写落盘”同时撞上了首屏白屏、事件循环阻塞与磁盘写放大三道墙。[ChatCrystal](/projects/chatcrystal/) 在 v0.7（对照提交 [`842e44a`](https://github.com/ZengLiangYi/ChatCrystal/tree/842e44a)）将持久化与同步链路拆解为四层架构：Node.js 24 内置 `node:sqlite` WAL 持久化、Index-First 索引优先懒加载、带解析器版本指纹的 Gzip 快照缓存，以及单飞后台同步引擎与 `worker_threads` 解析池。

此前在[sql.js WASM 数据库持久化边界](/blog/sqljs-wasm-persistence/)与[海量对话批量导入性能优化方案](/blog/bulk-import-performance-plan/)中，我们定位过全量内存导出和单线程导入的瓶颈。本文复盘如何把这些诊断落地为可复用的工程实现，并诚实记录审视代码时新发现的三处并发与交互边界。

## 为什么 `sql.js` 全库导出在多源高并发同步下会成为瓶颈

`sql.js` 将整个 SQLite 数据库驻留在 WASM 线性内存中，本身不直接映射宿主机磁盘页；一旦消息表增长到数十万行，且接入 32 个包含上百 MB 外部状态库（如 `opencode.db`）、多帧拼接 `.jsonl.zst` 日志与数万插件文件的目录时，原有导入链路会在三个位置同时退化：

- 存储层整库重写写放大 ：每次调用 `saveDatabase()` 与 30 秒定时保存都必须执行 `db.export()`，在内存中分配完整的 `Uint8Array` 副本并从头覆写 `chatcrystal.db`，保存动作本身演变为周期性内存尖峰与同步 I/O 阻塞。

- 首屏可见性与最慢解析器强绑定 ：`importAll()` 必须等前序会话全文解析入库后，前端列表才能看到记录。遇到大体积外部 SQLite 或慢速 `\\wsl.localhost` 路径时，主线程上的同步 JSON 解析与正则清洗还会直接阻塞 Fastify HTTP 响应。

- 手动按钮与文件监听器各自为政 ：前端依赖一次性“导入”按钮，而 `chokidar` 只维护局部防抖布尔锁，既无法与启动期导入共享进度，又容易在启动全盘建树时与首轮导入争抢磁盘队列。

| 架构维度 | v0.6 旧实现 | v0.7 重构后实现 | 直接工程收益 |

| --- | --- | --- | --- |

| 主库持久化 | `sql.js` 内存库 + `db.export()` 全量写盘 | Node 24 `node:sqlite`（`DatabaseSync` + WAL） | 事务即时落盘，`saveDatabase()` 降为轻量 WAL checkpoint |

| 外部客户端 DB 读取 | `sql.js` 只读快照 | 继续保留 `sql.js`（配 20 秒空闲句柄缓存） | 不触碰宿主 IDE 活跃锁与外部 `-wal`/`-shm` |

| 列表可见时机 | 全文解析入库后才可见 | `scan()` 后立写 `pending` 索引行，正文按需懒物化 | 首屏列表耗时仅取决于目录 `fs.stat` 扫描 |

| 重复解析开销 | 仅靠 DB 行 `size + mtime` 跳过 | 叠加 `<dataDir>/transcript-cache/*.json.gz` 缓存 | 删库重建、中途取消续跑与懒加载均免重复解析 |

| 同步调度与监听 | 手动按钮 + Watcher 局部防抖锁 | 全局单飞 `SyncEngine` + 首轮同步后挂载定向 Watcher | 消除启动 I/O 踩踏，变更按最长前缀只扫归属源 |

## 从 `sql.js` 平滑迁移到 Node.js 24 `node:sqlite`（WAL 模式）

将主数据库从 `sql.js` 切换到 [Node.js 24 内置 `node:sqlite` 模块](https://nodejs.org/docs/latest-v24.x/api/sqlite.html)（Electron 44 内置 Node 24 运行时同样原生提供 `DatabaseSync`），能够在不引入 `better-sqlite3` 原生 C++ 编译链（`node-gyp` 与 Electron ABI 重编译）的前提下，直接获得真实磁盘文件连接与 [SQLite WAL（Write-Ahead Logging）模式](https://www.sqlite.org/wal.html)。

为了让既有路由、Schema 迁移与测试套件零重写切换，[`server/src/db/sqlite-compat.ts`](https://github.com/ZengLiangYi/ChatCrystal/blob/842e44a/server/src/db/sqlite-compat.ts) 用不到 400 行代码实现了 `SqliteCompatDatabase` 兼容层，精确对齐 `sql.js` 的调用语义：

- 连接初始化开启 WAL 与外键约束 ：构造阶段立即执行 `PRAGMA journal_mode = WAL`、`PRAGMA synchronous = NORMAL` 与 `PRAGMA foreign_keys = ON`。每次事务提交即落入磁盘 WAL，原本昂贵的 `saveDatabase()` 直接简化为非阻塞的 `PRAGMA wal_checkpoint(TRUNCATE)`。

- 词法级多语句切分与 `CREATE TRIGGER` 保护 ：`sql.js` 的 `exec()` 和 `run()` 支持一次传入分号分隔的多条 SQL，而 `DatabaseSync.prepare()` 每次仅接受单条语句。`splitSqlStatements()` 逐字符跳过单双引号转义、`--` 与 `/* */` 注释，并专门识别 `CREATE TRIGGER … BEGIN …; END;` 块，防止触发器体内的分号被误切分。

- 命名参数前缀与空结果集对齐 ：`sql.js` 允许参数对象键带 `:`、`$`、`@` 前缀（如 `{ ':id': 'abc' }`）且在 0 行结果时返回空数组 `[]`；兼容层在 `toNamedParams()` 与 `execPrepared()` 中抹平了这两处差异，并借助 `DatabaseSync.serialize()` 保留了备份测试所需的字节导出能力。



```ts
export   class   SqliteCompatDatabase   {  
    private   readonly   handle  :   DatabaseSync  ;  
  
    constructor  (  filePath  :   string  ) {  
      this  .handle   =   new   DatabaseSync  (filePath);  
      this  .handle.  exec  (  'PRAGMA journal_mode = WAL'  );  
      this  .handle.  exec  (  'PRAGMA synchronous = NORMAL'  );  
      this  .handle.  exec  (  'PRAGMA foreign_keys = ON'  );  
    }  
  
    checkpoint  ()  :   void   {  
      try   {  
        this  .handle.  exec  (  'PRAGMA wal_checkpoint(TRUNCATE)'  );  
      }   catch   {  
        // 存在活跃读取或未提交事务时保留当前 WAL，留待下次检查点或 close() 刷盘  
      }  
    }  
  }
```



同样关键的是**读写分治策略**：ChatCrystal 自身持有的 `chatcrystal.db` 走 `node:sqlite` WAL，但解析 Cursor（`state.vscdb`）、OpenCode（`opencode.db`）、Goose、Hermes、Alma 等第三方本地数据库时，适配器仍然使用 `sql.js` 将文件快照读入 WASM 内存。因为宿主 IDE 往往正持有这些数据库的写锁，直接挂载外部活跃 SQLite 连接极易触发 `SQLITE_BUSY` 或污染宿主的 `-wal`/`-shm` 文件，内存快照则是天然无锁的只读隔离层。

## 大体积 JSONL 与 SQLite 会话懒加载：Index-First 与 Gzip 版本化缓存

面对上千条历史会话，决定用户体感速度的不是最后一条文件何时解析完，而是列表第一屏何时可交互。[`server/src/services/import.ts`](https://github.com/ZengLiangYi/ChatCrystal/blob/842e44a/server/src/services/import.ts) 通过 **Index-First（索引优先）** 两阶段流水线将目录发现与正文解析彻底拆开。

### 第一阶段：扫描即建 `pending` 索引行，详情页按需懒物化

各源适配器的 `scan()` 仅执行目录遍历与 `fs.stat`。每扫完一个源，`importAll()` 立刻在单事务内调用 `ensureIndexedConversation()` 插入 `transcript_status = 'pending'` 的索引行（若已知文件的 `file_size` 或 `file_mtime` 变化，则保留原行并重置回 `'pending'`）。

即使后台队列仍有上千个文件待解析，前端列表也能立即展示全部会话。当用户直接点开某条 `pending` 会话（或触发摘要生成）时，[`server/src/routes/conversations.ts`](https://github.com/ZengLiangYi/ChatCrystal/blob/842e44a/server/src/routes/conversations.ts) 会即时调用 `materializeConversationById()` 插队补齐该篇正文：



```ts
if   (  
    loaded.conversation.transcript_status   &&  
    loaded.conversation.transcript_status   !==   'materialized'  
  ) {  
    const   materialized   =   await   materializeConversationById  (id);  
    if   (materialized   ===   'error'  ) {  
      reply.  status  (  500  );  
      return   { success:   false  , error:   'Failed to load the conversation transcript'   };  
    }  
    loaded   =   loadConversation  ();  
  }
```



物化阶段同步处理了两类一致性边界：若解析器读完正文后重写了规范 ID（`parsed.id !== meta.id`），会先清理扫描期插入的临时占位行；若解析后有效消息少于两条（`parsed.messages.length < 2`），则删除该 `indexOnly` 占位行，确保懒加载与全量导入的数据过滤规则严格等价。

### 第二阶段：带 `parserVersion` 指纹的原子 Gzip 快照缓存

为避免删库重导、中途取消续跑或按需物化重复解析大文件，[`server/src/services/transcript-cache.ts`](https://github.com/ZengLiangYi/ChatCrystal/blob/842e44a/server/src/services/transcript-cache.ts) 将归一化后的 `ParsedConversation` 压缩保存在 `<dataDir>/transcript-cache/<source>/<sha1>.json.gz`。

缓存键将所有会影响解析结果的输入拼成 `\0` 分隔的七元组计算 SHA-1（延伸自 [SourceAdapter 内容哈希与幂等导入设计](/blog/source-adapter-internals/)）：



```ts
function   cacheKey  (  meta  :   TranscriptCacheMeta  ,   parserVersion  :   string  )  :   string   {  
    const   parts   =   [  
      meta.source,  
      meta.id,  
      parserVersion,  
      meta.filePath,  
      String  (meta.fileSize),  
      meta.fileMtime,  
      meta.rootDir   ??   ''  ,  
    ];  
    return   createHash  (  'sha1'  ).  update  (parts.  join  (  '  \0  '  )).  digest  (  'hex'  );  
  }
```



纳入 `parserVersion`（如修复 Codex 0.160+ 事件格式后的 `codex@4`、双表去重的 `opencode@2`）与 `rootDir`（区分宿主机与 WSL 根目录）后，**任何解析逻辑升级只需递增版本号即可自动淘汰旧缓存**。写入采用 `<sha1>.json.gz.<pid>.<uuid>.tmp` 同目录临时文件加 `rename` 原子替换，并按每 20 次写入定期清理超过 `512 MB` 或 `30 天` 的冷数据；任何损坏归档或 Windows 文件锁异常均静默回退为重新解析。

## Node.js `worker_threads` 解析池（`tsx` 兼容）与 `chokidar` v4 静态目录监听

要彻底告别手动导入按钮且不拖慢开发机，后台调度必须同时管住并发冲突、CPU 隔离与文件系统监听风暴：

- 单飞状态机 `SyncEngine`（`server/src/services/sync.ts`） ：启动后 2.5 秒自动首扫、`POST /api/sync/start` 手动触发与文件变更事件全部汇入同一状态机。同一时刻最多运行一轮同步；运行期间的新触发按源合并进 `pendingSources`，待当前轮次收尾后自动续跑；`cancel()` 则清空挂起队列并通过 `AbortSignal` 在文件边界安全停机。

- 兼容 `tsx` 与打包降级的 `ParserPool`（`server/src/services/parse-pool.ts`） ：默认按 `min(4, max(1, availableParallelism() - 1))` 懒启动 `worker_threads`。针对开发态 `tsx` 运行 `.ts` 源码时子线程不自动继承 ESM Loader 的常见坑，池子根据 `import.meta.url` 自动注入 `execArgv: ['--import', 'tsx']`；若受限打包环境下首个 Worker 在 10 秒内未能就绪，则告警一次并平滑退化为主线程内联解析（`degraded = true`）。

- 首轮同步完成后才挂载的 `chokidar` v4 定向监听（`server/src/watcher/index.ts`） ：部分客户端（如 WorkBuddy）主目录下有约 7 万个插件市场文件，启动时若让 `chokidar` 建树与首轮导入并发执行，双倍 `readdir/stat` 会直接打满磁盘 I/O。因此 `createServer` 严格等 `syncManager` 完成首轮同步后才启动监听器；同时适配 `chokidar` v4 移除 glob 字符串的变更，由 `normalizeWatchTarget()` 截取首个通配符前的静态父目录，忽略 `node_modules/.git/.cache`，并在 1.8 秒防抖后按 最长路径前缀 反查变更所属的单一 `source` 触发增量同步。

## 解析 32 个 AI 编程客户端记录：共享基板、多帧 zstd 与 WSL 边界

从早期的[五种主流客户端对话存储格式](/blog/ai-conversation-data-formats/)扩展到 **32 个会话源**（涵盖 Claude Code、Cursor、Codex、Gemini CLI、OpenCode、Goose、Cline、Roo Code、Kilo Code、Continue、Claude Desktop、Copilot / Copilot CLI、Trae、Factory Droid、Antigravity、Hermes、Kimi、Qwen、MiniMax、DeepSeek Harness、Pi、omp、Raft、Cindy、ZCode、Alma、CodeBuddy、WorkBuddy、Qoder / Qoder CN、Grok Build），v0.7 没有编写 32 套孤立脚本，而是提炼出三类家族基板：**Cline 家族 VS Code 任务基板**（`adapters/vscode-tasks.ts`，参数化兼容 `history_item.json` 与 `taskHistory.json`）、**Pi 会话流基板**（`adapters/pi-sessions.ts`，复用于 Pi / omp / Raft / Cindy）以及 **OpenCode 跨代双 Schema 基板**（`adapters/opencode.ts`，合并 1.x 三表与 2.x `session_v2` 并复用于 ZCode）。

在异构协议落地上，有两个极易踩坑的系统级边界值得单独拆解：

### 修复 Node.js `zlib.zstdDecompressSync` 多帧 `.jsonl.zst` 截断

DeepSeek Harness 与新版 Codex 的 `.jsonl.zst` 会话在每次写入刷盘时，都会向文件末尾直接拼接（concatenate）一帧独立的 zstd 数据。Node.js 内置的 `zlib.zstdDecompressSync()` 面对多帧拼接缓冲区时**只解压第一帧便提前结束**，导致首轮之后的所有对话静默丢失；但若简单用 `buf.indexOf` 搜索 4 字节魔数（`0xFD2FB528`）切分，一旦压缩负载内巧合出现相同字节序列就会截断报错。

[`server/src/parser/zstd.ts`](https://github.com/ZengLiangYi/ChatCrystal/blob/842e44a/server/src/parser/zstd.ts) 严格依据 [RFC 8878 §3.1.1 帧格式规范](https://datatracker.ietf.org/doc/html/rfc8878#section-3.1.1)解析 `Frame_Header_Descriptor`、窗口描述符、字典 ID 与变长 `Frame_Content_Size`，再循环读取 3 字节小端块头（`Last_Block` + `Block_Type` + 21 位 `Block_Size`）与可选 4 字节校验和，精确步进定位每一帧边界；仅当末尾帧正处于半写入状态导致步进返回 `null` 时，才回退到最多 3 次魔数边界探测，完整抢救已落盘的前序对话。

### Windows 读取 `\\wsl.localhost`：UTF-16LE 解码与禁止唤醒休眠 WSL

Windows 虽可通过 `\\wsl.localhost\<distro>\home\<user>` 读取 WSL 内的 Claude Code 或 Codex 会话，但存在两个隐蔽副作用：一是 `wsl.exe` 标准输出在管道重定向时默认编码为 **UTF-16LE** 而非 UTF-8；二是对已停止（Stopped）的发行版执行 `fs.stat` 或挂载 `chokidar`，会触发系统在后台强行冷启动整个 Linux 虚拟机。

`parser/wsl.ts` 通过支持 UTF-16LE BOM 与零字节特征检测的解码器执行 `wsl.exe -l --running -q`，**严格只扫描当前处于 Running 状态的发行版**（目录解析结果缓存 5 分钟），并配合 `watcher/index.ts` 中的 `isWslUncPath()` 守卫，彻底禁止对 `\\wsl.localhost` 和 `\\wsl$` 建立文件监听。

## 工程复盘：三个已识别的并发吞吐与交互边界

全链路审视 v0.7 代码后，存储持久化与多源隔离已经非常扎实，但也清晰暴露了三个可在下一版本继续打磨的边界：

- 事件循环解耦已完成，但批处理尚未喂饱多核 Worker 槽位 ：`ParserPool` 默认开启最多 4 个工作线程，但 `importAll()` 主循环仍采用串行 `await importConversationItem(...)`，意味着批量同步期间池内同时只有 1 个 Worker 处于忙碌状态。下一步可将“读缓存 + Worker 解析”改为有界滑动窗口预取（主线程保持串行 SQLite 事务落盘），并对缓存了 20 秒 `sql.js` 实例的大体积外部库按 `source` 做固定 Worker 亲和路由，避免 4 个线程重复加载同一份百兆 `opencode.db`。

- `scanning` 阶段列表渐进刷新签名还可更灵敏 ：前端 `useSyncStatus` 当前仅根据 `${imported}:${replaced}:${skipped}:${errors}` 变化触发列表重拉；在 32 个源依次 `scan()` 插入 `pending` 行阶段，四个计数恒为 `0:0:0:0`，需等到首条会话解析完成才触发首次刷新。将 `progress.total` 纳入签名即可实现每扫完一个源立刻上屏。

- 不足 2 条消息的 `pending` 占位行被抢先点击时的空态过渡 ：`scan()` 不读正文，单行中断会话会短暂生成 `pending` 行；若用户在后台清理前点入详情，`materializeConversationById()` 判定有效消息不足 2 条会删除占位行并返回 `'skipped'`，使详情接口二次查询返回 `404`。为 `'skipped'` 分支补充显式前端提示并退回列表即可闭合该边界。

从早期全内存 `sql.js` 演进到 `node:sqlite` WAL、索引优先与异构解析池，最核心的工程经验只有一条：**本地优先工具的流畅度，取决于何时避免全量写盘、何时推迟正文解析，以及何时绝对不碰邻居进程的文件锁与虚拟机电源状态**。完整模块关系可进一步参考 [ChatCrystal 项目架构导览](/projects/chatcrystal/)与源码中的 [`sqlite-compat.ts`](https://github.com/ZengLiangYi/ChatCrystal/blob/842e44a/server/src/db/sqlite-compat.ts) 及 [`transcript-cache.ts`](https://github.com/ZengLiangYi/ChatCrystal/blob/842e44a/server/src/services/transcript-cache.ts)。

分享：

##  相关文章

[##  海量对话批量导入性能优化：并发控制与压测方案

剖析 Node.js 批量导入千条 AI 会话的性能瓶颈：拆分 JSONL 流式解析、SQLite 事务合并、sql.js 导出与 p-queue 429 限流压测，给出可复现的基准校验方案。          曾亮懿       2026年10月7日      阅读约 5 分钟

#ChatCrystal

#SQLite

#性能优化](/blog/bulk-import-performance-plan/)    [##  大文件批量导入的 Node.js 内存管理与分批流式处理

测量与治理 Node.js 大体积会话批量导入的内存峰值：拆解 JSONL 解析、sql.js WASM 线性内存、全库导出与异步队列开销，用可复现基准决定分批策略。          曾亮懿       2026年10月3日      阅读约 6 分钟

#ChatCrystal

#Node.js

#数据解析

#性能优化](/blog/conversation-import-memory-budget/)    [##  AI 对话存储格式对比：JSONL 事件流与 SQLite 快照

对比 Claude Code、Codex、Cursor、Trae 与 Copilot 五种本地存储格式：区分 JSONL 事件流与 SQLite 键值表结构，在内存库中验证消息索引、孤立记录与未知版本边界。          曾亮懿       2026年10月7日      阅读约 4 分钟

#ChatCrystal

#Node.js

#SQLite](/blog/ai-conversation-format-divergence/)

##  从文章到代码

到我的 GitHub 看看 ChatCrystal、KeelDesk、n8n 工作流和日常学习记录，欢迎交流实现细节。

[访问我的 GitHub](https://github.com/ZengLiangYi)

```json
{
  "@context": "https://schema.org",
  "@id": "https://zengliangyi.com/#website",
  "@type": "WebSite",
  "name": "ZengLiangYi Blog",
  "alternateName": [
    "Leon Zeng",
    "Zeng Liangyi",
    "ZengLiangYi",
    "zengliangyi.com"
  ],
  "url": "https://zengliangyi.com",
  "description": "曾亮懿的个人网站。记录 AI Native 探索、开发者工具与全栈产品实践。",
  "inLanguage": "zh",
  "author": {
    "@id": "https://zengliangyi.com/#person"
  }
}
{
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "headline": "从 sql.js 迁移到 node:sqlite：WAL 与多源后台同步",
  "description": "在 Node.js 24 与 Electron 中用内置 node:sqlite WAL 替换 sql.js 全库导出：详解零重写兼容层、Gzip 懒加载缓存与 Worker 解析池，打通 Claude Code、Cursor、Codex 等 32 源本地会话同步。",
  "url": "https://zengliangyi.com/blog/migrate-sqljs-to-node-sqlite-wal-sync/",
  "image": "https://zengliangyi.com/images/blog/migrate-sqljs-to-node-sqlite-wal-sync.svg",
  "datePublished": "2026-11-15T00:00:00.000Z",
  "dateModified": "2026-11-15T00:00:00.000Z",
  "inLanguage": "zh",
  "keywords": [
    "ChatCrystal",
    "Node.js",
    "SQLite",
    "性能优化"
  ],
  "articleSection": "ChatCrystal",
  "isPartOf": {
    "@id": "https://zengliangyi.com/#website"
  },
  "author": {
    "@id": "https://zengliangyi.com/#person",
    "@type": "Person",
    "name": "曾亮懿",
    "alternateName": [
      "Leon Zeng",
      "Zeng Liangyi",
      "ZengLiangYi",
      "夜雪闻竹"
    ],
    "jobTitle": "AI Native Developer",
    "knowsAbout": [
      "AI Native Development",
      "AI Agents",
      "Model Context Protocol",
      "TypeScript",
      "React",
      "Full-Stack Development",
      "Developer Tools"
    ],
    "url": "https://zengliangyi.com/about/",
    "email": "contact@zengliangyi.com",
    "image": "https://zengliangyi.com/branding/zeng-liangyi-avatar.png",
    "address": {
      "@type": "PostalAddress",
      "addressLocality": "深圳",
      "addressRegion": "广东",
      "addressCountry": "CN"
    },
    "sameAs": [
      "https://github.com/ZengLiangYi",
      "https://x.com/LeonZeng_",
      "https://bsky.app/profile/yizel9.bsky.social",
      "https://www.reddit.com/user/ExternalActive4238/",
      "https://juejin.cn/user/1669474445171547",
      "https://blog.csdn.net/2201_75708499",
      "https://www.linkedin.com/in/zeng-liangyi/",
      "https://gravatar.com/radangelb905e883e0"
    ]
  },
  "publisher": {
    "@type": "Organization",
    "name": "ZengLiangYi Blog",
    "url": "https://zengliangyi.com",
    "logo": {
      "@type": "ImageObject",
      "url": "https://zengliangyi.com/favicon-96x96.png"
    }
  },
  "mainEntityOfPage": {
    "@type": "WebPage",
    "@id": "https://zengliangyi.com/blog/migrate-sqljs-to-node-sqlite-wal-sync/"
  }
}
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "name": "从 sql.js 迁移到 node:sqlite：WAL 与多源后台同步",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "在 Node.js 24 与 Electron 中，为什么主数据库用 node:sqlite 而解析外部 IDE 数据库仍保留 sql.js？",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "主库需要真实文件级 WAL 持久化与低开销 checkpoint，且内置 node:sqlite 免去了 better-sqlite3 的跨平台 C++ 原生编译负担；而 Cursor、OpenCode、Goose 等外部 SQLite 数据库正被宿主编辑器并发写入，用 sql.js 在内存中只读加载文件快照可避免触碰外部活跃 WAL 引发 SQLITE_BUSY 锁冲突。"
      }
    },
    {
      "@type": "Question",
      "name": "为什么 Node.js 的 zlib.zstdDecompressSync 解压 .jsonl.zst 日志会丢失后续对话？",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "许多 AI 客户端采用追加写入模式，每次 flush 会向同一个 .jsonl.zst 文件末尾拼接一帧独立的 RFC 8878 zstd 数据。Node.js 内置的 zstdDecompressSync 遇到多帧拼接缓冲区时只解压第一帧即返回，需要按帧头与 3 字节块头步进切分后再逐帧解压。"
      }
    },
    {
      "@type": "Question",
      "name": "Windows Node.js 如何读取 \\\\wsl.localhost 下的 Linux 文件而不唤醒已关停的 WSL 发行版？",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "直接访问或监听已关停发行版的 \\\\wsl.localhost UNC 路径会触发后台冷启动整个 Linux 虚拟机。应先运行 wsl.exe -l --running -q（注意重定向输出为 UTF-16LE 编码）仅枚举运行中的发行版，并禁止 chokidar 对 WSL UNC 路径挂载监听器。"
      }
    }
  ]
}
{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "name": "面包屑导航",
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "name": "首页",
      "item": "https://zengliangyi.com/"
    },
    {
      "@type": "ListItem",
      "position": 2,
      "name": "文章",
      "item": "https://zengliangyi.com/blog/"
    },
    {
      "@type": "ListItem",
      "position": 3,
      "name": "从 sql.js 迁移到 node:sqlite：WAL 与多源后台同步",
      "item": "https://zengliangyi.com/blog/migrate-sqljs-to-node-sqlite-wal-sync/"
    }
  ]
}
```
