feat(desktop-client): 阶段4-6 Electron EXE 客户端（登录/课表/作业/通知/成绩/设置 + Socket.IO 实时 + IndexedDB 离线缓存与自动同步 + electron-builder 打包）

2026-09-11 22:46:31 +08:00
1 parent 4566d7cd5e
commit 6e4c7c1050
@@ -0,0 +1,37 @@
+/**
+ * 主进程 / preload 构建：esbuild 打包为 CommonJS。
+ * - external: electron（由 Electron 运行时提供）
+ * - @classhelper/shared 会被内联打包（ESM 源码 -> CJS 产物）
+ */
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { build } from 'esbuild';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+const shared = {
+  bundle: true,
+  platform: 'node',
+  target: 'node20',
+  format: 'cjs',
+  sourcemap: false,
+  external: ['electron'],
+  logLevel: 'warning',
+  define: {
+    'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV ?? 'production'),
+  },
+};
+
+await build({
+  ...shared,
+  entryPoints: [path.join(root, 'src/main/index.ts')],
+  outfile: path.join(root, 'dist/main/index.js'),
+});
+
+await build({
+  ...shared,
+  entryPoints: [path.join(root, 'src/preload/index.ts')],
+  outfile: path.join(root, 'dist/preload/index.js'),
+});
+
+console.log('[build:main] dist/main/index.js 与 dist/preload/index.js 构建完成');
@@ -0,0 +1,67 @@
+/**
+ * 开发模式：先构建主进程/preload，再启动 Vite 渲染进程开发服务器，
+ * 等端口就绪后用 Electron 打开开发地址（支持热更新）。
+ *
+ * 说明：子进程统一使用 stdio: 'inherit'，在受限沙箱中也能正常启动。
+ */
+import { spawn } from 'node:child_process';
+import net from 'node:net';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import electronPath from 'electron';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const HOST = '127.0.0.1';
+const PORT = 5174;
+const DEV_URL = `http://${HOST}:${PORT}`;
+
+const viteBin = path.join(root, 'node_modules', 'vite', 'bin', 'vite.js');
+
+const vite = spawn(process.execPath, [viteBin, '--host', HOST, '--port', String(PORT), '--strictPort'], {
+  cwd: root,
+  stdio: 'inherit',
+  env: process.env,
+});
+
+let electron = null;
+
+function cleanup(code = 0) {
+  if (electron && !electron.killed) electron.kill();
+  if (!vite.killed) vite.kill();
+  process.exit(code);
+}
+
+function waitForPort(attempt = 0) {
+  const socket = net.connect({ host: HOST, port: PORT });
+  socket.once('connect', () => {
+    socket.destroy();
+    startElectron();
+  });
+  socket.once('error', () => {
+    socket.destroy();
+    if (attempt > 120) {
+      console.error('[dev] 等待 Vite 开发服务器超时');
+      cleanup(1);
+      return;
+    }
+    setTimeout(() => waitForPort(attempt + 1), 250);
+  });
+}
+
+function startElectron() {
+  console.log(`[dev] Vite 已就绪，启动 Electron -> ${DEV_URL}`);
+  electron = spawn(electronPath, ['.'], {
+    cwd: root,
+    stdio: 'inherit',
+    env: { ...process.env, VITE_DEV_SERVER_URL: DEV_URL },
+  });
+  electron.on('exit', (code) => cleanup(code ?? 0));
+}
+
+vite.on('exit', (code) => {
+  if (code !== 0) console.error(`[dev] Vite 退出，code=${code}`);
+});
+process.on('SIGINT', () => cleanup(0));
+process.on('SIGTERM', () => cleanup(0));
+
+waitForPort();
@@ -0,0 +1,63 @@
+/**
+ * Windows 打包入口（等价于 electron-builder --win，但做了三件工程化处理）：
+ *
+ * 1) 复用本地已解压的 Electron：node_modules/electron/dist 存在时通过
+ *    --config.electronDist 直接使用，避免再下载 150MB+ 发行包（受网络影响最大的步骤）。
+ * 2) 默认使用国内镜像（可用环境变量覆盖）：
+ *      ELECTRON_MIRROR                   Electron 发行包
+ *      ELECTRON_BUILDER_BINARIES_MIRROR  nsis / winCodeSign 等构建工具
+ * 3) 缓存固定到仓库内的 .cache 目录，便于清理与迁移，不污染用户全局目录。
+ *
+ * 用法：
+ *   node scripts/dist-win.mjs            # nsis 安装包 + portable 单文件
+ *   node scripts/dist-win.mjs --dir      # 仅生成免安装目录 release/win-unpacked
+ */
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const repoRoot = path.resolve(root, '..', '..');
+const args = process.argv.slice(2);
+const dirOnly = args.includes('--dir');
+const passthrough = args.filter((item) => item !== '--dir');
+
+const env = {
+  ...process.env,
+  ELECTRON_MIRROR: process.env.ELECTRON_MIRROR ?? 'https://cdn.npmmirror.com/binaries/electron/',
+  ELECTRON_BUILDER_BINARIES_MIRROR:
+    process.env.ELECTRON_BUILDER_BINARIES_MIRROR ??
+    'https://npmmirror.com/mirrors/electron-builder-binaries/',
+  ELECTRON_BUILDER_CACHE:
+    process.env.ELECTRON_BUILDER_CACHE ?? path.join(repoRoot, '.cache', 'electron-builder'),
+  ELECTRON_CACHE: process.env.ELECTRON_CACHE ?? path.join(repoRoot, '.cache', 'electron'),
+};
+
+const localElectronDist = path.join(root, 'node_modules', 'electron', 'dist');
+const overrides = [];
+if (fs.existsSync(path.join(localElectronDist, 'electron.exe'))) {
+  overrides.push(`--config.electronDist=${localElectronDist}`);
+  console.log('[dist] 复用本地已解压的 Electron：', localElectronDist);
+} else {
+  console.log('[dist] 未找到本地 Electron，将由 electron-builder 下载（镜像：' + env.ELECTRON_MIRROR + '）');
+}
+
+const cli = path.join(root, 'node_modules', 'electron-builder', 'out', 'cli', 'cli.js');
+if (!fs.existsSync(cli)) {
+  console.error('[dist] 未找到 electron-builder，请先执行 pnpm install');
+  process.exit(2);
+}
+
+const cliArgs = [cli, '--win', ...(dirOnly ? ['--dir'] : []), ...overrides, ...passthrough];
+console.log('[dist] electron-builder', cliArgs.slice(1).join(' '));
+
+const child = spawn(process.execPath, cliArgs, { cwd: root, stdio: 'inherit', env });
+
+child.on('exit', (code) => {
+  if (code === 0) {
+    const output = path.join(root, 'release');
+    console.log('\n[dist] 打包完成，产物目录：', output);
+  }
+  process.exit(code ?? 1);
+});
@@ -0,0 +1,35 @@
+/**
+ * Electron 冒烟验证：以 ELECTRON_SMOKE_TEST=1 启动应用（不弹窗），
+ * 主进程会依次校验 preload 桥接、渲染进程挂载、登录页 DOM、
+ * IPC 往返、IndexedDB 缓存读写、断网回退缓存，然后自动退出。
+ *
+ * 前置条件：已执行 npm run build（需要 dist/main 与 dist/renderer）。
+ */
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import electronPath from 'electron';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const required = [path.join(root, 'dist/main/index.js'), path.join(root, 'dist/renderer/index.html')];
+const missing = required.filter((file) => !fs.existsSync(file));
+
+if (missing.length > 0) {
+  console.error('[smoke] 缺少构建产物，请先执行构建：');
+  console.error('  pnpm --filter @classhelper/desktop-client build');
+  for (const file of missing) console.error(`  缺失: ${path.relative(root, file)}`);
+  process.exit(2);
+}
+
+console.log('[smoke] 启动 Electron 冒烟验证...\n');
+const child = spawn(electronPath, ['.'], {
+  cwd: root,
+  stdio: 'inherit',
+  env: { ...process.env, ELECTRON_SMOKE_TEST: '1' },
+});
+
+child.on('exit', (code) => {
+  console.log(`\n[smoke] Electron 退出，code=${code ?? 1}`);
+  process.exit(code ?? 1);
+});