Skip to content

armgit / peach

Public Imported from GitHub
0

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.md
index 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.ts
new file mode 100644
index 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();
+});