MooTool Next Electron 1.0.1：系统菜单三语本地化与更新检查链路修复详解

• 桌面应用
• 开发工具

MooTool Next Electron 是 MooTool 工具集在 Electron/Vite/React/TypeScript 技术栈上的重写产品线（技术栈见 next/package.json）。本文以官方发布说明 next/release-notes/1.0.1.md 为骨架，深入剖析 1.0.1 版本的五大核心变更——系统应用菜单的中文/英文/日文三语本地化、菜单直达设置入口、更新检查反馈修复、工具提示残留修复，以及工作区布局优化，并结合主进程与渲染进程源码验证每条改动的真实实现路径。读完你将掌握：这套菜单与设置导航的构建方式、更新检查从触发到展示结果的完整链路、以及 macOS 未签名 DMG 的“手动安装”更新模式的工作原理。

版本概况：独立于 Java 产品线的首个修复版本

1.0.1 是 MooTool Next Electron 产品线的早期修复版本。发布说明开篇即强调两件事：

• 本版本与 MooTool Java独立安装、独立更新，不会覆盖 Java 版本；
• 更新检查只读取next-electron产品清单，Java 产品线继续使用v*tag 与原有更新清单，不受本次发布影响。

这一点在仓库根目录的 update-manifest.json 中得到印证：清单顶层products下同时注册了"java"（displayName 为 "MooTool Java"）与"next-electron"（displayName 为 "MooTool Next Electron"）两个独立产品条目，各有各的 releases 与 assets。主进程 next/electron/main/updateService.ts 中定义了currentUpdateProductId = 'next-electron'，更新服务只解析自己产品线的发布数据，这就是“互不影响”的实现基础。

系统应用菜单三语本地化：一份模板、三组文案

1.0.1 最核心的改动是“完整支持系统应用菜单的中文、英文和日文显示”。这并非简单的文本翻译，而是在 Electron 主进程中按语言动态重建整套原生菜单。

文案表：menuLabels

菜单所有文案集中维护在主进程入口 next/electron/main/index.ts 的menuLabels常量中，以AppLanguage（zh-CN/en-US/ja-JP）为键，覆盖文件、编辑、显示、窗口、工具、搜索、设置、检查更新、关于、同步与备份、快捷键、外观、布局与习惯、运行环境、工具默认值、剪贴板操作、全屏、缩放，以及托盘菜单的取色器/截图/翻译等全部条目。例如：

• 中文：about: '关于 MooTool'、backup: '同步与备份…'、shortcuts: '快捷键…'、runtime: '运行环境…'、toolDefaults: '工具默认值…'；
• 英文：about: 'About MooTool'、backup: 'Sync and Backup…'、runtime: 'Runtimes…'；
• 日文：about: 'MooTool について'、backup: '同期とバックアップ…'、runtime: '実行環境…'。

文案类型由MenuLabels联合类型（index.ts）严格约束，保证三语言模板结构一致，不会出现漏项。

动态重建：rebuildApplicationMenu

菜单构建入口是 rebuildApplicationMenu，其核心逻辑为：

1. 根据当前语言取文案表：const labels = menuLabels[language]；
2. 组装MenuItemConstructorOptions[]模板；
3. 调用Menu.setApplicationMenu(Menu.buildFromTemplate(template))（index.ts）应用到系统菜单。

关键细节在于：语言变化后菜单是“重建”而不是“翻译”。applySettings（index.ts）在设置提交后调用rebuildApplicationMenu(settings.general.language)，即语言切换会触发原生菜单整体重建。这也解释了为何每个菜单项都通过settingsLink(label, category)工厂函数（index.ts）生成——重建时可以统一注入点击行为。

菜单结构：平台差异处理

模板（index.ts）按平台区分：

• macOS（darwin）：首菜单为应用菜单（app.name），包含“关于 MooTool”“检查更新…”、分隔线、“设置…（⌘,）”“同步与备份…”“快捷键…”，以及role化的隐藏、隐藏其他、全部显示、退出等系统行为；
• Windows / Linux：首菜单为“文件”，将设置、同步与备份、快捷键、检查更新聚合其中，避免 macOS 应用菜单语义缺失导致的功能不可达。

其余顶层菜单三平台一致：编辑（撤销/重做/剪切/复制/粘贴/全选 + 搜索工具）、显示（实际大小/放大/缩小/全屏 + 外观…/布局与习惯…）、窗口（最小化/缩放/前置全部窗口）、工具（搜索工具 + 运行环境…/工具默认值…）。开发模式下还会额外注入reload与toggleDevTools条目。托盘菜单则复用 next/electron/main/trayMenu.ts 的buildTrayMenuTemplate构建，与系统菜单共享同样的多语言文案体系。

菜单直达入口：一套设置页，多个快捷路径

发布说明提到的“在系统菜单中增加关于、同步与备份、快捷键、外观、布局、运行环境、工具默认值等快捷入口”，本质上是将原生菜单项与渲染进程的设置窗口分类做了映射。

设置分类注册表

设置窗口的 12 个分类定义在 next/src/features/settings/SettingsWindow.tsx：general / appearance / layout / editor / network / data / vault / runtime / ai / tools / shortcuts / about，每个分类绑定图标与 i18n 文案。菜单中的“外观”映射到appearance、“布局”映射到layout、“运行环境”映射到runtime、“工具默认值”映射到tools、“同步与备份”映射到data、“快捷键”映射到shortcuts。

跳转链路

菜单项点击后调用openSettingsPage(category)（index.ts），通过navigateMainWindow({ type: 'open-settings', category })向主窗口发送导航消息；渲染端收到后定位到对应分类组件（SettingsCategoryContent的 switch 分发，SettingsWindow.tsx）。这样用户无需逐层点击“设置 → 分类”即可直达目标配置页。

检查更新修复：从“无反馈”到“打开关于页并展示结果”

1.0.1 明确修复了“检查更新点击后无反馈”的问题。修复后的行为是：点击菜单项 → 打开“关于”设置页 → 触发一次更新检查并广播结果到页面展示。这在源码中有完整闭环。

菜单项实现

updateItem（index.ts）的 click 处理为：

click: () => { openSettingsPage('about') void checkForUpdatesAndBroadcast() }

即先导航到about分类，再触发异步检查。

检查服务：清单解析与产物匹配

checkForUpdates（index.ts）调用updateService.check(app.getVersion())。底层 updateService.ts 的流程：

1. 拉取 update-manifest.json（Accept: application/json，10 秒超时）；
2. 校验 schemaVersion 与产品注册状态，解析next-electron产品的 releases；
3. 通过 compareVersions 比较当前版本与最新发布版本（支持预发布版本排序与v前缀归一化）；
4. 根据当前platform+architecture调用selectUpdateAsset（updateService.ts）选择最匹配的安装包，匹配优先级为：架构精确匹配 > 用户偏好包类型 > 清单priority> 平台默认包类型偏好（macOS 只接受 dmg）。

结果展示：About 页面

渲染端 AboutSettings 通过window.mootool.onUpdateCheck监听主进程广播的update:checked事件，或直接调用window.mootool.checkForUpdates()，将UpdateCheckResult渲染为结果卡片：最新版本号、目标平台/架构（如darwin/arm64）、安装包文件名、错误信息，以及通过marked+DOMPurify渲染的 Release Notes（SettingsWindow.tsx）。这正好解释了为什么本次发布说明的中英文日文全文都能在“关于”页内联展示。

更新下载与安装：自动模式与 macOS 手动模式

1.0.1 说明中特别提到“macOS 会下载并校验新版 DMG，随后提示用户打开 DMG 并将应用拖入‘应用程序’”。这是 next/electron/main/updateManager.ts 中UpdateInstallMode = 'automatic' | 'manual'（contract 定义见 next/src/shared/contracts/update.ts）两种模式差异的直接体现：

• 自动模式（automatic）：prepare()内部通过updater.setFeedURL({ provider: 'generic', url, channel })配置 electron-updater 的 generic 源（channel 由 updateMetadataChannel 将aarch64→arm64、amd64→x64），随后checkForUpdates()→downloadUpdate()→quitAndInstall(true, true)（updateManager.ts），全程静默；
• 手动模式（manual）：由于 macOS 安装包未签名，走自定义downloadFile回调下载并校验 DMG（SHA-512 校验逻辑见 updateService.ts），下载完成后通过openDownloadedFile调用系统打开 DMG，由用户手动拖拽安装，随后quitApp()（updateManager.ts）。对应的测试用例 next/electron/main/updateManager.test.ts 验证了“手动模式下不调用 quitAndInstall、改为打开下载文件”的行为。

状态机（idle → available → downloading → ready / error，见 updateManager.ts）通过onStateChange持续推送给 About 页的下载/安装按钮（SettingsWindow.tsx），用户即可看到“下载中 x%”“安装并重启”等实时状态。此外，next/electron/main/updateCleanup.ts 会定时清理userData/pending-updates下超过 7 天的旧 DMG 与超过 1 天的残留.download片段（正被下载/待安装的文件会被保护跳过），避免磁盘被未签名的更新安装包占满。

工具提示残留修复：Tooltip 的生命周期管理

1.0.1 修复了“关闭窗口或切换窗口后，焦点落在设置按钮时工具提示仍然残留”的问题。这涉及 next/src/shared/components/Tooltip.tsx 中统一 Tooltip 组件的两条隐藏路径：

• 窗口失焦即隐藏：组件挂载后注册window.addEventListener('blur', hideTooltip)（Tooltip.tsx）。无论焦点是否落在设置按钮上，只要窗口失去焦点（关闭、切换），工具提示立即清除，不会残留；
• 工具激活状态联动：useToolActivity()返回toolActive，当应用不再处于活跃状态时调用hideTooltip()并阻止下一次showTooltip()（Tooltip.tsx）；同时showTooltip前置检查if (!toolActive) return（Tooltip.tsx）。

默认展示延迟delay = 400毫秒、触发器上同时绑定onMouseEnter/onMouseLeave/onFocusCapture/onBlurCapture，并通过createPortal将提示渲染到document.body。整个 workbench 与各工具页（如 next/src/features/workbench/ToolWindow.tsx）复用了该组件，因此这一处修复会同步惠及所有 Tooltip 使用点。

布局与间距优化

1.0.1 还包含“优化工作区与设置界面的布局和间距”，属于界面打磨类改动，对应 next/src/features/settings/SettingsWindow.tsx 中设置分类页的SettingsGroup/SettingRow排版结构。这通常通过调整共享样式（next/src/shared/styles）与工作区组件的间距类（如工具窗口的 detach/dock 区域）完成，属于低风险 UI 迭代，与菜单、更新等行为修复互补，使设置页各分类的字段密度与视觉层级更规整。

发布说明的工程复用：一份笔记，多处消费

值得一提的是，本发布说明不仅是给用户的更新日志，还被更新服务原样消费。仓库根目录 update-manifest.json 中 1.0.1 条目的notes字段与 next/release-notes/1.0.1.md 内容逐字一致；当用户点击“检查更新”发现 1.0.1 及以上版本可用时，releaseNotesAfter 会聚合从当前版本之后的所有 release notes，交给 About 页渲染。因此阅读这篇发布说明，就等于提前看到了更新结果卡片中将展示的 Release Notes。

小结与延伸阅读

MooTool Next Electron 1.0.1 的实质是一次“体验链路”修复：系统菜单三语本地化让原生菜单与界面语言统一；菜单直达入口缩短了配置路径；检查更新从“静默失败”变为“可感知、可追踪”的完整闭环；工具提示的生命周期问题得到根除。这些改动的核心代码都集中在主进程 next/electron/main/index.ts（菜单构建与更新调度）、next/electron/main/updateService.ts 与 next/electron/main/updateManager.ts（更新链路），以及渲染进程 next/src/features/settings/SettingsWindow.tsx（关于页与设置分类）和 next/src/shared/components/Tooltip.tsx。

• 想深入验证更新流程，可阅读 next/electron/main/updateManager.test.ts（自动/手动模式）与 next/electron/main/updateCleanup.test.ts（残留清理）；
• 想了解菜单文案全量内容，可直接查看 index.ts 的menuLabels；
• 想对照发布清单结构，可查看 update-manifest.json 中next-electron产品的 releases 与 assets 字段（platform、architecture、packageType、priority、sha512、size）。

• 桌面应用
• 开发工具