# electron-client **Repository Path**: NativeBase/electron-client ## Basic Information - **Project Name**: electron-client - **Description**: electron桌面客户端 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-11-17 - **Last Updated**: 2026-11-18 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Electron Client 基于 Electron、Vue 3 和 TypeScript 的桌面客户端基础项目,支持本地 Vue 业务与远程业务网页两种模式,提供窗口、托盘、菜单、开机启动、下载和更新等公共能力。 当前默认启动本地工作台,具体业务可通过 Vue 组件、远程服务地址及主进程业务钩子接入。设置、下载、更新和加载失败页面均随客户端提供,业务服务离线时仍可使用。 ## 技术栈 | 技术 | 用途 | | --- | --- | | Electron 45 | 桌面运行时、窗口与系统能力 | | Vue 3 + TypeScript | 本地管理界面与共享类型契约 | | Vite 8 | 页面、主进程和 preload 构建 | | Tailwind CSS 4 + CSS | 界面样式 | | electron-builder 26 | 多平台应用打包 | | electron-updater 6 | 更新检查、下载与安装 | ## 快速开始 开发环境要求 Node.js `>=22.12.0`,并具备运行 Electron 的桌面环境。 ```sh # 安装依赖。 npm install # 启动 Vite 和 Electron 开发环境。 npm run dev ``` Electron 运行时会按需下载,也可执行 `npm run electron:install` 提前准备。Windows 命令提示符下可使用 `npm run dev:win` 设置 UTF-8 代码页后启动。 首次运行进入本地工作台。通过左侧导航、原生菜单或托盘打开「客户端设置」,选择远程模式并填写服务地址;勾选「立即应用业务页面配置」后保存,经过确认即可切换。未勾选时,业务页面配置在下次启动或再次立即应用时生效。 ## 常用命令 | 命令 | 作用 | | --- | --- | | `npm run dev` | 启动开发环境 | | `npm run dev:win` | 在 Windows 命令提示符中设置 UTF-8 并启动 | | `npm run electron:install` | 预先下载 Electron 运行时 | | `npm run typecheck` | 检查 Vue、应用代码及构建配置的类型 | | `npm test` | 运行 Node.js 单元测试 | | `npm run build:app` | 执行完整类型检查并构建页面、主进程和 preload,不生成安装包 | | `npm run test:electron` | 构建后运行真实 Electron 集成冒烟测试 | | `npm run build:win` | 执行完整类型检查和构建,生成 Windows x64 NSIS 安装包 | | `npm run build:mac` | 执行完整类型检查和构建,生成 macOS DMG,默认使用当前机器架构 | | `npm run build` | 执行 `vue-tsc`、Vite 构建,按当前系统平台打包 | | `npm run preview` | 预览已构建的网页;不提供 Electron 原生能力 | ## 已实现能力 | 模块 | 行为与边界 | | --- | --- | | 页面与窗口 | 本地/远程模式、单实例唤回、业务子窗口、加载失败与重试 | | 菜单与托盘 | 显示主窗口、打开管理页面、明确退出;托盘实际可用时才允许关窗隐藏 | | 开机启动 | 已安装的 Windows/macOS 客户端支持;开发环境及 Linux 返回不支持 | | 下载 | 接管原生 GET、Blob、POST 附件;支持进度、速度、暂停、恢复、取消、打开、定位及历史管理 | | 更新 | 定时与手动检查、用户发起下载、明确确认后安装;普通退出不自动安装 | | 业务生命周期 | 初始化、退出检查、页面切换检查及资源释放 | 生产环境默认关闭主窗口后隐藏,开发环境默认退出,可在设置中调整。隐藏启动还要求托盘可用,避免窗口隐藏后无法找回。 下载恢复取决于 Electron 原生任务状态。GET 重试仅限原进程、原 Session 内的 30 分钟有效窗口,并要求有明确的 GET 请求证据;Blob、POST 及重启后的历史不提供重试。重启前未完成的任务会标记为中断,不代表支持跨重启断点续传。 ## 目录结构 ```text electron/ main.ts # 主进程构建入口 preload.ts # 本地管理页 preload 入口 remote-preload.ts # 远程业务页最小权限桥接 main/ index.ts # 应用组装、IPC 注册与生命周期组织 config/ # 设置验证、来源策略与持久化 window/ # 窗口身份、导航、弹窗及页面加载 ipc/ # IPC 授权、统一结果和异常收敛 remote/ # Session 权限限制 downloads/ # 下载任务、历史及完成提示 updater/ # 更新状态与原生更新适配 startup/ # 系统自启与失败回滚 menu/ # 原生菜单 tray/ # 系统托盘 lifecycle.ts # 业务生命周期钩子与原生退出适配 exit.ts # 退出与更新安装协调 foundation.ts # 向业务提供的基础服务契约 product.ts # 产品更新源与 Session 分区 preload/ # 本地固定 API 与 IPC 调用包装 utils/ # 主进程纯工具 shared/ desktop.ts # 设置、状态、下载、更新及桥接契约 domain/errorCodes.ts # 统一错误码与提示文案 src/ desktop/ # 本地管理界面与状态逻辑 assets/styles/style.css # Tailwind 与全局样式入口 App.vue # Vue 根组件与本地业务插槽 main.ts # Vue 应用入口 plugins/ # Vite 插件组装与自动导入 test/ # 单元测试与 Electron 集成测试入口 scripts/ # 集成测试调度脚本 docs/ # 架构、接入及验收文档 ``` 当前本地页面通过 Hash 选择展示内容,导航操作由主进程打开或聚焦对应窗口。`src/router/index.ts` 尚未接入 Vue Router,`src/view`、`src/hooks` 等目录保留为扩展位置。 ## 桥接与安全边界 本地管理与远程业务使用独立的持久化 Session,以及不同的 preload。窗口默认关闭 Node.js 集成,启用上下文隔离与沙箱,不向网页暴露任意 IPC 或文件系统接口。 - 远程页面的 `window.desktop` 仅提供 `getVersion()` 和 `downloads.open()`。 - 本地页面通过固定 API 获取快照、订阅变化及操作设置、窗口、下载和更新;不同管理窗口仍按角色限制操作。 - 主进程校验窗口身份、主框架与当前来源,修改 URL Hash 不会提升权限。 - 业务 URL 默认只接受 HTTPS;HTTP 需要在设置中显式允许。 - `navigationOrigins` 用于额外导航来源,`trustedOrigins` 用于额外原生授权来源,均按完整 origin 精确匹配。允许 SSO 导航不会自动授予原生能力。 桥接操作返回 `Result`,调用方先判断 `ok`,再读取 `data` 或展示 `message`。`onChanged()` 返回取消订阅函数,组件卸载时必须调用。 ## 业务接入 - **本地 Vue 业务**:在 `src/App.vue` 中向 `DesktopView` 的默认插槽传入业务组件。 - **远程业务**:在客户端设置中配置服务地址、允许导航的来源和可信来源。 - **主进程业务**:在 `electron/main.ts` 调用 `startMainProcess(import.meta.url, { business, menu })`,显式传入业务钩子和菜单。 `BusinessHooks` 提供 `initialize`、`beforeQuit`、`beforePageChange`、`dispose`。检查钩子返回 `false` 可阻止操作;初始化时可通过 `FoundationServices` 读取设置、打开管理页、获取主窗口和注册业务 IPC。 业务 IPC 必须使用 `business:` 前缀,默认仅允许本地业务主窗口调用。注册通道后,还需在 preload 和共享契约中增加参数、返回类型明确的固定方法,不能向网页暴露任意 `invoke(channel)`。 完整示例见 [基础功能使用与验收](./docs/electron-base/06-基础功能使用与验收.md#业务服务接入示例)。 ## 样式开发 Tailwind CSS 4 通过 `plugins/index.ts` 中的 Vite 插件接入,样式入口为 `src/assets/styles/style.css`,由 `src/main.ts` 全局引入。当前扫描范围为 `src/`,可直接在 Vue 模板中使用完整工具类名。 新增主题变量可使用 `@theme`,无需额外创建 `tailwind.config.js`。动态样式应保留完整类名,例如 `active ? 'text-blue-600' : 'text-gray-600'`。全局样式当前包含普通 CSS 选择器,调整层叠关系时需同时检查与工具类的覆盖效果。 ## 数据与日志 运行数据保存在 Electron 的 `app.getPath('userData')` 目录: | 路径 | 内容 | | --- | --- | | `desktop-settings.json` | 用户偏好;配置损坏时回退默认值并尽力保留损坏副本 | | `downloads/history.json` | 下载历史;下载文件本身保存在用户设置的下载目录 | | `logs/desktop.log` | 有限的运行事件摘要,超过约 2 MB 时轮换 | 下载历史中的 URL 会移除内嵌凭据、查询参数和 Hash,不保存 Cookie 或请求头。清理下载记录不会删除磁盘文件。清除远程登录会话前需要结束活动下载,并经过业务页面切换检查。 ## 构建与发布 `electron-builder.json5` 配置了 Windows x64 NSIS、macOS DMG 和 Linux AppImage,默认输出到 `release/${version}`。应用产物位于 `dist/` 和 `dist-electron/`。 按目标平台选择打包命令: ```sh # Windows:生成 x64 NSIS 安装包。 npm run build:win # macOS:在 Mac 上生成当前机器架构的 DMG 安装包。 npm run build:mac ``` macOS 如需指定架构,可执行 `npm run build:mac -- --arm64` 或 `npm run build:mac -- --x64`。`npm run build` 保留为按当前系统平台打包的通用入口。 正式发布前需替换占位的 `appId`、`productName` 和 `package.json` 版本,并完成目标平台签名配置。当前 macOS 配置为 `identity: null`。 更新源属于可信产品构建配置,不能通过网页设置。可通过构建环境变量 `DESKTOP_UPDATE_URL` 注入公开更新地址,或在 electron-builder 中配置 `publish` 生成标准 `app-update.yml`;构建环境变量指定的源优先。更新地址中不得包含发布密钥。 泛用 HTTP(S) 更新服务需要发布对应平台的更新元数据、安装包和 blockmap。打包成功不代表真实安装、系统登录自启或更新升级已验收,正式发布仍需在目标系统执行安装、自启及双版本升级测试。 ## 测试与开发约定 单元测试覆盖配置验证与损坏恢复、来源和角色策略、下载历史与文件名、自启回滚、更新重试及退出安装顺序。Electron 冒烟测试使用隔离用户目录和受控业务站点,覆盖生产资源加载、重启及开发模式,需要可运行 Electron 的环境。 新增函数、方法、接口、类型、类和重要逻辑须编写必要的中文注释,公共 API 优先使用 JSDoc/TSDoc。所有错误码统一定义在 `shared/domain/errorCodes.ts`,提示文案统一维护在 `ERROR_CODE_MESSAGES`。具体要求见 [AGENTS.md](./AGENTS.md)。 ## 项目文档 - [文档索引](./docs/README.md) - [当前功能、业务接入与验收边界](./docs/electron-base/06-基础功能使用与验收.md) - [当前运行关系图](./docs/electron-base/diagrams/runtime.svg) `docs/electron-base` 中的 01—05 文档保留历史结构、设计和规划;判断当前功能时,以源码及 06 文档为准。 ## 许可证 [MIT](./LICENSE)