Electron + TypeScript + Prisma 8:桌面应用类型安全升级全记录
1. 升级前的"三座大山":为什么这次要彻底切换到 TypeScript 全家桶
1.1 旧项目的四个难堪时刻
上个月我终于把那个从 JS 时代残留下来的 Electron 项目翻新完了。起因其实很朴素——维护成本绷不住了。这个项目是个本地知识库工具,数据层用的是 JSON 文件加手写读写,渲染进程和主进程之间靠一串神秘的 IPC 通道名互传 any,UI 层虽然用了 Vue 3,但 TypeScript 开了个假 strict,错误全靠运行时爆出来才肯现身。后来一鼓作气,把 TypeScript 的严格模式全量打开,顺手把数据层从 JSON 换成了 SQLite + Prisma 8,顺便把 Electron 的主进程、preload、渲染进程三层全用类型串了起来。
如果你正在维护一个 Electron 老项目,或者准备从零写一个桌面工具,这篇升级实战记录应该能帮你少踩一堆坑。它适合三种人看:一是被"DLL not found""Cannot read property of undefined"折磨到麻木的 Electron 开发;二是想在桌面应用里用 Prisma 但摸不清主进程、打包、迁移这几个环节怎么配合的;三是准备迎接 TypeScript 7.0 弃用项,但不知道从哪里下手的团队。
旧项目的问题不是一个爆炸性故障,而是四个慢性病同时发作。数据层我用的是一套 JSON 文件存储库,每次写入都要把整个数组读出来、修改、再 writeFileSync 回去。数据一上到 2000 条笔记,启动加载超过 3 秒,写一条笔记要等 300ms 以上。IPC 通信就是暗号式对接,主进程的 ipcMain.on('get-data'),渲染进程 ipcRenderer.send('get-data'),通道名靠大家自觉保持一致。某次重构把一个字段 data 改成 payload,主进程忘了同步,UI 层静默拿到 undefined,用户反馈"列表偶尔空白",查了一个下午才发现是字段名不匹配。第三个问题是 TypeScript 形同虚设,tsconfig 里 strict 全是 false,代码里 any 遍地,数组取元素直接 index 访问不判空,用 TS 只是因为编辑器补全舒服。第四个问题是第三方库的类型缺口,项目里有两个只有 JS 声明甚至没有 @types 的库,以前靠 // @ts-ignore 糊过去,后面升级依赖时运行时报错根本定位不到。
单看哪一个都不致命,但合起来,每次小需求都要花大量时间在"确认哪块代码又悄悄坏了"上面。产品复杂度继续上涨,隐患会被放大得越来越明显。
1.2 技术选型定调:Prisma 8 凭什么取代旧方案
调研 ORM 方案时,我其实纠结过一阵。最后选 Prisma 8 + SQLite,核心因素是三个:
- Prisma 的 schema 文件是声明式的,模型、关系、迁移全在一条链路上。桌面应用这种以本地单机为主的场景,最怕的就是表结构和代码各说各话。打开
schema.prisma一眼看到所有模型,比翻一堆装饰器注解容易太多。 - Prisma Migrate 和 Client Generation 一体化。TypeORM 这类装饰器驱动的 ORM 在 Electron 里和构建工具配合时,装饰器元数据的处理经常要额外配置;Prisma 从 schema 到 migratio 再到类型安全的 client,整条管线是官方设计好的,省心。
- 类型推导是原生能力。Prisma 生成的 client 类型可以直接被 TypeScript 引用,查询结果、筛选条件、关联字段都有完整类型,这正好对上了这次"全面拥抱 TypeScript"的目标。
为什么不用 Knex 或 Drizzle?Knex 本质是查询构建器,没有 schema/migration 一体化能力,抵抗 schema 漂移的能力弱;Drizzle 轻量确实是亮点,但这次的项目不只需要 query builder,还需要一套从 model 到 migration 到 client 的完整管道。数据库选 SQLite 也符合场景:桌面单机工具不需要起数据库服务,文件型存储对用户来说等同于"数据就在硬盘上",备份迁移都方便,比 JSON 文件在并发写、事务、索引上强太多。
1.3 升级范围与预期目标
这次改造不是推倒重写,而是在尽量保留现有功能的条件下翻新底层。我列了一张升级清单来约束范围:
| 模块 | 旧方案 | 新方案 | 直接收益 |
|---|---|---|---|
| 数据层 | JSON 文件 + 手写读写 | SQLite + Prisma 8 | 事务能力、索引查询、写入性能 |
| 类型策略 | strict 关闭、any 泛滥 | strict 全开、noUncheckedIndexedAccess | 编译期拦截运行时错误 |
| 路径解析 | baseUrl + 相对路径 | paths 相对化 + moduleResolution bundler | 兼容 TS 7.0 |
| IPC 通信 | 字符串通道 + 无类型 | 协议清单 + 类型推导 | 编译期发现字段不匹配 |
| 打包 | electron-builder 默认配置 | Prisma 引擎资源外置 | 产物真正可分发 |
表格里每一行都对应着一套具体动作,下面几章就是我实际操作的完整记录。
2. TypeScript 7.0 前夜:baseUrl 与 node10 解析策略迁移实录
2.1 一升级就全红了
我先把 TypeScript 升到当前 6.x 这条线,准备让项目提前适应 7.0 的收紧。结果 npm run typecheck 一跑,两百多个错误,最集中的两类:
TS2307 几乎把所有路径引用都炸了。原因很清晰:旧项目的 tsconfig 里设了 baseUrl: "./src",然后所有 import 都基于这个 baseUrl 去写,比如 import { Note } from "types/note",实际文件在 src/types/note.ts。这种写法在旧版 TS 里能用,但已经属于被官方标记为废弃的用法,从 TypeScript 7.0 开始 baseUrl 会停止生效。
为什么 TS 官方这么坚决地抛弃 baseUrl?我去翻了 GitHub 上的 discussion,大概逻辑是:baseUrl 打破了模块解析的正常路径层级。一个项目里可以存在多个看起来像是包名的路径,实际却指向本地目录,误导性极强;它和 node_modules 的包名解析规则叠加之后,出现歧义的机率很高;最关键的是,它把"相对路径的根"藏在全局配置项里,重构目录结构时,IDE 的移动文件功能经常没法可靠改写引用。我后面就遇到一个例子:import { GlobalStore } from "stores/global" 在旧 baseUrl 下解析到 src/stores/global.ts,但后来 node_modules 里新增了一个同名包,TS 在很长一段时间里把这条 import 指向了依赖包,恰好两个模块长得差不多,所以没当场爆炸。baseUrl 移除后才彻底暴露。
2.2 不依赖 baseUrl 的 paths 写法
既然决定拥抱新语法,我把路径别名全部改为显式映射。最关键的转变:新写法不再借助 baseUrl,而是把映射目标写成完整的相对路径。
注意 @/* 映射到 ./src/*,映射终点必须写到 src 这一层,而不是原来那样靠 baseUrl 推导。我花了半个小时把整个项目的 import 从 types/note 这种形式改成 @/types/note 或 @shared/xxx。过程很机械,但收益很直接:路径解析不再依赖"根目录藏在哪"的约定,后面我把 src 下的子目录重新分组,IDE 和编译器都没有任何迟疑。
这里必须提醒一个很容易忽略的点:tsconfig 里的 paths 只是 TypeScript 的编译视角,运行时和打包器并不知道这个映射。项目用 Vite 构建渲染进程、esbuild/rollup 打包主进程代码,所以还得同步改 Vite 配置:
我踩过一个很具体的坑:只改 tsconfig,typecheck 全绿,但 dev 模式启动后渲染进程报 Failed to resolve import '@shared/ipc-types'。因为 Vite 有自己的 resolve 体系,不会自动读 tsconfig(即使装了 vite-tsconfig-paths 插件,也要显式引入)。两边 alias 不一致,编译期和运行期就会各说各话。
2.3 moduleResolution 的迁移选择:bundler 而不是 nodenext
第二类报错是 moduleResolution: node10 被标记为 deprecated。TS 7.0 里这个选项会被移除,官方要求改用 node16、nodenext 或 bundler 之一。
我最终选择 "moduleResolution": "bundler",配合 "module": "ESNext"。原因很务实:
bundler模式就是为 Vite/esbuild 这类打包器设计的,不强制要求源码里的 import 写全扩展名,也不需要 package.json 的exports字段无懈可击。node16/nodenext对 ESM/CJS 的判定非常严格,一个既有type: "module"又有主进程 CommonJS 产物的 Electron 项目,改起来动静会大得多。
改完后的 tsconfig 核心片段:
几个严格选项我是一次开齐的,没有用手工补丁的思路去捂问题。尤其是:
noUncheckedIndexedAccess:数组arr[i]会变成T | undefined,逼着你在访问前先判空。数据层有很多"取某条笔记"的逻辑,开完之后我补了二十多处空值处理,但补完这些之后,运行时Cannot read properties of undefined基本绝迹。exactOptionalPropertyTypes:这个选项最狠,它不允许可选属性被显式塞一个undefined。一开始会很不适应,但它能抓住"{ a?: string }类型的对象被赋值为{ a: undefined }"这种隐藏 bug。noImplicitOverride:主要是改名保护,父类方法改名时,子类的 override 不同步会直接报错。
2.4 配置联动完成后的体检清单
所有配置改完,我做了四件事来验证:"npx tsc --noEmit 全绿;npm run dev 启动后主进程日志没有模块解析错误;渲染进程控制台没有 Failed to resolve import;搜索代码里的 // @ts-ignore 和 as any,从 30 多处降到 5 处,剩余的是确需临时绕过的库边界。"
这一步最值钱的不是"报错消失",而是整个项目的编译行为正式与 TypeScript 7.0 对齐。路径解析歧义这种Bug最可怕的地方就在于它平时不炸、关键时刻给你来一下;移除了旧解析策略之后,这类静默问题会直接在编译期暴露。
3. Prisma 8 接入 Electron 主进程:数据层重写最核心的一环
3.1 从 JSON 扁平结构到 SQLite 关系表:schema 设计与生成路径
旧数据层保存的是 JSON 数组,结构长这样:
tags 是字符串数组,关系全靠命名规范约定,没有任何外键,查"所有带了某标签的笔记"只能全量遍历。换到 SQLite 后,我在 schema.prisma 里设计了三个模型:
关于生成路径,output 直接放在 src 下的 generated 目录,这样主进程代码可以 import { PrismaClient } from "@/generated/prisma",不需要额外把生成的代码塞进 node_modules。注意 runtime = "nodejs",这是 Prisma 近几代里强化过的配置,表示生成的 client 面向 Node 运行时而非浏览器/edge 环境。如果这个字段写错,Electron 主进程加载 client 时会报一个让人摸不着头脑的模块错误。
3.2 PrismaClient 的初始化时机:不能无脑在顶层 new
这是我折腾最久的一个点。Electron 主进程里,Prisma Client 不能在模块顶层直接创建,原因有两个:
-
app ready 时序问题。Electron 主进程执行入口脚本时,app 事件还没 ready。此时拿
app.getPath('userData')得到的是临时目录,或者干脆抛错。数据库路径如果依赖 userData,就必须在app.whenReady()之后创建 client。 -
单例与连接数问题。如果哪里需要 PrismaClient 就 new 一个,很容易出现多个实例同时持有 SQLite 连接。SQLite 对同一文件的并发写有限制,多个连接会在写操作时报
database is locked。
实际代码我放在了 main/services/database.ts:
这里用 $connect() 主动确认连接成功,而不是等第一次查询时才懒连接。好处是启动阶段就能发现数据库文件打不开、权限不对、引擎路径错这类问题,而不是等到用户点了某个按钮才爆出错误。我设计的启动顺序是:
这个顺序是有意的:数据库连接最先建立,失败就直接弹错误对话框,而不是先渲染出一个残缺界面,再让用户自己发现功能不可用。
3.3 数据库路径、迁移文件与打包后的策略
开发期一切正常,因为 prisma migrate dev 会根据 schema 生成迁移文件并同步到本地 SQLite。但打进 electron-builder 之后,有两个文件类问题必须处理:
- 数据库文件是用户运行数据,必须放在可写的 userData 目录。asar 包内是只读的,把数据库放进去只会在运行时静默失败。
- 迁移文件目录
prisma/migrations在新机器上首次启动时可能需要应用。
对本地单机应用,我最推荐的方案其实是"模板数据库复制":在开发环境(或 CI)里执行 prisma migrate deploy 生成最终的 SQLite 文件,把它作为模板放进 extraResources。用户机器首次启动时,主进程检查 userData 下有没有数据库文件,没有就从模板复制一份过去。这个方案不依赖目标机器上是否存在完整 Prisma CLI,逻辑最简单,也不会引入运行时动态迁移的复杂度。
如果确实需要在目标机器上执行 SQL 迁移,那就把整个 prisma/migrations 目录放进 extraResources,在主进程里逐个执行迁移 SQL。但要在 Electron 子进程里调用 Prisma 的 migrate 命令,就要额外处理 CLI 文件路径和 Node 运行环境,对单机工具来说性价比不高。我后来选择了模板数据库方案,因为知识库这类应用,表结构变更频率低,发布新版时重新生成模板完全够用。
3.4 Engine 选择:为什么我建议优先看 driver adapter
Prisma 在 Electron 打包时最著名的坑是 query engine。传统 prisma-client-js 会生成一个原生二进制文件,electron-builder 打 asar 后经常出现找不到引擎、权限不对、路径漂移等问题。Prisma 8 把 driver adapter 放在更稳定的位置之后,Electron 场景有了更干净的解法:直接把 SQLite 驱动交给 better-sqlite3,Prisma Client 走 JS 协议驱动数据库。
这个方案的收益很直接:不需要把 query engine 二进制塞进 extraResources,打包体积和部署复杂度都降一截。不过这类接口演进比较快,动手前要确认一下当时版本对 driver adapter 的官方支持状态。如果还是走传统 query engine 路线,也别慌,文末第 5 节会列出完整的引擎文件处理方式。两条路线我都实际验证过,driver adapter 更省事,传统方案更稳妥,选哪条取决于你项目的打包环境和交付形态。
4. 主进程与渲染进程的类型安全 IPC:再也不需要 any 了
4.1 先给 IPC 通道做一份协议清单
升级之前,IPC 是项目里最拖后腿的环节。这次改造,我做的第一件事是新建 src/shared/ipc.ts,把通道名集中定义并给出请求响应类型:
这里我故意不用泛型工具去做花哨的自动推导,而是先手写这份协议。原因是:自动推导的代码确实短,但阅读成本高;手写协议会逼着我把"这个通道到底返回什么"写清楚,连字段名都是明确的。协议本身就成了主进程和渲染进程共同遵守的文档。通道命名规范也顺势统一成了 资源:动作,全部写在 IPC 常量对象里,谁也不能再在代码里手写字符串。
4.2 主进程 handler 的类型推导:从 Prisma 模型到 service 返回
主进程这边,handler 直接挂在 ipcMain.handle 上。但我没有让 handler 直接暴露 prisma.note.findMany() 的结果——Prisma 返回的对象带 tags 关联和多个内部字段,直接透传给渲染进程会把内部结构暴露出去,也会让前后端类型耦合过深。中间加了一个 service 层:
service 内部用 Prisma 查询:
我特意在查询里用 select 而不是直接 findMany 拿全量字段。对 Electron 本地应用来说,主进程和渲染进程的数据交互走 IPC 序列化,字段越多开销越大。用 select 精确控制返回字段,IPC 的 payload 会小一大截。
Promise.all 让 count 和 findMany 并行执行,SQLite 场景下差异不算大,但查询复杂时这个习惯能延续下来,以后切到 Postgres 或 MySQL 也不会踩串行查询的坑。service 层返回的 tagNames 和协议里的 IpcResponseMap[IPC.notes.list] 严格对齐,如果 Prisma 模型改了,TS 会立刻提示 service 返回类型对不上。
4.3 preload 与 d.ts 装配:window.api 不再是黑盒
渲染进程不能直接访问主进程的 ipcRenderer,Electron 安全模型要求通过 preload 暴露。我把 preload 也做成带类型的桥:
然后给渲染进程提供全局类型声明:
之后在 Vue 组件里就可以安全地写 await window.api.notes.list({ page: 1, pageSize: 20 }),返回的 items 结构是确定的。我甚至把请求参数里的分页字段从 page 改成 pageNo 时,改动波及的所有调用处在编译期全部报错,不用再靠 Ctrl+F 满项目搜字符串。
从 Prisma 模型到渲染进程 UI,这段类型链是:
每一环的字段名都经过编译期校验。字段一旦改名,所有引用处会同时报错,而不是像以前那样出现"主进程返回了 tagNames,UI 层读取 tags.map,得到 undefined"。
4.4 一个真实 bug 的修复案例:类型系统如何救了我
这里分享一个被类型系统拦截下来的真实案例。旧代码里 Tag 在数据层只是 string[],我把 schema 改成多对多关系后,IpcResponseMap[IPC.notes.list] 里的 tagNames 字段保留,但底层 Prisma 查询从 note.tags 变成了 note.tags → tag → name 的嵌套。由于 service 层做了映射,渲染进程完全无感知。问题出在两个地方:
- 另一个旧接口
getNoteById之前返回的是tags: string[],service 层改成了tagNames,而对应协议还写着tags。 - 某个页面组件里用了
note.tags.length判断是否存在标签。
这两个错误在类型检查阶段全部暴露:第一个是 service 返回类型与 IpcResponseMap 不一致,第二个是 tags 属性在该类型上不存在。如果还是以前那种 any 满天飞的写法,等用户跑到那个页面才会发现数据没了;现在则在合并代码前就被 CI 拦住了。这才是全面拥抱 TypeScript 最直接的回报。
5. 打包与运行时的坑:electron-builder + Prisma 引擎文件处理
5.1 打包后"一切正常但什么都不正常"的完整排查链路
本地环境的一帆风顺不代表打包后也能顺利运行,我第一次用 electron-builder 打出 exe 后安装运行,界面起来了,但列表一查就是空,报了 PrismaClientInitializationError: Prisma Client could not locate the Query Engine。这里记录完整的排查链路,大家可以直接照着走:
- 看主进程日志有没有报错。Prisma 初始化失败一般会打印一段 error log,明确说是 engine 文件找不到。如果日志都没有,先确认 electron-log 是否正常写盘。
- 确认数据库文件路径。用
app.getPath("userData")拼路径,而不是在源码里写./data.db。打包后的进程工作目录可能是 resources 也可能是系统临时目录,依赖相对路径一定会炸。 - 确认 engine 文件是否真的在产物里。去安装目录找
resources目录,看有没有 Prisma client 的引擎文件。 - 确认 asar 是否阻碍了文件和子进程访问。Prisma 的 query engine 以子进程或动态库方式工作,从 asar 里拿不到可执行文件权限。解决办法是把它放到 extraResources,再指定引擎位置。
我在 electron-builder 里的最终配置片段:
主进程初始化数据库时额外指定引擎路径:
这一步做完,query engine 找不到的问题消失。注意 Windows 上引擎文件名带平台标识,打包时要确认 electron-builder 复制过去的文件名和实际匹配,跨平台打包尤其要小心。
5.2 better-sqlite3 和原生模块的 ABI 问题
如果走 driver adapter 路线,better-sqlite3 就是另一个需要盯住的对象。Electron 内置的 Node 版本与系统 Node 版本不一致,原生模块必须针对 Electron headers 重新编译,否则加载时报 Module version mismatch。
electron-builder 有 npmRebuild: true 的自动重建机制,但偶尔会失败,尤其是 Windows 上缺少完整构建工具链时。我建议在 package.json 里加 postinstall 脚本:
这条命令会读取当前 Electron 版本的编译目标,重新编译原生模块。特别注意,装依赖时不要用 --ignore-scripts,否则原生模块很容易变成针对纯 Node 编译的版本。
另一个坑是 asar。把 better-sqlite3 原生模块塞进 asar 后,动态链接库路径也可能出问题。我在 electron-builder 配置里加了一行 asarUnpack:
这行配置保证 better-sqlite3 的 .node 文件以解包形式存在于 resources 目录,而不被压缩进 asar。原生模块和 asar 的兼容性问题是 Electron 打包时最隐蔽的坑之一,提前用 asarUnpack 排出,能省大量排查时间。
5.3 打包配置的完整形态与干净机测试
汇总一下这次项目的 electron-builder.yml 关键部分:
打包完成后,我会手动做一次"干净机测试":把 release 安装包放到另一台没有任何 Node 环境、没有安装开发依赖的机器上安装,然后启动应用。这是因为开发机上的 node_modules、环境变量、Prisma CLI 都会掩盖真实的运行环境问题。Electron 应用最容易翻车的就是这一步,我至少见过三个项目因为依赖开发机环境而把"看起来成功"的安装包直接发给了用户。
5.4 升级后的运行指标对比与日常维护心得
最后放一组同一台机器、同样 2000 条笔记样本的对比数据:
| 指标 | 升级前(JSON + JS) | 升级后(SQLite + Prisma 8 + TS) |
|---|---|---|
| 启动到可操作 | 约 3.2s | 约 1.1s |
| 写入一条笔记 | 300ms 左右 | 小于 10ms |
| 按标签过滤列表 | 全量遍历后 filter | 数据库带索引查询,基本无感 |
| 类型检查报错 | 基本为零(几乎没有检查价值) | 严格模式全开,平均每次改动会暴露 1-2 个隐患 |
| 打包体积 | 约 85MB | 约 98MB(含 Prisma client 与引擎) |
启动变快主要不是 Prisma 的功劳,而是我把数据加载从"load 全量 JSON"改成了"列表页只取 20 条";但 SQLite 的索引查询确实让过滤、排序这些操作进入了另一个量级。
日常维护还有几条经验值得记下来。Prisma schema 一定要提交进 git,迁移文件绝不手改,每次 schema 变更都走 prisma migrate dev,即使是加一个字段,本地应用同样会面对数据迁移,跳过这层后面一定后悔。主进程日志永远带上 Prisma 的 query 事件,开发时我打开 query 日志,线上环境关掉 query、保留 warn/error;Prisma 日志有点吵,但排查"某条数据为什么没查到"时极其有用。数据库文件放进 userData 目录后,记得再做一层备份,桌面应用的数据一旦丢失,用户的第一反应永远不会是"我忘了备份",而是"这个软件太不靠谱了"。
这次改造对我个人而言,最大的收获不是某个具体版本号的切换,而是把"类型可以贯通 Electron 主进程、preload、渲染进程三层"这件事真正做透了。TypeScript 严格模式 + Prisma 单例 + 类型化 IPC 协议,这三板斧让桌面应用的数据层不再是最容易腐烂的地方。以后再开新的 Electron 项目,我会毫不犹豫地把这套架构原样搬过去。