Electron 打包后本地知识库总掉路径，我把 userData、sessionData 和 resources 拆成了三层
最近在整理一个 Electron 桌面端知识库工具的安装包，最麻烦的问题集中在打包后的路径漂移。开发环境里索引目录、SQLite 库、检索缓存和模板资源都在项目根目录附近，看起来一切正常。可一旦进了安装包，用户升级一次版本，知识库路径就可能失效，缓存把磁盘撑大，甚至日志和数据库文件搅在一起，后面排障很难还原现场。
原创示意图：把业务数据、会话缓存和安装包只读资源拆成三层，主进程统一管理路径解析。 来源：Codex image generation
问题背景
这个项目同时有三类本地资产。第一类是用户自己的知识库状态，比如目录映射、索引版本、任务快照和本地数据库。第二类是 Chromium 会持续写入的数据，比如 cookie、缓存和 devtools 相关文件。第三类是随安装包发出去的只读资源，比如默认提示词、数据库迁移脚本、内置模型配置和首启模板。之前我把这些内容都挂在一个“应用数据目录”概念下，结果开发态能跑，打包态很脆。
我踩到的几个坑
第一个坑是把自己的数据库和 Chromium 缓存放在同一层目录。Electron 官方文档对 userData 和 sessionData 的职责写得很清楚，缓存量大的 Session 数据如果不单独迁走，很容易把真正需要长期保留的业务数据埋进去。第二个坑是把只读模板写成相对路径，开发时能从源码目录拿到，打包后却因为资源进入 resources 目录而全部失效。第三个坑来自升级。Electron 发布说明最近专门补了一条文档建议，提醒业务文件最好放在 userData 的子目录里，避免和 Chromium 自带的 Cache、GPUCache、Local Storage 这些目录撞名。
解决思路
我后来把本地存储拆成了三层。第一层是 app.getPath('userData')/app-data，只存业务状态，里面再细分 db、indexes、tasks、logs。第二层是单独改写过的 sessionData，在 ready 前就重定向到 userData/session，让浏览器缓存和业务数据库彻底隔离。第三层是只读资源层，统一从 process.resourcesPath 向下取 prompts、migrations、bootstrap 这些目录，并在打包配置里通过 extraResources 明确复制进去。
关键步骤
1. 应用启动最早阶段先创建业务目录，并在主进程里生成统一的路径清单，渲染层不直接拼接磁盘路径。 2. 在 app 的 ready 事件之前调用 app.setPath('sessionData', ...)，把缓存目录单独迁出去。 3. 所有内置模板、迁移脚本和首启资源只通过 process.resourcesPath 解析，开发态也走同一套 helper。 4. 在 electron-builder 里把这些只读资产放进 extraResources，让安装包产物和代码里的读取路径保持一一对应。 5. 首次启动时只做资源校验与目录初始化，不在资源目录里写入任何运行时文件。
可复用经验
这次复盘之后，我对 Electron 桌面端和 Web 端协作有了一个更稳定的判断。只要页面里出现“本地业务状态”“浏览器运行缓存”“随版本分发的只读资产”这三类东西，就应该在工程上先把边界立住。目录分层一旦清楚，RAG 索引迁移、任务恢复、日志归档和自动更新都会顺很多。后面我再做桌面端 Agent 工具箱时，也准备沿用这套拆法，把用户数据、会话缓存和内置能力包继续分开维护。
主要来源
Electron process.resourcesPath