eSearch 项目架构全解析：Electron 多窗口渲染进程、数据存储与国际化技术选型指南

eSearch 项目架构全解析：Electron 多窗口渲染进程、数据存储与国际化技术选型指南

【免费下载链接】eSearch截屏 离线OCR 搜索翻译 以图搜图 贴图 录屏 万向滚动截屏 屏幕翻译 Screenshot Offline OCR Search Translate Search for picture Paste the picture on the screen Screen recorder Omnidirectional scrolling screenshot Screen translator 支持Windows Linux macOS项目地址: https://gitcode.com/GitHub_Trending/es/eSearch

本篇文章基于 eSearch 官方开发文档《整体说明》整理并扩展而来，深入剖析这款跨平台"识屏·搜索"工具的整体技术选型、目录结构与核心模块分工。你将了解到它为何选择 Electron 与 Biome、如何以自研 dkh-ui 轻量框架组织多页面渲染进程、如何通过类型化 IPC 与自研 Store 实现主进程和渲染进程的高效协作，以及基于 JSON 文件的多语言国际化工作流，从而具备直接阅读、调试乃至二次开发 eSearch 源码的能力。

项目定位与整体说明

eSearch 是一个同时支持 Windows、Linux、macOS 的桌面应用，功能涵盖截屏、离线 OCR、搜索翻译、以图搜图、贴图、录屏、万向滚动截屏与屏幕翻译。项目的描述文件 package.json 中，其产品名为 eSearch、版本号为 15.5.1，简介为"识屏 · 搜索"，遵循 GPL-3.0 协议，包管理器为 pnpm（packageManager: pnpm@10.17.0）。

在技术选型上，作者在 docs/develop/overview.md 中直白地说明：

• 开发框架：使用 Electron 开发。作者自述"JS 适合快速开发"；同时承认 Electron 跨平台方案在体积和内存上偏大，因此"尽量让功能对得上他的体积"。文中也提到 tauri 同样是不错的方案，但受限于作者的技术栈并未采用，并寄希望于未来 Windows 和 macOS 下也能出现类似 ArchLinux 中 Electron 共享运行时的方案。
• 工具链：使用 Biome 作为格式化和检查工具，使用 vite（经由 electron-vite）作为打包工具。
• 前端语言：TypeScript，很少使用类型体操，仅作为简单的类型标注。主进程开启了strict模式，渲染进程未开启（历史遗留问题较多）。

以下各节将沿着该文档的脉络，结合仓库源码逐一展开。

技术选型详解：框架、工具链与关键依赖库

自研 UI 框架 dkh-ui：向 jQuery 的"拙劣模仿"

渲染层使用的不是 Vue 或 React，而是作者自研的 dkh-ui（在 package.json 的 dependencies 中以dkh-ui: ^0.14.2引入）。作者自述 dkh-ui"只是对 JQuery 的拙劣模仿"，并坦言自己学不会 Vue/React 的 hook、ref 等概念，因此在代码中可以看到大量直接使用document和原生 HTML 操作的地方，目前也在逐步迁移到 dkh-ui。

从源码结构看，这决定了渲染进程代码风格偏向命令式 DOM 操作而非数据驱动，例如 src/renderer/root/root.ts 承担初始化样式、统一各页面风格的角色。理解这一点有助于阅读渲染层代码时对齐作者的编码心智。

核心依赖库

文档明确列出以下三个关键库，其他依赖以 package.json 为准：

此外 dependencies 中还包含onnxruntime-node（OCR/分割模型推理运行时）、esearch-seg（人像抠图）、uiohook-napi（全局键盘/鼠标钩子）、xtranslator（翻译 API 封装）、fuse.js（模糊搜索）、mediabunny（录屏处理）、picture_match（以图搜图）、qr-scanner-wechat（二维码识别）等，可对照 package.json 逐项查看。

构建与打包脚本

package.json 的 scripts 中定义了完整的开发与构建命令：

• pnpm run dev：electron-vite 开发模式（文档说明由于 vite 调试.node原生库尚未配置好，推荐使用start）。
• pnpm run start：electron-vite preview 预览运行，是开发时的常用入口。
• pnpm run build：electron-vite 构建。
• pnpm run pack：build后执行 electron-builder--dir输出未打包目录。
• pnpm run dist：build后执行 electron-builder 生成各平台安装包。
• pnpm run ana：以 analyze 模式预览，配合 vite-bundle-analyzer 分析包体积。
• pnpm run typecheck：tsc -b --noEmit --force全量类型检查。
• pnpm run format/pnpm run lint/pnpm run fix：Biome 格式化、检查与自动修复。
• pnpm run uitest：使用独立的 electron.vite.config_test.ts 跑 UI 测试。

关于 Biome，仓库根目录有 biome.json 配置文件，格式化与 lint 均以它为准。

目录结构与文件职责说明

文档对仓库结构给出了明确划分，结合源码验证如下：

根目录

• electron-builder.config.js：electron-builder 打包配置，见下节。
• assets：程序图标（svg 源文件、多尺寸 png、icon.icns、icon.ico 等），assets/logo下还有生成图标的脚本与模板。
• src：项目源码主体。
• lib：主进程侧的自有库（存储、国际化、IPC、工具函数等）。
• docs：开发文档与使用文档。

主进程

• src/main/main.ts：主进程入口，负责 CLI 参数处理、窗口管理、全局快捷键、托盘、IPC 中转与打包资源下载等。该文件约 3000 行，是整个应用的"中枢"。

渲染进程（多页面结构）

文档列出了各渲染模块与对应 HTML 入口，electron.vite.config.ts 的renderer.build.rollupOptions.input恰好以多页方式注册了全部 12 个 HTML 入口，两者可一一对应：

从 electron.vite 的配置可以看到，渲染层构建时对 svg 启用了 ViteImageOptimizer 优化、assetsInlineLimit: 0使资源不内联，并开启 sourcemap 便于调试，主进程构建不压缩（minify: false），这些细节对二次开发排查问题很有帮助。

类型共享与 IPC

• src/ShareTypes.d.ts：配置类型定义（setting接口，约 561 行，覆盖快捷键、全局外观、OCR、AI、工具栏、鼠标跟随栏、框选、图像编辑等全部配置项），同时定义主进程与渲染进程 IPC 的消息类型。文档特别指出，在这种多页面的项目中，共享类型定义非常方便。
• lib/ipc.ts：自研的类型化 IPC 封装。核心是一个Message接口（包含 clip_show、clip_ocr、clip_search、recordInit、translatorInit 等数十个消息），配合mainSend、renderOn、renderSend、renderSendSync、mainOn、mainOnReflect六个导出函数，实现主进程到渲染进程推送（mainSend）、渲染到主进程请求（renderSend/renderSendSync）、以及渲染进程之间的"主进程中转"通信（mainOnReflect）。mainOnReflect专门服务无返回值的消息，将数据广播给多个 WebContents，这正是截屏、贴图、录屏等页面之间协作的基础设施。

自有库

• lib/store：自研设置存储库。文档说明其参考了 electron-store，但直接使用 TypeScript 做类型定义、不依赖 ajv。见下节详解。
• lib/translate：翻译库，用于多语言国际化。见"国际化"节。

模型资源的下载策略

文档特别强调：OCR 模型和人像抠图模型在打包或编译时下载，不放进 git 仓库，具体逻辑见 electron-builder.config.js 的beforePack钩子。该钩子会：

• 检查./assets/onnx/ppocr/ppocr6_small_rec.onnx，不存在则从 eSearch-OCR 的 release 下载并解压 ppocr_v6_small.zip；
• 下载doc_cls.onnx（方向分类模型）到./assets/onnx/ppocr/；
• 下载seg.onnx（人像分割模型）到./assets/onnx/seg/；
• Windows 下额外下载copy.exe到./lib/（用于特殊复制场景）；
• 按平台下载 ffmpeg 到./lib/ffmpeg/（win32 会进一步解压出 ffmpeg.exe）。

这套机制保证了 OCR 模型等大体积文件不进入 git，而是构建时按需拉取。此外 electron-builder 配置中还包含：electronDownload.mirror指向 npmmirror 镜像加速 Electron 二进制下载；asar: false（不打包成 asar，便于检查产物）；为 png/jpg/svg 注册文件关联（fileAssociations，role 为 Editor，意味着可用 eSearch 打开图片文件进行编辑）；afterPack钩子会根据 lib/translate 中支持的语言裁剪 Electron 自带的 locales 原生语言包以减小体积；deb/rpm 包分别声明依赖 ffmpeg 与 ffmpeg-free。

主进程与 CLI：窗口管理与启动参数

src/main/main.ts 是主进程唯一入口，承担以下职责：

• CLI 参数处理：通过minimist解析命令行参数。其中-d或环境变量ESEARCH_DEV或设置项dev为真时进入开发者模式；--userData可指定自定义用户数据目录，并且支持便携模式（程序目录下存在portable目录时自动把用户数据放到该目录）。从源码看还支持读取程序根目录下的preload_config文件预置用户路径，这种"三选一"的优先级（命令行 > preload_config > portable 目录）值得二次开发时留意。
• 窗口管理：创建主窗口、截屏窗口、贴图窗口、翻译窗口、录屏窗口等多个窗口，配合mainSend向对应页面广播事件。
• 快捷键与托盘：注册全局快捷键（globalShortcut）与托盘图标（Tray），托盘样式在设置类型中可配置为"无/彩色/黑/白/跟随系统/跟随系统反"。
• IPC 注册：通过ipcMain.on("store", ...)提供设置的读写通道，见下节。
• 模型资源下载：打包时的 beforePack 逻辑如上节所述。

开发模式判断的完整逻辑为：process.argv.includes("-d") || import.meta.env.DEV || process.env.ESEARCH_DEV || store.get("dev")，任一项为真即开启。

自研设置存储库 lib/store：类型化、无 ajv 依赖

文档指出 lib/store 参考了 electron-store，但直接使用 TS 类型定义，不依赖 ajv。从源码看其实现分为三层：

1. lib/store/store.ts：核心Store类，将配置以 JSON 文件落盘（configPath默认是用户数据目录下的 config.json，见 src/main/main.ts 第 88-90 行的实例化：new Store({ configPath: join(app.getPath("userData"), "config.json") })）。提供get/set/getAll/setAll/clear/path等方法；get在取不到值时回退到defaultData（通过setDefaultData注入，类型为 src/ShareTypes.d.ts 的setting接口）；getAll使用deepMerge将当前数据与默认值深合并，保证旧配置升级到新版本时自动补全缺失字段。
2. lib/store/parse.ts：xget/xset按a.b.c形式的点路径读写嵌套对象；xset在中间路径不存在时，会根据下一段是否为数字自动创建数组或对象。
3. lib/store/renderStore.ts：渲染进程侧的同名封装，通过ipcRenderer.sendSync走ipcMain.on("store", ...)通道，提供get/set/getAll/setAll。其点睛之处在于用类型映射（Paths<setting>、GetValue<setting, P>）把设置路径字符串约束到setting接口的合法键路径，例如store.get("快捷键.截屏搜索.key")这类写法会得到编译期类型校验，这是"直接使用 ts 进行类型定义、不依赖 ajv"的体现——用编译期类型取代运行时 schema 校验。

国际化：lib/translate 与 JSON 语言包

多语言国际化由 lib/translate 承担，文档提到"翻译库，用于多语言国际化"。仓库内已有 ar、en、eo、es、fr、ru、zh-HANT 等语言的 JSON 文件，简体中文（zh-HANS）为源语言默认值。

• 运行时翻译：见 lib/translate/translate.ts。lan()切换语言（不匹配时通过 xtranslator 的matchFitLan回退到 zh-HANS）；t()按文本查 source.json 的 id 再取对应语言词条；如果文字未在 source.json 中定义，控制台会以红色样式输出提示，未翻译则以蓝色样式输出——这正是 lib/translate/readme.md 中"开发者"一节所述的行为。
• 翻译工作流：见 lib/translate/readme.md 与 lib/translate/tool.js。导出 CSV 后用node lib/translate/tool.js -l en（追加-a输出全部文字，便于修改旧翻译），编辑第三列译文后用node lib/translate/tool.js -i en.csv导入回 JSON。tool.js 还通过 srcCommit 与各语言 finishId 记录翻译进度，借助 git diff 定位需要翻译的新增文字。
• 打包裁剪：electron-builder 的afterPack会读取 lib/translate 目录中的语言文件，动态裁剪 Electron 自带 locales 中不被支持的原生语言包，进一步减小体积。

图标资源：svg +<img>方案

文档最后提到"图标：使用 svg 图标，通过<img>显示"。从 src/renderer/assets/icons 可以看到 add、ocr、record、translate、setting、clip 等数十个功能图标均为 svg；electron.vite.config.ts 中对 svg 启用了 ViteImageOptimizer 优化，构建时按需压缩。图标类型定义在 src/iconTypes.d.ts（由 script/gen_icon_types.ts 生成），保证在代码中引用图标名时有类型提示。

从整体说明到动手开发

整体说明是 eSearch 开发文档的入口，后续文档还包含《开始》（环境准备与构建命令）、《主进程》《截屏》《OCR》《高级图片编辑》《超级录屏》等专题，见 docs/develop/readme.md。

开发者快速上手路径可参考 docs/develop/start.md：准备 vscode、npm、node.js、git，推荐使用 pnpm 并将 registry 与 electron_mirror 指向 npmmirror.com 镜像加速；克隆仓库后pnpm install（若不需要 CUDA 或网络受限，可设环境变量ONNXRUNTIME_NODE_INSTALL_CUDA="skip"）；日常开发用pnpm run start运行（dev 模式因.node原生库调试尚未配置好而暂不可用）；pnpm run pack输出未打包目录，pnpm run dist生成安装包。

在动手改代码前，建议先建立三个心智模型：渲染进程是多个独立 HTML 页面的集合（入口清单见 electron.vite.config.ts）；页面间协作依赖 lib/ipc.ts 的类型化消息通道；所有可配置项的类型都收敛在 src/ShareTypes.d.ts 的setting接口中。掌握这三点，就能沿着本文梳理的模块地图快速定位并理解 eSearch 的任意一处实现。

【免费下载链接】eSearch截屏 离线OCR 搜索翻译 以图搜图 贴图 录屏 万向滚动截屏 屏幕翻译 Screenshot Offline OCR Search Translate Search for picture Paste the picture on the screen Screen recorder Omnidirectional scrolling screenshot Screen translator 支持Windows Linux macOS项目地址: https://gitcode.com/GitHub_Trending/es/eSearch