首页首屏性能问题：启动后约十秒整页空白且无提示（含首页全前端演进方案）

[1w1w11w1]

首页首屏性能问题：启动后约十秒整页空白且无任何提示（含「首页全前端」演进方案）

概述

用户在前端调起后，首页从「全空」到「活动信息等板块正确加载」之间约有 10 秒空白，期间空白区域完全无加载提示；切换页面同样是全空、无提示，只能等待。该等待还与本地网络状态相关，开启代理/弱网时明显更久。

本 issue 记录实测数据、根因定位，以及一个按「首页全前端」方向拟定的演进方案。

可观察现象

1. 应用启动后约 10 秒内，主页（以及此期间切换到的其他页面）为空白，无骨架/加载/错误提示。
2. 等待结束后活动卡、方舟关卡、代理概况一次性出现。
3. 延迟随网络状态（代理开启程度、弱网）明显放大。

实测数据（冷启动探针）

对 POST /api/info/get/overview 在启动后逐秒采样：

时间点	overview	setting	scripts	notice
t≈2.7s（首次）	17176ms	15ms	101ms	7ms
t≈21s+	39ms	12ms	67ms	5ms

后端日志显示：Uvicorn running（t≈18.6s）后，到 t≈35.7s 之间 事件循环没有任何一条日志，活动服务自己发起的后台 TCP 连接也要排到 t≈35.7s 才开始。即：Uvicorn 已可接收连接，但后端事件循环被冻结了约 17 秒，这段时间内所有 API 请求（不限于 overview）都排队等待。前端此时已连上主 WebSocket、已渲染，但所有数据请求都排在冻结窗口之后——这正是「主页全空、切页也全空」的来源。

该冻结与网络无关（关闭 MCP、关闭所有远端依赖后复测仍约 17 秒），属于后端后台初始化自身的同步/CPU 占用阻塞事件循环。

另外注意：setting/scripts/notice 在同一窗口内仅几十毫秒，说明首屏慢不是这些页面慢，而是全部请求共同被冻结窗口延迟。

根因定位

「十秒空白」由两个相互独立的根因叠加：

根因 A — 后端事件循环冻结（约 17s）
main.py 后台初始化段（clean_maafw_agent_venvs → MaaFW 适配器导入 → ArknightWin32Toolkit.init → MainTimer.start）在事件循环内执行耗时初始化，逐项实测各模块导入约 1–2s，但叠加 + 进程内行为合计把事件循环卡住约 17s，期间 overview/scripts/setting 等全部接口静默排队。

根因 B — 前端引导期门禁

• Home.vue:49 内容区以 layoutReady && !isBootstrapping 为条件，引导期间直接不渲染内容卡。
• 路由守卫在 isBootstrapping 为真时把一切非 /home 导航强制打回 /home。
• 因此引导期内既无内容、又不允许跳转，表现为「全空 + 切页也全空 + 无提示」。

演进方向：首页全前端

背景：首页数据当前 100% 依赖后端聚合接口 POST /api/info/get/overview（app/api/info.py:270），由 asyncio.gather 聚合 7 个第三方活动源 + 方舟关卡 + 代理历史后一次性返回；前端(useHomeOverview.ts:66) 只是渲染壳 + 轮询兜底。

拟定方向为「首页全前端」：让活动卡在浏览器端直接请求各第三方源，逐卡独立超时/缓存/失败，从而不再受后端事件循环约束。

可行性：CORS 已实测全部放行

以 Origin: http://localhost:5173 + cors 模式探测各源响应头：

卡片	来源 host	Access-Control-Allow-Origin
星穹 / 原神 / 绝区零 / 鸣潮 / 异环（5 卡）	starrailassistant.top	*
重返未来	api.1999.fan	*
终末地	data.akedata.wiki	*

* 对开发环境 http://localhost 与生产版 file://（null origin，无凭证）均成立，浏览器直连技术上可行。

关键：全前端并非字面全前端

• 方舟关卡：依赖后端关卡缓存 + 硬编码资源表（RESOURCE_STAGE_INFO / RESOURCE_STAGE_DATE_TEXT 等）。
• 代理概况：读取本机 history/ 目录（search_history / merge_statistic_info），属本地数据。

这两张卡第三方源给不了，必须留后端。因此目标形态是「7 张活动卡走前端 + 方舟/代理 2 张卡留后端」，后端聚合接口相应瘦身。

各卡成本差异

卡片	成本
SRA 5 卡（sr/ys/zzz/ww/nte）	最低：同 host 同格式，一个解析器复用
重返未来	中：单 JSON（api.1999.fan/.../cn.json）
终末地	高：需拉 manifest.json + 6 张 GameTable JSON，再做 i18n 文本解析 + 时区换算合并

分阶段演进方案

• Phase 0 — 前端引导期解卡（最便宜，收益直观）：去掉 !isBootstrapping 对内容卡的硬性隐藏，改为卡片各自显示骨架/加载态；引导期放行导航，各页自处理 loading。消除「全空且无提示 + 切页全空」。
• Phase 1 — 后端事件循环解冻（全前端与否都必须做）：将 main.py 后台初始化中冻结事件循环的段用 asyncio.to_thread 挪出主循环，或推迟到首屏之后。令 overview/scripts/setting 等从 17s 降至毫秒级。
• Phase 2 — SRA 5 卡转前端：新建前端 composable 直连 starrailassistant.top/api/v1/activity/{game}.json，逐卡超时/缓存/退避；类型复用 types/home.ts 的 SraActivityOverview。
• Phase 3 — 重返未来转前端：复用 Phase 2 管线，仅 URL/字段不同。
• Phase 4 — 终末地：决策点。建议先留后端（Phase 1 解冻后测实测再定）；完整 TS 移植（7 文件管线 + i18n + 时区）成本高，仅当解冻后仍显慢才投入。
• Phase 5 — 后端瘦身：/get/overview 移除已迁前端的服务，只回 Stage + Proxy（或拆 /overview/local）；删除后端无调用方的活动服务/缓存，避免双份逻辑漂移。

结构性风险

• 第三方源改格式/挂掉：前端逐卡独立超时 + 失败态；保留后端缓存作兜底（Phase 1 后成本低）。
• 跨端逻辑双份/漂移：Phase 5 删除后端旧逻辑，只留单一归属方。
• 终末地复刻成本：先 A 后 B，以实测决定，不预先投入。
• file:// + * CORS 边角：已实测 null 源可用，生产无凭证请求确认即可。
• 引导期/路由门禁未同步改：Phase 0 独立前置。

优先级建议

Phase 0 → Phase 1 → 评估 → Phase 2 →（Phase 3/4 按实测）。Phase 0+1 即可将「全空十秒」降为亚秒级且带骨架，且是「全前端」方向的共同前提（方舟/代理依赖 Phase 1）；Phase 2 为拟定方向的核心落地，以实测决定 Phase 4 的 A/B。

[1w1w11w1]

跟进：首页空白的真正根因与已落地修复（2026-08-31 复测）

修正之前的根因判断

上一版方案把根因 A 归为「后端事件循环冻结（bg-init）」与「首页被 !isBootstrapping 门禁隐藏」。本轮做了更完整的真实运行取证（读前端 electron-log 与后端 uvicorn 访问日志、时间戳交叉比对），结论修正如下：

1. 「启动后约十秒空白」的直接原因 = 首页数据等待一个聚合接口 + 引导期门禁：
   • 首页所有数据来自一个接口 POST /api/info/get/overview，而各家活动卡（终末地/1999/SRA×5）卡片是 a-card :loading——加载期间整个卡片被骨架屏取代，无其它提示。
   • 实测用户真实运行（22:13 那轮）：应用引导完成后立即请求 overview，响应 20 秒后才返回（22:13:16 → 22:13:29 送达后端、处理后仅 35ms）；期间用户看到的首页数据区始终是空/骨架。
2. 同期观测到一次真实的 13.2s 事件循环冻结（22:13:16.015 → 22:13:29.226，后端日志零输出、所有请求排队，解冻后瞬间处理完）：
   • 已排除：bg-init（冻结发生在其完成 27s 之后）、ArknightsPC/GameSign（配置未启用）、活动关卡冷缓存（当时是缓存直取）。
   • 尚未定位到精确的阻塞调用（需要复现时的 faulthandler 堆栈采样，见下）。
3. 后端启动速度：当前启动路径仍有可观的冷启动开销（初始化+后台任务约 5-8s），且首次接口调用受冷缓存影响大——已记录，作为后续专项（会补充启动分段耗时数据）。

已落地修复（前端侧，不改后端）

• Home.vue：首页内容不再等 isBootstrapping 结束才渲染（骨架/空态即刻可见）。
• useHomeOverview.ts：概览本地快照（stale-while-revalidate）——启动即用上次成功的 overview 快照填充各卡片，后台静默刷新；有快照时刷新过程不再用骨架屏遮挡内容（loading 仅在无任何数据时为真）。
• 验证：后端进程手动停止后，首页仍在 ~3s 内渲染出上一轮全部卡片数据（代理状态/终末地/星穹铁道等），不再依赖后端即时可用。

效果

• 正常启动：首页内容即时渲染（上次快照），数据在后台刷新，无 10-20s 空白 / 全骨架。
• 后端冷启动 / 弱网 / VPN：首页不白屏，内容先显示，数据陆续补全。
• 事件循环冻结（13s 类）不再影响首页观感；但该冻结本身仍值得根治。

待办

• 后端首次 overview 延迟与 13s 冻结：建议复现时在 app/api/info.py 的 overview 处理器加 faulthandler.dump_traceback_later(3, exit=False) 类采样，拿到冻结时的调用栈；当前方案未触及后端。
• 后端启动冷启动耗时：作为下一项性能专项，先补启动各阶段计时。

[1w1w11w1]

第 2 轮：全面提速 + 主页全前端化（测量驱动，附基线与阶段计划）

已确认修复（上一轮落地，用户已验收）

• 首页不再"十秒空白"：内容即时渲染 + 概览本地快照 SWR（后端进程停掉时 2.9s 内渲染全部卡片）。
• 但"看起来快"≠ 快：本轮聚焦真实性能，全部数字来自实测。

实测基线（本机 @ dev）

后端冷启动：

• 进程启动 → 可服务：2.5s（变数 2.0~5.5s，受 Windows 缓存/外置盘影响）
• → 后台初始化完成：4.9s
• imports ≈1s（app.core.config 链 793ms：models.schema 自耗 321ms + models.config 460ms；MaaEnd 381ms；mcp 325ms）；应用构建 + lifespan ≈1.2s；bg-init +2.4s（ArknightWin32 初始化 ≈1s，禁用状态也加载 pyautogui/keyboard 全套；MaaEnd 资源读取走 D:\Script\MaaEnd）
• 复测到 13.2s 事件循环冻结一次（22:13 轮；已排除 bg-init/ArknightsPC/GameSign/关卡缓存，未定位）

前端生产构建：总 JS ≈7~8MB；主 chunk 2.46MB（完整 ant-design-vue）、Monaco 3.58MB（懒 chunk）、Home 702KB（three.js）、sourcemap 28MB 进包。

调度链路：派发为 WS 事件驱动（无轮询延迟），日志渲染 200ms 节流；实际延迟主要是引擎/模拟器启动（秒级）+ 启动队列故意 +10s（防跨日）。已排除"调度 UI 轮询 10s"猜想。

首页数据：聚合接口冷调用 1320s（端上仅 35ms，其余为排队/网络），热调用 130200ms——这正是全前端化的直接理由。

更新后的分阶段方案（测量驱动，每阶段有验收标准）

• P1 后端启动提速（目标可服务 <1.2s）：config.py 顶层 import 瘦身（uvicorn 仅为类型注解、jinja2 懒加载）；ArknightWin32 重依赖惰性化（启用时才 import）；MaaEnd 链懒加载评估；启动分段计时（诊断基建）；冻结恢复用 faulthandler 堆栈采样。
• P2 前端产物体积（主 chunk <1.2MB）：ant-design-vue 按需导入；three.js 异步化；sourcemap 不进包；拆分被静态引用的 Monaco/调度逻辑依赖。
• P3 调度响应：先做 start→running 三段计时测量；启动队列 10s 改为可配置；引擎预热评估（若瓶颈确在引擎启动则不做无谓改动）。
• P4 主页全前端化（方向不变）：每卡独立数据源 + 独立 SWR 快照（复用已落地模式）：SRA 5 卡 → reverse1999 → endfield（决策点保留）；聚合接口瘦身为本地卡（方舟 Stage + 代理）。
• P5 后端瘦身：overview 仅剩本地数据后，后端路由/schema 负载随之下调。

执行顺序建议

P1.1/1.2（最小 diff、−1s）→ P1.5 测量基建 → P2.1/2.3（纯前端低风险）→ P4 SRA 5 卡 → 其余按测量结果决定。

详细报告：debug/PERFORMANCE_REPORT.md（本机复现材料齐备：importtime、生产构建产物、日志交叉比对方法）。