Files
ClassHelper/packages/desktop-client/src/main/index.ts
T
LoveChengke 0b57e926bd fix(release): 发布1.4.5并加固登录与灵动岛体验
登录连续五次失败封禁五分钟,修复两端错误提示;教师导入逐人生成随机密码并提供一次性清单。统一自定义岛外观与控件,修复圆角配置和全天课表对齐,临近下课显示课程旁秒数徽标;客户端更新改为云端统一下发。同步发布版本、帮助文档及隔离回归。
2026-11-08 09:55:33 +08:00

348 lines
13 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
import path from 'node:path';
import { pathToFileURL } from 'node:url';
import { BrowserWindow, app, shell } from 'electron';
import { setQuitHandler, watchMainWindow as watchAutoUpdateWindow } from './auto-update.js';
import { startClientAgent, stopClientAgent } from './client-agent.js';
import { flushConfigSync, getConfig } from './config.js';
import { installCrashGuard, watchMainWindow as watchCrashGuardWindow } from './crash-guard.js';
import { registerIpcHandlers } from './ipc.js';
import { island, registerIslandIpc } from './island.js';
import { logger } from './logger.js';
import { runSmokeTest } from './smoke.js';
import { createTray, destroyTray, isTrayReady } from './tray.js';
// 主进程由 esbuild 打包为 CommonJS,因此这里可以直接使用 __dirname
// (dist/main/index.js -> dist/preload/index.js 与 dist/renderer/index.html)
const currentDir = __dirname;
const devServerUrl = process.env.VITE_DEV_SERVER_URL;
const isSmokeTest = process.env.ELECTRON_SMOKE_TEST === '1';
const isQuickSmoke = isSmokeTest && process.env.ELECTRON_SMOKE_MODE !== 'visual';
/**
* 这次启动是否需要"直接进托盘、不弹窗"——开机自启专用(见 `applyAutoLaunch()`)。
* 判定依据是我们自己在登录项里注册的命令行参数 `--hidden`(Electron 44 的
* `setLoginItemSettings` 在 Windows 上**没有** `openAsHidden` 这个开关,只能自己带参数)。
*/
const startHidden = !isSmokeTest && process.argv.includes('--hidden');
// 自动化验证使用独立的 userData:否则用户正在运行的客户端会占着单实例锁,
// 冒烟进程会"静默退出(退出码 0、无输出)",看起来像构建坏了。
const smokeProfile = process.env.ELECTRON_SMOKE_PROFILE;
if (smokeProfile) app.setPath('userData', smokeProfile);
let mainWindow: BrowserWindow | null = null;
/** 是否正在退出:用于区分「关闭窗口 = 隐藏到托盘」与「真正退出」 */
let isQuitting = false;
/** 生产环境下主窗口加载的本页地址(用于导航白名单的精确比对) */
const prodRendererUrl = pathToFileURL(path.join(currentDir, '../renderer/index.html')).href;
/**
* 是否允许窗口导航到这个地址。
*
* 为什么不能用 `url.startsWith(...)`:
* - 开发态 `url.startsWith(devServerUrl)` 没有主机边界,`http://localhost:5174.evil.com` 也会被放行;
* - 生产态 `url.startsWith('file://')` 等于放行**任意本地页面**。
* 而 preload 是挂在窗口上的(不是挂在 URL 上):一旦窗口被导航到别处,那个页面照样持有
* `window.desktop`(含 `getConfig` 返回的明文 token)。因此这里按"精确同源 / 精确同一文件"比对。
*/
function isAllowedNavigation(url: string): boolean {
try {
const target = new URL(url);
if (devServerUrl) return target.origin === new URL(devServerUrl).origin;
target.hash = '';
target.search = '';
return target.href === prodRendererUrl;
} catch {
return false;
}
}
function createWindow(options: { hidden?: boolean } = {}): BrowserWindow {
// 启动底色跟主题走:深色主题下若仍用浅色底,窗口先白后黑会"闪一下"
const theme = getConfig().theme;
const win = new BrowserWindow({
// 初始尺寸与 ClassIsland 主窗口对齐(实测其可视区 1242x582),保持同一观感
width: 1242,
height: 582,
minWidth: 1000,
minHeight: 540,
center: true,
title: 'ClassHelper',
// 冒烟验证时不弹窗,避免打扰使用者;开机自启(--hidden)时直接进托盘
show: !isSmokeTest && options.hidden !== true,
focusable: !isQuickSmoke,
autoHideMenuBar: true,
backgroundColor: theme === 'dark' ? '#161719' : '#f3f3f3',
webPreferences: {
preload: path.join(currentDir, '../preload/index.js'),
contextIsolation: true,
nodeIntegration: false,
sandbox: true,
webSecurity: true,
backgroundThrottling: false,
offscreen: isQuickSmoke,
},
});
// 外部链接交给系统浏览器,禁止在应用内新开窗口
win.webContents.setWindowOpenHandler(({ url }) => {
if (/^https?:\/\//i.test(url)) void shell.openExternal(url);
return { action: 'deny' };
});
win.webContents.on('will-navigate', (event, url) => {
if (isAllowedNavigation(url)) return;
event.preventDefault();
if (/^https?:\/\//i.test(url)) void shell.openExternal(url);
logger.warn(`主窗口拒绝了页面导航:${url}`);
});
win.on('closed', () => {
if (mainWindow === win) mainWindow = null;
});
win.on('close', (event) => {
if (isQuitting) return;
event.preventDefault();
win.hide();
logger.info('主窗口已隐藏到系统托盘(后台继续运行)');
});
// 崩溃自愈与「空闲安装更新」都要盯着主窗口:窗口重建后换的是新实例,因此每次建窗都重挂一次
watchCrashGuardWindow(win);
watchAutoUpdateWindow(win);
return win;
}
/**
* 取当前主窗口,必要时重建。
*
* 与 `createWindow()` 的区别:这里会把"窗口已经被崩溃自愈销毁 / 还没建"的情况一并处理掉
* (托盘、二次启动、`activate` 都通过它拿窗口),因此调用方拿到的要么是活着的窗口、要么是 null。
*/
function ensureMainWindow(options: { hidden?: boolean } = {}): BrowserWindow | null {
if (mainWindow && !mainWindow.isDestroyed()) return mainWindow;
try {
mainWindow = createWindow(options);
void loadRenderer(mainWindow).catch((error) => logger.error('重建主窗口加载失败', error));
} catch (error) {
logger.error(`创建主窗口失败:${error instanceof Error ? error.message : String(error)}`);
mainWindow = null;
}
return mainWindow;
}
async function loadRenderer(win: BrowserWindow): Promise<void> {
if (devServerUrl) {
await win.loadURL(devServerUrl);
win.webContents.openDevTools({ mode: 'detach' });
return;
}
// 生产:加载打包后的本地 HTML(vite base 为 './',使用 file:// 相对路径)
await win.loadFile(path.join(currentDir, '../renderer/index.html'));
}
/**
* 按配置里的 `autoLaunch` 应用「开机自启」。
*
* 两个实测过的坑:
* 1. Electron 44 的 `setLoginItemSettings` 在 **Windows 上没有 `openAsHidden`**
* (那是旧的 macOS 选项),所以"登录后不弹主窗口"只能自己带参数 —— 启动时注册 `--hidden`,
* `createWindow()` 看到它就把窗口建成隐藏态(见 `startHidden`);
* 2. **冒烟验证绝不写登录项**:那会改开发机真实的注册表启动项,属于"验证污染环境"。
*/
function applyAutoLaunch(): void {
if (isSmokeTest) return;
const enabled = getConfig().autoLaunch === true;
try {
app.setLoginItemSettings({
openAtLogin: enabled,
path: process.execPath,
args: enabled ? ['--hidden'] : [],
});
logger.info(enabled ? '已开启开机自启(登录 Windows 后静默启动,不弹主窗口)' : '开机自启未开启');
} catch (error) {
logger.warn(
`设置开机自启失败(不影响主功能,可在设置页重试):${
error instanceof Error ? error.message : String(error)
}`,
);
}
}
// 单实例:重复启动时聚焦已有窗口
const gotLock = app.requestSingleInstanceLock();
if (!gotLock) {
app.quit();
} else {
app.on('second-instance', () => {
showMainWindow();
});
app
.whenReady()
.then(async () => {
// 日志级别跟开发者模式走:debug 只在开启时才输出(设置页「开发者模式」)
logger.setVerbose(getConfig().developerMode === true);
registerIpcHandlers();
registerIslandIpc();
// 开机自启:登录项要与配置保持一致(用户在设置页改过之后由 IPC 立即同步)
applyAutoLaunch();
mainWindow = createWindow({ hidden: startHidden });
// 崩溃自愈:主窗口渲染进程崩溃 / 界面无响应时静默重建;主进程崩溃且本机空闲时自动重启
installCrashGuard({
recoverMainWindow: async () => {
const alive = mainWindow && !mainWindow.isDestroyed() ? mainWindow : null;
if (alive) {
alive.hide();
alive.destroy();
}
mainWindow = createWindow({ hidden: true });
await loadRenderer(mainWindow);
},
isIdle: () =>
island.getState().inClass === false &&
mainWindow?.isVisible() !== true &&
!BrowserWindow.getAllWindows().some((win) => !win.isDestroyed() && win.isVisible()),
quitApp: () => quitApp(),
});
await loadRenderer(mainWindow).catch((error) => logger.error('主窗口启动加载失败', error));
// 空闲安装更新:先把手动退出的回调交给 auto-update(它不能再 import 本文件,否则循环导入)
setQuitHandler(() => quitApp());
// 灵动岛:独立的置顶透明小窗口(桌面中上方)
try {
if (!isQuickSmoke)
await island.init(devServerUrl ? `${devServerUrl.replace(/\/+$/, '')}/island.html` : null);
// 点击灵动岛里的"打开应用"时把主窗口拉到前台
island.setOpenAppHandler(() => {
if (!mainWindow || mainWindow.isDestroyed()) return;
if (mainWindow.isMinimized()) mainWindow.restore();
mainWindow.show();
mainWindow.focus();
});
island.setEditLayoutHandler(() => {
if (!mainWindow || mainWindow.isDestroyed()) return;
if (mainWindow.isMinimized()) mainWindow.restore();
mainWindow.show();
mainWindow.focus();
mainWindow.webContents.send('island:open-editor');
});
// 灵动岛点"标为已读":转交主窗口渲染进程调用接口并刷新通知中心
island.setMarkReadHandler((id) => {
if (!mainWindow || mainWindow.isDestroyed()) return;
mainWindow.webContents.send('island:mark-read', id);
});
// 多条通知时的"标为已读"是**整批**操作:一次把列表里的通知都标上
island.setMarkAllReadHandler((ids) => {
if (!mainWindow || mainWindow.isDestroyed()) return;
mainWindow.webContents.send('island:mark-all-read', ids);
});
} catch (error) {
logger.error('灵动岛初始化失败(不影响主功能)', error);
}
try {
if (!isQuickSmoke)
createTray({
onShow: () => showMainWindow(),
onHide: () => mainWindow?.hide(),
onQuit: () => quitApp(),
});
} catch (error) {
logger.warn(`系统托盘初始化失败(不影响主功能):${error instanceof Error ? error.message : error}`);
}
// 服务端统一下发:定时上报本机状态并领取「待执行命令 / 统一更新」(冒烟默认不上报)
startClientAgent();
if (isSmokeTest) {
try {
await runSmokeTest(mainWindow);
} catch (error) {
console.error('[SMOKE] 冒烟验证异常', error);
app.exit(1);
}
}
})
.catch((error) => {
logger.error('应用初始化失败', error);
if (isSmokeTest) app.exit(1);
});
/** 显示主窗口(托盘左键 / 托盘菜单 / 二次启动 / 灵动岛"打开应用") */
function showMainWindow(): void {
const win = ensureMainWindow();
if (!win) return;
if (win.isMinimized()) win.restore();
win.show();
win.focus();
}
/**
* 退出前的统一资源清理(需求 5:托盘 / 定时器 / 网络连接 / 窗口都不留残留)。
* 幂等:托盘退出、before-quit、will-quit 都可能触发。
*/
function shutdownResources(): string {
const done: string[] = [];
// 上报代理先停:否则退出过程中它还会再排一次心跳(幂等,重复调用无副作用)
stopClientAgent();
// 配置是**异步合并写**的(见 main/config.ts):退出前必须同步落地一次,
// 否则"刚改完设置就退出"这一类操作会丢掉最后一次改动。
// 放在最前面:后面会销毁窗口与灵动岛,先落盘不依赖任何窗口是否还在。
flushConfigSync();
done.push('配置已落盘');
if (isTrayReady()) {
destroyTray();
done.push('托盘已销毁');
}
if (island.isReady()) {
island.destroy();
done.push('灵动岛已销毁');
}
for (const win of BrowserWindow.getAllWindows()) {
if (!win.isDestroyed()) {
// 渲染进程随之结束:其中的 Socket.IO 连接、定时器、IndexedDB 句柄一并释放
win.destroy();
done.push('窗口已销毁');
}
}
return done.length > 0 ? done.join('、') : '无需要清理的资源';
}
/** 真正退出:先清理资源,再 app.quit,并用 app.exit 兜底(确保不留进程) */
function quitApp(): void {
if (isQuitting) return;
isQuitting = true;
logger.info(`正在退出:${shutdownResources()}`);
app.quit();
setTimeout(() => app.exit(0), 1500);
}
app.on('window-all-closed', () => {
// 有托盘常驻:窗口全关也不退出,继续后台接收通知
logger.info('所有窗口已关闭,程序继续在系统托盘后台运行');
});
app.on('before-quit', () => {
isQuitting = true;
shutdownResources();
});
app.on('will-quit', () => {
const summary = shutdownResources();
logger.info(`应用退出清理:${summary}`);
});
app.on('activate', () => {
if (BrowserWindow.getAllWindows().length === 0) {
ensureMainWindow();
}
});
}