From 45898cba4eed69e8b4a50009646436b2b8b192b7 Mon Sep 17 00:00:00 2001 From: kdletters Date: Sun, 26 Apr 2026 15:35:40 +0800 Subject: [PATCH] =?UTF-8?q?=E4=BC=98=E5=8C=96=E5=89=8D=E7=AB=AF=E9=A6=96?= =?UTF-8?q?=E6=AC=A1=E5=8A=A0=E8=BD=BD=E4=BD=93=E9=AA=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...D_FIRST_LOAD_PERFORMANCE_FIX_2026-04-26.md | 41 +++++++++++++++++++ docs/technical/README.md | 1 + vite.config.ts | 10 +++++ 3 files changed, 52 insertions(+) create mode 100644 docs/technical/FRONTEND_FIRST_LOAD_PERFORMANCE_FIX_2026-04-26.md diff --git a/docs/technical/FRONTEND_FIRST_LOAD_PERFORMANCE_FIX_2026-04-26.md b/docs/technical/FRONTEND_FIRST_LOAD_PERFORMANCE_FIX_2026-04-26.md new file mode 100644 index 00000000..4178d9d2 --- /dev/null +++ b/docs/technical/FRONTEND_FIRST_LOAD_PERFORMANCE_FIX_2026-04-26.md @@ -0,0 +1,41 @@ +# 前端首次加载慢修复记录 + +日期：`2026-04-26` + +## 1. 背景 + +网站启动后首次打开页面约需三分钟才出现可用界面。已确认 Vite dev server 本身可在数秒内 ready，因此本次不继续扩大 `api-server` 冷编译等待窗口，而是收口浏览器首屏可见链路。 + +## 2. 现象与根因 + +本次排查发现两个会放大首屏等待的前端问题： + +1. `RouteImageReadyGate` 会先挂载真实业务页面但把整页 `visibility: hidden`，扫描路由 DOM 中所有 `` 和 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 文本。 diff --git a/docs/technical/README.md b/docs/technical/README.md index 03f2ce4a..72c30d36 100644 --- a/docs/technical/README.md +++ b/docs/technical/README.md @@ -5,6 +5,7 @@ ## 文档列表 - [SPACETIMEDB_TABLE_CATALOG.md](./SPACETIMEDB_TABLE_CATALOG.md)：持续维护当前 SpacetimeDB 表目录，按领域说明每张表的作用、字段结构、索引和常用 `spacetime sql` 查询模板。 +- [FRONTEND_FIRST_LOAD_PERFORMANCE_FIX_2026-04-26.md](./FRONTEND_FIRST_LOAD_PERFORMANCE_FIX_2026-04-26.md)：记录网站启动后首次加载约三分钟的前端根因，收口 `RouteImageReadyGate` 首屏图片门控和 Vite dev server 无关文件监听范围。 - [RPG_WORK_DELETE_SPACETIMEDB_PROCEDURE_EXPORT_FIX_2026-04-25.md](./RPG_WORK_DELETE_SPACETIMEDB_PROCEDURE_EXPORT_FIX_2026-04-25.md)：记录 RPG 作品删除时报 `No such procedure` 的根因，补齐 `delete_custom_world_agent_session` 在有效 SpacetimeDB 模块入口中的导出，并要求发布后核验 Maincloud schema。 - [CURRENT_BACKEND_IMPLEMENTATION_BASELINE_2026-04-25.md](./CURRENT_BACKEND_IMPLEMENTATION_BASELINE_2026-04-25.md)：冻结当前后端唯一落地口径，明确新功能以 `server-rs + Axum + SpacetimeDB` 为准，旧 `server-node` / Express / PostgreSQL 与 Go 方向只允许作为迁移参考。 - [RPG_DRAFT_GENERATION_CONTINUE_AND_ETA_FIX_2026-04-25.md](./RPG_DRAFT_GENERATION_CONTINUE_AND_ETA_FIX_2026-04-25.md)：记录世界草稿生成失败/中断后进度不再误到 `100%`、主按钮改为“继续生成草稿”并复用已保存底稿续跑，以及按阶段耗时模型估算预计等待时间的修复口径。 diff --git a/vite.config.ts b/vite.config.ts index 1dea3aab..a51976db 100644 --- a/vite.config.ts +++ b/vite.config.ts @@ -16,6 +16,16 @@ export default defineConfig(({mode}) => { '**/public/generated-characters/**', '**/public/generated-custom-world-scenes/**', '**/public/generated-qwen-sprites/**', + '**/backend-rewrite-tasklist/**', + '**/docs/**', + '**/jenkins/**', + '**/media/**', + '**/scripts/**', + '**/server-rs/**', + '**/*.test.ts', + '**/*.test.tsx', + '**/*.spec.ts', + '**/*.spec.tsx', ]; const rustServerTarget = env.RUST_SERVER_TARGET ||