加载速度优化设计方案

概述

针对手机端访问 kongjianguan.fyi 时 Teek 主题加载动画（"正在开门..."）长时间旋转的问题，通过精简首屏 JS 体积、优化部署缓存策略来缩短首次加载时间。

现状：3.6MB theme JS + 256KB CSS，首次加载 1-2 分钟 目标：首屏 JS 降至 ~1.5MB，加载时间缩至 20-30 秒，二次访问秒开

---

分析结论

瓶颈定位

资源	大小	下载耗时	影响
theme.0XAt0Hy5.js	3.6 MB	~100 秒	核心阻塞：Teek 主题 + ECharts 全量打包
style.B1FYmon-.css	256 KB	~29 秒	Twikoo 未使用样式占 50-80KB
mermaid 相关 chunks	~2 MB	已懒加载	不影响首屏
background images (100+)	~200KB/张	懒加载	只预加载下一张，不阻塞

根因

Teek 主题的路由加载遮罩（"正在开门..."）在 Vue 完全水合（hydrate）前一直显示。手机上 3.6MB JS 的下载、解析、编译、执行过程均阻塞渲染。

对比：kanoverse.com

• 使用 Next.js（SSR），HTML 返回即含完整内容
• 首屏 JS ~740KB，是当前的 1/5
• 结论：部署平台（均为 Vercel）不是瓶颈，框架架构和 JS 体积是核心差异

---

优化措施

1. ECharts 动态导入

文件：docs/.vitepress/theme/components/ContributeChart.vue

改动：将顶层静态导入 import * as echarts from "echarts" 改为按需动态导入：

// 改前（打包进 theme chunk）
import * as echarts from "echarts";

// 改后（仅在组件进入视口时加载）
onMounted(async () => {
  const echarts = await import("echarts");
  // ...
});

预期：首屏 JS 减少 ~1-1.5MB 风险：低。ContributeChart 只在归档页可见，利用已有的 useIntersectionObserver 在进入视口时再加载即可。

2. 删除未使用的 Twikoo 样式

文件：

• docs/.vitepress/theme/style/Twikoo.scss（删除文件）
• docs/.vitepress/theme/style/index.scss（移除导入行）

原因：评论系统使用的是 Giscus，Twikoo 样式完全未使用。

预期：CSS 减少 50-80KB

3. 清理注释图片

文件：docs/.vitepress/config/BackgroundImg.ts

改动：删除所有被 // 注释或包裹在 /* */ 中的图片条目，只保留实际生效的图片 URL。

预期：数组从 ~100 条减至 ~60 条。不影响加载性能（背景图已懒加载），但提升代码可维护性。

4. 部署优化（vercel.json）

文件：项目根目录新增 vercel.json

内容：

{
  "headers": [
    {
      "source": "/assets/(.*)",
      "headers": [
        { "key": "Cache-Control", "value": "public, max-age=31536000, immutable" }
      ]
    }
  ]
}

额外操作：

• 在 Vercel 项目面板中启用 Brotli 压缩（Settings → Enable Brotli）

预期：二次访问全量命中浏览器缓存，实现秒开。Brotli 比 gzip 再压缩 20-30%。

5. 不变动（已验证正常）

• mermaid 懒加载：vitepress-plugin-legend 已按 diagram 类型拆分为独立 chunk，按需加载
• 背景图懒加载：Teek 的 body-bg-image 组件只预加载下一张图，不会批量下载

---

预期效果

指标	优化前	优化后
首屏 JS 体积	3.6 MB	~1.5-2 MB
CSS 体积	256 KB	~180 KB
首次加载时间（20Mbps）	1-2 分钟	20-30 秒
二次访问	同上	秒开（缓存）
代码可维护性	—	清理无用图片和样式

---

实施顺序

1. ECharts 动态导入（核心收益）
2. 删除 Twikoo 样式
3. 清理 BackgroundImg.ts
4. 创建 vercel.json 并启用 Brotli
5. 构建验证 + 部署测试