Peach: Local-first video metadata scraper and media manager.
test(web): 低频页 chunk 装载失败的重载与预热回归,ADR 补导出名与实测
longmeidaoe30ae0cbf551
diff --git a/docs/adr/0117-main-bundle-route-chunks.md b/docs/adr/0117-main-bundle-route-chunks.mdindex 108c514c0..a5a8bfb75 100644--- a/docs/adr/0117-main-bundle-route-chunks.md+++ b/docs/adr/0117-main-bundle-route-chunks.md@@ -14,7 +14,7 @@**一、入口固定名,低频页拆成带内容哈希的 chunk。** 入口仍是 `peach-app.js`,服务端 ETag 复验。路由表里的低频页面(JAV、统计、口味、复核、数据管理、重复文件、高清版、采集来源、配置与诊断、任务、关注管理、播放列表)由 `frontend/src/react/router/route-chunk.ts` 的 `routeChunk(() => import(...))` 动态导入,产物名 `peach-app.<名字>-<哈希>.js`,平铺在 `web/dist/`。首页目录、资料页、索引页、详情舞台、侧栏与设置面板等首屏和常驻部分留在入口。-**二、首屏用得到的模块留在入口。** 库模式默认 `preserveEntrySignatures: 'strict'`,入口不许多出导出,入口与 chunk 共用的模块会被拆成几十份公共 chunk,首屏变成一串瀑布请求。构建放开为 `allow-extension`,并用 `codeSplitting.groups` 把 `$initial`(入口静态可达)的模块收回入口:入口没有任何静态导入,chunk 从 `./peach-app.js` 导入共用模块,React、Query、历史与控件各只有一份实例。+**二、首屏用得到的模块留在入口。** 库模式默认 `preserveEntrySignatures: 'strict'`,入口不许多出导出,入口与 chunk 共用的模块会被拆成几十份公共 chunk,首屏变成一串瀑布请求。构建放开为 `allow-extension`,并用 `codeSplitting.groups` 把 `$initial`(入口静态可达)的模块收回入口:入口没有任何静态导入,chunk 从 `./peach-app.js` 导入共用模块,React、Query、历史与控件各只有一份实例。入口给 chunk 的导出保留源码名(`minifyInternalExports: false`,入口多 6.9 KB):压成单字母时入口任何改动都会让导出名整体错位,全部 chunk 跟着换哈希。**三、页面的代码与首屏数据并行取,取齐后同步画。** 路由的 `prefetch` 同时等 chunk 与接口,两样都落地才进入 `openManagedRoute` 的同步画页;不用 `React.lazy`,它第一次渲染总要挂起一次,等于多画一帧空白。首屏稳定后浏览器空闲时逐个预热全部 chunk,第一次进入低频页不再等代码。@@ -26,7 +26,7 @@## 后果-- 入口 3.80 MB → 2.61 MB(gzip 996 KB → 717 KB)。首屏请求数不变:入口之外的 chunk 一律按需或在空闲时取。+- 入口 3.80 MB → 2.62 MB(gzip 996 KB → 719 KB),首屏请求数不变:入口之外的 28 个 chunk(共 1.23 MB)一律按需或在空闲时取。真实小样本上交替各测 5 轮的中位数:首页冷加载第一个长任务 772 → 690 ms,load 1010 → 876 ms;预热后进入低频页与改前持平,没预热就进入多 10–45 ms。- 每次构建只有内容变了的 chunk 换名;`web/dist/` 的提交里会出现 chunk 的增删,提交时连同删除一起暂存。`tests/test_frontend_build.py` 核对 `web/dist/` 的 chunk 与产物引用一一对应。- 低频页模块里的样式不能靠排在首屏样式前面取胜;需要覆盖首屏样式时提高选择器特异性。- 视频墙(`catalog-grid-page.tsx` 静态引用)与设置面板(常驻组件,`configureSettingsPanel` 与组件同模块)仍在入口。diff --git a/frontend/test/route-chunk.test.ts b/frontend/test/route-chunk.test.tsnew file mode 100644index 000000000..766998871--- /dev/null+++ b/frontend/test/route-chunk.test.ts@@ -0,0 +1,61 @@+/* 低频页 chunk 的装载(ADR-0117):打开页面时装不上而服务还在,说明旧入口指着已删除的 chunk,整页重载一次;+ * 同一会话 30 秒内不重载第二次,服务连不上不重载,空闲预热失败不重载。 */+import { afterEach, beforeEach, expect, it, vi } from 'vitest';++let reload: ReturnType<typeof vi.fn>;+beforeEach(() => {+ vi.resetModules();+ sessionStorage.clear();+ reload = vi.fn();+ vi.stubGlobal('location', { ...window.location, reload });+});+afterEach(() => { vi.unstubAllGlobals(); vi.useRealTimers() });++const missing = () => Promise.reject(new TypeError('Failed to fetch dynamically imported module'));++it('装上之前 get() 抛错,装上之后同步拿到模块,第二次打开不再装载', async () => {+ const { routeChunk } = await import('../src/react/router/route-chunk');+ const load = vi.fn(async () => ({ Page: 'page' }));+ const chunk = routeChunk(load);+ expect(() => chunk.get()).toThrow('页面代码还没装载');+ await chunk.preload();+ await chunk.preload();+ expect(chunk.get()).toEqual({ Page: 'page' });+ expect(load).toHaveBeenCalledTimes(1);+});++it('打开时装不上而服务可达就重载一次,30 秒内再失败不重载,失败的那次不记住、下次重试', async () => {+ vi.stubGlobal('fetch', vi.fn(async () => ({ ok: true })));+ const { routeChunk } = await import('../src/react/router/route-chunk');+ const load = vi.fn(missing);+ const chunk = routeChunk(load);+ await expect(chunk.preload()).rejects.toThrow('dynamically imported module');+ expect(reload).toHaveBeenCalledTimes(1);+ expect(vi.mocked(fetch).mock.calls[0]?.[0]).toBe('/healthz');+ await expect(chunk.preload()).rejects.toThrow('dynamically imported module');+ expect(load).toHaveBeenCalledTimes(2);+ expect(reload).toHaveBeenCalledTimes(1);+});++it('服务连不上时不重载,错误交给页面', async () => {+ vi.stubGlobal('fetch', vi.fn(async () => { throw new TypeError('offline') }));+ const { routeChunk } = await import('../src/react/router/route-chunk');+ await expect(routeChunk(missing).preload()).rejects.toThrow('dynamically imported module');+ expect(reload).not.toHaveBeenCalled();+});++it('空闲预热逐个装载,失败不重载,留到打开时再试', async () => {+ vi.stubGlobal('fetch', vi.fn(async () => ({ ok: true })));+ vi.stubGlobal('requestIdleCallback', (callback: () => void) => { queueMicrotask(callback); return 0 });+ const { routeChunk, warmRouteChunks } = await import('../src/react/router/route-chunk');+ const broken = vi.fn(missing);+ const fine = vi.fn(async () => ({ ok: 1 }));+ routeChunk(broken);+ const chunk = routeChunk(fine);+ warmRouteChunks();+ await vi.waitFor(() => expect(fine).toHaveBeenCalledTimes(1));+ expect(broken).toHaveBeenCalledTimes(1);+ expect(chunk.get()).toEqual({ ok: 1 });+ expect(reload).not.toHaveBeenCalled();+ expect(fetch).not.toHaveBeenCalled();+});