Genarrative/docs/technical/FRONTEND_FIRST_LOAD_PERFORMANCE_FIX_2026-04-26.md

前端首次加载慢修复记录

日期：2026-04-26

1. 背景

网站启动后首次打开页面约需三分钟才出现可用界面。已确认 Vite dev server 本身可在数秒内 ready，因此本次不继续扩大 api-server 冷编译等待窗口，而是收口浏览器首屏可见链路。

2. 现象与根因

本次排查发现两个会放大首屏等待的前端问题：

1. RouteImageReadyGate 会先挂载真实业务页面但把整页 visibility: hidden，扫描路由 DOM 中所有 <img> 和 CSS 图片，等全部图片 settled 后才显示页面。平台首页和运行时页面会渲染作品封面、角色图、图标和生成资源，任何慢图片或后端图片代理等待都会把整页可见时间拖长。
2. Vite dev server 监听范围过宽，日志中可见 docs/、scripts/、server-rs/ 和测试文件变更都会触发 page reload。后端编译、文档更新或测试文件保存会让浏览器反复全量重载，叠加首屏图片门控后表现为“首次加载一直等”。

3. 修复口径

3.1 首屏图片门控

首屏门控从“等待所有图片加载完成”改为“短暂稳态等待后放行”：

• 页面仍先真实挂载，保留极短等待窗口，避免首帧布局剧烈闪动。
• 达到最大阻塞时间后必须显示页面，慢图片由浏览器渐进加载，不再隐藏整页。
• 页面已经显示后，不再因为新增图片或图片地址变化重新隐藏页面。
• 图片预加载继续保留，用于提前触发浏览器缓存，但不得成为首屏可见的硬阻塞。

3.2 Vite 监听范围

Vite dev server 只对前端真实运行入口保持热更新敏感：

• 忽略 docs/、server-rs/、scripts/、backend-rewrite-tasklist/、media/ 等非前端首屏运行目录。
• 忽略 *.test.ts(x) / *.spec.ts(x)，避免测试文件保存触发页面 reload。
• 保留 src/ 与 packages/shared/ 的正常变更反馈，因为它们仍是前端运行时依赖。

4. 验收标准

1. Vite ready 后，默认站点首屏不再等待所有图片完成才显示。
2. 慢图片、失败图片或生成资源代理慢时，页面主体仍能先显示并保持可操作。
3. 修改 docs/、server-rs/、scripts/ 或测试文件时，不再触发前端页面 reload。
4. RouteImageReadyGate 工具测试覆盖慢图片仍会放行首屏的行为。
5. 修改中文文件后运行编码检查，确保没有破坏 UTF-8 文本。