[RFC] 082 - 应用页面打开速度优化

[arvinxx]

背景

• [RFC] 076 - 操作卡顿性能优化 #5105

本 RFC 讨论如何提升应用的页面打开速度

设计思路

现状回顾

首先回顾下现有的实现。 LobeChat 目前的应用结构，是完全基于 SSR/RSC 的研发范式来的。它的好处有两点：

第一点：首屏感知

SSR 能带来更好的首屏感知，一般 SPA 的首屏最多加个 load 就完事了，但是通过 SSR + 水合的方式，能做到首屏直出应用的完整骨架屏。

以 https://lobechat.com/chat 为例，SSR 首屏直出是这样的：

如果点 devtools 去看的话，首屏返回的 html 直接就是 loading 的样子：

这就意味着当服务端返回 html 时，用户看到的就是已经等待加载数据的样子。而如果换到 SPA 的话，这个骨架屏大概率要等到 JS 加载完之后才能出现，也会遇到俗称的瀑布加载的问题。所以在首屏角度来看，采用 SSR的体验会明显好于纯 SPA。

第二点：按需下发页面资源

在 SSR 之上，新的 RSC 带来了更强的服务端渲染能力，能带来更好的移动端首屏体验（详见：#252 ）。

上面这个就是从 SSR Layout 切到 RSC Layout 之后带来的性能提升，因为只用加载一套移动端 layout 的 js ，bundle 一下子就小了很多。而 SSR还是要同时带上 PC 和移动的两份 JS。

---

选择现有方案的原因已经讲明，那接下来需要回答的问题就是，为什么现在 SSR/RSC 的实现，会比 SPA 要慢这么多？比如我们的一位用户跟我反馈：

手搓简陋单页面版本的，首次打开，1秒内打开即用。 next那个首次，3秒内打开可用，lb版本首次打开9秒左右才可以用。我是本地部署的。现在是用的lb。 不知道是不是每次浏览器第一次打开lb, 服务端就才即时才生成的网页源码。 就是很慢的感觉。

经过仔细研究，我发现根因也是 SSR。Next 的 SSR 有两种形式，一种是 Static Render，另一种则是 Dynamic Render，根据 官方文档 中的说明，当应用中有使用以下任何一种方法时，nextjs 都会自动把页面渲染模式切换为 Dynamic Render ：

• cookies
• headers
• connection
• draftMode
• searchParams prop
• unstable_noStore

而我们为了移动端 / 桌面端不同页面布局的适配，使用了 headers 来获取用户的 ua；为了避免亮暗色主题、多语言、LTR 导致的 FOUC，我们使用了 cookies 。这就会导致页面默认进入了动态渲染。

而从 SPA 时期过来的我们，在做这个方案的时候只考虑用户看到的第一眼的问题（访问速度的问题在本地开发时是完全感知不到的），却不曾想到这种看似良好的体验，早已在暗中标记好了价格。

动态渲染最大的一个缺陷是，必须要回源到服务器做计算生成（nextjs 会在请求层面将 Cache Control 设为不做任何缓存，必须回源），没法复用 CDN 静态缓存，所以带来的问题有两方面：

1. 请求链路就会变成 用户 → CDN → 服务器 → 返回CDN → 返回用户，请求环节变多，耗时会提升；
2. 服务器生成 HTML 耗时视应用复杂度，从百毫秒到几秒甚至十几秒不等；

这就是目前 LobeChat 整体页面打开缓慢的根本原因。我们部署的 Cloud 实例，由于在 Vercel 上，计算耗时相对还好，能控制在 1~2s 左右，而如果用户是自部署的情况，可能就会出现耗时几秒甚至十几秒的情况。

解决思路

其实知道了根本原因，解决的思路就很清晰了：想方法做缓存。

因为根据我们的实际情况来说，不同设备、不同语言只需要算一次 HTML，后续复用这套 html 即可，不需要每次都重新计算。

所以理论上只要针对不同设备、语言、主题提供一套预先渲染好的 html ，只要访问请求命中组合，就直接返回 CDN 缓存的内容，页面就能做到接近秒开。

思路有了，但是具体该怎么做？期间我探索了两种方式，Vary Headers 和 variant path segment 静态化。

Vary Header 方案

一开始想从 CDN cache 角度找方案，自然而然就找到了 Vary Header。但经过一番尝试，发现这方案不太行。

• https://github.com/lobehub/lobe-chat/pull/5239/files#diff-0626369278c89781505d2c04865ecce1302e979271bcfb471e029c19addc13a0R41

原因是 Nextjs 会在框架层直接覆写 Vary 强制变成： RSC, Next-Router-State-Tree, Next-Router-Prefetch, Next-Router-Segment-Prefetch，导致 Vary 设置失效。社区也有对应的 issue 提出：

• vary header can't be overwritten even defined explicitly in middleware vercel/next.js#55396

而后咨询了 Vercel 的 Lee ，他说 Vary 这个方案存在的一个明显的问题是并非所有的 CDN 供应商都遵循 Vary 规范，就会导致缓存不一定真正有效。而是推荐了另外一种他们在 v0 中的实现思路，就是 variant segment rewrite + 静态化。

variant segment rewrite

这个实现静态化的方案非常巧妙，主要通过以下几个关键点实现：

1. 中间件重写变量路由段

在 middleware 中读取 header、cookie 状态并组合成 variant segment，然后加到路由最前面做重写：

const defaultMiddleware = (request: NextRequest) => {
  // 1. 从 cookie 中读取用户偏好
  const theme = request.cookies.get(LOBE_THEME_APPEARANCE)?.value || 'light';

  const locale = request.cookies.get(LOBE_LOCALE_COOKIE)?.value;

  const ua = request.headers.get('user-agent');

  const device = new UAParser(ua).getDevice();

  // 2. 创建规范化的偏好值
  const route = RouteVariants.serializeVariants({
    isMobile: device.type === 'mobile',
    locale,
    theme,
  });

  // 重写 URL，构建新路径: /${route}${originalPathname}
  url.pathname = `/${urlJoin(route, url.pathname)}`;

  return NextResponse.rewrite(url);
};

这样就可以做到最终的请求是：

[rewrite] /chat -> /zh_0_light/chat

2. 静态参数生成

通过新增一个路由段[variant]，然后在这里的 layout.tsx 添加 generateStaticParams 函数实现静态路由的参数预生成：

export const generateStaticParams = () => {
  const themes: ThemeAppearance[] = ['dark', 'light'];
  const mobileOptions = [true, false];
  // only static for serveral page, other go to dynamtic
  const staticLocales = [DEFAULT_LANG, 'zh-CN'];

  const variants: { variants: string }[] = [];

  for (const locale of staticLocales) {
    for (const theme of themes) {
      for (const isMobile of mobileOptions) {
        variants.push({
          variants: RouteVariants.serializeVariants({ isMobile, locale, theme }),
        });
      }
    }
  }

  return variants;
};

3. 变体序列化

• 使用 RouteVariants.serializeVariants 函数将不同的参数组合序列化成字符串
• 包含了移动端标识、主题、语言等参数

生成的路径段例如： /zhCN_0_light 、 /en-US_1_dark。

4. 动态布局处理

通过 RootLayout 组件处理动态内容：

const RootLayout = async ({ children, params, modal }: RootLayoutProps) => {
  const { variants } = await params;

  const { locale, isMobile, theme, primaryColor, neutralColor } =
    RouteVariants.deserializeVariants(variants);

  const direction = isRtlLang(locale) ? 'rtl' : 'ltr';

  return (
    <html dir={direction} lang={locale} suppressHydrationWarning>
      <body>
        <GlobalProvider
          appearance={theme}
          isMobile={isMobile}
          locale={locale}
          neutralColor={neutralColor}
          primaryColor={primaryColor}
        >
          {children}
        </GlobalProvider>
      </body>
    </html>
  );
};

由于在这个 Layout 中已经没有了 cookie、header 等动态内容，因此页面就可以完全静态化。已经测试了 POC 方案，效果显著：

• ⚡️ perf: make app page as static route to improve performance #5478

基本能做到首次打开 1s 以内，第二次打开 500ms 以内。

因此接下来会基于这个方案做更进一步的梳理，争取在 2 月底之前完成上线。

[arvinxx]

Vary Header 相关经验

Vary 头是 HTTP 响应头之一，它告诉缓存服务器（如 CDN）在缓存响应时，除了 URL 之外，还需要基于哪些 HTTP 头来区分缓存版本。当指定 Vary: cookie 时，表示需要基于请求的 Cookie 头的值来区分不同的缓存版本。

举个具体例子：

假设有一个页面 https://example.com/page

用户 A 的请求：
Cookie: theme=dark; language=en
→ 生成并缓存深色主题、英文版本的 HTML

用户 B 的请求：
Cookie: theme=light; language=zh
→ 生成并缓存浅色主题、中文版本的 HTML

在这种情况下，CDN 会为同一个 URL 维护多个缓存版本：

缓存键的组成：
URL + Cookie 值的哈希

例如：
/page_hash(theme=dark;language=en)  → HTML内容1
/page_hash(theme=light;language=zh) → HTML内容2

但是这里有一个重要的问题：默认情况下，Vary: cookie 会基于整个 Cookie 头进行缓存区分，这可能会导致缓存效率低下。因为用户的 Cookie 中可能还包含其他与页面渲染无关的值（如会话 ID、跟踪代码等）。

所以，更好的做法是在 middleware 中只保留关键的 cookie：

// middleware.ts
export function middleware(request: NextRequest) {
  const theme = request.cookies.get('theme')?.value || 'light'
  const language = request.cookies.get('language')?.value || 'en'
  
  // 1. 创建一个新的响应
  const response = NextResponse.next()
  
  // 2. 设置规范化的 Cookie 头
  // 只包含影响页面渲染的 cookie
  response.headers.set(
    'Cookie',
    `theme=${theme}; language=${language}`
  )
  
  // 3. 告诉 CDN 基于 Cookie 头缓存
  response.headers.set('Vary', 'cookie')
  
  return response
}

这样做的好处：

1. 缓存效率提升：

// 不好的例子 - 可能导致过多的缓存变体
Cookie: theme=dark; language=en; sessionId=123; tracking=abc
Cookie: theme=dark; language=en; sessionId=456; tracking=xyz
// 这样会产生两个不同的缓存版本，尽管页面内容是一样的

// 好的例子 - 只关注必要的 cookie
Cookie: theme=dark; language=en
// 不管其他 cookie 如何变化，只要 theme 和 language 相同，就使用同一个缓存版本

2. 可预测的缓存行为：

// 可以准确计算缓存变体数量
const themeCount = 2  // light, dark
const languageCount = 3  // en, zh, es
const totalVariants = themeCount * languageCount  // 6个变体

3. 更好的缓存命中率：

// 添加缓存状态监控
response.headers.set('X-Cache-Status', 'HIT/MISS')
response.headers.set('X-Cache-Key', `${theme}-${language}`)

4. 调试友好：

// 可以添加调试信息
response.headers.set('X-Cache-Debug', JSON.stringify({
  theme,
  language,
  url: request.url,
  timestamp: new Date().toISOString()
}))

需要注意的限制：

1. Cookie 大小限制：

// 需要确保规范化后的 Cookie 不会太大
const cookieValue = `theme=${theme}; language=${language}`
if (cookieValue.length > 4096) {
  console.warn('Cookie value too large')
}

2. 缓存键的唯一性：

// 确保缓存键的组成部分是确定的
const cacheKey = `${request.url}_${theme}_${language}`.toLowerCase()

3. 缓存刷新策略：

// 当主题或语言配置更新时，需要有机制刷新缓存
response.headers.set(
  'Cache-Control',
  'public, s-maxage=3600, stale-while-revalidate=86400'
)

使用建议：

1. 仅对真正需要基于 cookie 区分的页面使用 Vary: cookie
2. 尽可能减少影响页面渲染的 cookie 数量
3. 监控缓存命中率和性能指标
4. 实现合适的缓存失效策略

这样的实现可以确保：

• CDN 正确缓存不同版本的页面
• 提高缓存命中率
• 减少不必要的回源请求
• 提供更好的用户体验

[arvinxx]

variant segment rewrite

如果要把这个方案做完善。现有的实现存在哪些问题需要重构的？

1. 遇到的最大的一个问题是 useSearchParams 不兼容 PreRender ，必须要包裹一个 Suspense 才可以使用。因此用到这个方法的实现可能大多估计要全部重构掉（要试下是否可以用 useQueryState 替代）；
2. 由 1 可得，用 query 来区分 mobile 布局的方案是存在天生缺陷的（PreRender 不友好，无法静态化），重点表现在 /chat 相关的移动端路由中；
3. 平行路由并不是越多越好，在 POC 过程中发现 @nav 是阻断构建的核心因素。控制台的 Error Error: Route "/chat" used `searchParams._debugInfo`. `searchParams` should be awaited before using its properties. Learn more: https://nextjs.org/docs/messages/sync-dynamic-apis 也是由于 @nav 导致（但根因还没找到，只知道移除 @nav slot 就好了）

进展

前置重构：

• 移除 @nav slot 💄 style: refactor @nav layout and improve pin list style #5533
• useMobileWorkspace nqus 替换 useQuery ♻️ refactor: useMobileWorkspace use nqus to replace useQuery #5603

[arvinxx]

相关实践问题合集

【500 类错误】

经过 discover/xx/[id] 、 provider/[id] 、 files/[id] 等多个路由检验，最终发现 500 的根因是 layout 层的 force-static。 force-static 将会阻止页面获取动态参数（ cookie、headers 等），进而导致 clerk auth 或者 next-auth auth 找不到参数，或参数为空，进而抛错。因此针对 [id] 类页面有从 sever 获取参数的场景（以及需要服务端 auth 鉴权的页面），绝对不能使用 force-static，默认采用 auto 即可。

• 🐛 fix: fix provider 500 issue #5807
• 🐛 fix: fix /file/[id] 500 issue #5812

【NextAuth 集成失效】

基本可以确认和环境变量失效是同一类问题，均由于强制静态化后丢失 cookie、headers 等导致集成失效。设定 export const dynamic = 'force-dynamic'; 可修复。

在 1.52.0 中，我们引入 NEXT_PUBLIC_ENABLE_NEXT_AUTH 构建时环境变量来解决 NextAuth 的启动逻辑， 在 Database 版本的 Docker 镜像中预设 NEXT_PUBLIC_ENABLE_NEXT_AUTH=1 来默认开启 NextAuth ，而在其他支持构建的部署环境（Vercel 等），则可以自行设定构建镜像来解决该问题。

• ✨ feat: refactor the auth condition in Next Auth #5866

【首页路由重定向不正确】

在使用 db 的 docker 镜像中，会出现 / 永久重定向 (308) 到 /zh-CN__0__light 的情况，经过排查原因是由于 nextjs 会自动将 / 后缀的路由重定向到不带后缀，即 / rewrite to /zh-CN__0__light/ ，然后 /zh-CN__0__light/ redirect to /zh-CN__0__light。因此解决方案是确保 rewrite 的路径是不带 /后缀，并强制指定status code 为 200，就可以解决。

• • ✨ feat: refactor the auth condition in Next Auth #5866

【环境变量 ( FEATURE_FLAG 等 ) 失效】

原本环境变量都通过 RSC 的 props 参数进行传递，页面静态化后，RSC 的 props 将无法动态化，因此环境变量将会全部失效。目前的临时解法是重新将页面变成动态，设定 export const dynamic = 'force-dynamic'; （ #5825 ）

最终解法是再多一个 client 端请求来获取 serverConfig：（ d4b2f36 ）。如果是 Vercel 部署场景下，还是可以通过 RSC 来获取最新的FeatureFlag，而 docker 模式下则会做一次请求后进入正确状态。

【发现页 助手详情语种不正确】

• [Bug] 添加中文AI助手后变成全英文的AI助手 #5849

【当访问 chat 路径时出现异常 404 响应】

当访问 chat 路径时出现异常 404 响应，具体表现为：

• 不携带 session 参数访问路径时：/ ➔ 出现 [Bug] 使用setup.sh域名安装后，无法跳转至登录页面 #5837 同类错误
• 不携带 session 参数访问路径时：/chat ➔ 出现 一堆404，如下图
• 携带 session 参数访问路径时：/chat?session=xxx ➔ 访问正常
• 访问非 chat 路径时（如 /settings）➔ 全部正常

部分客户端（主要集中在Chrome），部分用户出现问题。

找到问题了：宝塔面板反向代理的坑。 宝塔面板的"禁用缓存"不彻底，我直接在反向代理增加了自定义配置才能完全的禁用缓存

# 新增: 禁用Nginx所有层级的缓存
    proxy_cache off;
    proxy_buffering off;
    proxy_no_cache 1;
    proxy_cache_bypass 1;
    
    # 覆写后端返回的缓存头，强制不缓存
    add_header Cache-Control "no-cache, no-store, must-revalidate, proxy-revalidate";
    add_header Pragma "no-cache";
    add_header Expires "0";

refs: #5804 (comment)

[arvinxx]

关于 MIDDLEWARE_REWRITE_THROUGH_LOCAL 的讨论： #5876

[arvinxx]

目前拿 /chat 页面为例评估的首屏加载性能，汇总表格如下：

部署模式	v1.51.3	v1.52.9+
Vercel	2.3s	160ms
Zeabur GCP free trial	2.1s	215ms
2C8G HK 服务器部署 IP + 端口模式	3.7s	73ms
2C8G HK 服务器部署 域名 + Cloudflare 小黄云代理	3.3s	289ms

详细数据：

Vercel 部署模式

v1.51.3: 平均 2.3s

v1.52.11: 平均 160ms

Zeabur 部署模式

v1.51.3：平均 2.1s

v.1.52.9: 平均 215ms

自部署服务器

一台 2C8G ，在 HK 的服务器：

纯 IP + 端口模式访问：

v1.51.3: 平均 3.7s

v1.52.9
禁用浏览器缓存: 平均 1.9s

不禁用浏览器缓存（这是大家浏览器默认的配置）: 平均 73 ms

HTTPS 域名 + Cloudflare 小黄云代理访问：

v1.51.3：平均 3.3s

v1.52.9

禁用浏览器缓存：首次 5.2s ，后续平均 279ms ，全部平均 1.26s

不禁用浏览器缓存: 平均 289 ms

[tjx666]

一图胜千言：