From 125e3e5302ada7af28c39aa8f41b8e5a087e0708 Mon Sep 17 00:00:00 2001
From: shellRaining <shellRaining@gmail.com>
Date: Sun, 26 Jul 2026 00:51:12 +0800
Subject: [PATCH 1/3] =?UTF-8?q?fix(pwa):=20=E4=BF=AE=E5=A4=8D=E9=83=A8?=
 =?UTF-8?q?=E7=BD=B2=E5=88=87=E6=8D=A2=E5=90=8E=E7=9A=84=E6=87=92=E5=8A=A0?=
 =?UTF-8?q?=E8=BD=BD=E5=A4=B1=E8=B4=A5?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md                                     | 10 +--
 apps/docs/content/guide/getting-started.md    |  2 +-
 apps/website/build/runtime-cache.ts           | 32 ++++++++
 .../src/components/PwaStatusBanner.vue        | 71 +++++++++++++++--
 apps/website/src/components/pwa-update.ts     | 71 +++++++++++++++++
 apps/website/tests/pwa-update.test.ts         | 78 +++++++++++++++++++
 apps/website/tests/runtime-cache.test.ts      | 38 +++++++++
 apps/website/tests/vercel-routing.test.ts     | 32 ++++++++
 apps/website/vite.config.ts                   |  8 +-
 docs/exec-plans/README.md                     |  4 +-
 .../active/2026-07-26-pwa-version-skew.md     | 60 ++++++++++++++
 docs/frontend.md                              |  6 +-
 vercel.json                                   |  7 +-
 13 files changed, 398 insertions(+), 21 deletions(-)
 create mode 100644 apps/website/build/runtime-cache.ts
 create mode 100644 apps/website/src/components/pwa-update.ts
 create mode 100644 apps/website/tests/pwa-update.test.ts
 create mode 100644 apps/website/tests/runtime-cache.test.ts
 create mode 100644 apps/website/tests/vercel-routing.test.ts
 create mode 100644 docs/exec-plans/active/2026-07-26-pwa-version-skew.md

diff --git a/README.md b/README.md
index 635d9ea..c93a65a 100644
--- a/README.md
+++ b/README.md
@@ -4,12 +4,12 @@
 
 ## 开发环境
 
-| 开发者类型 | 需要自行准备 | 说明 |
-| --- | --- | --- |
-| 普通开发者 | [Vite+](https://viteplus.dev/) 的 `vp` CLI | 进入仓库后执行 `vp install`，其余项目工具由仓库管理 |
-| 真实接口验证者 | 浙江大学校园网或代理、CC98 账号 | 账号写入 `.cc98-credentials.local`；普通构建和离线测试不需要 |
+| 开发者类型         | 需要自行准备                                                | 说明                                                                      |
+| ------------------ | ----------------------------------------------------------- | ------------------------------------------------------------------------- |
+| 普通开发者         | [Vite+](https://viteplus.dev/) 的 `vp` CLI                  | 进入仓库后执行 `vp install`，其余项目工具由仓库管理                       |
+| 真实接口验证者     | 浙江大学校园网或代理、CC98 账号                             | 账号写入 `.cc98-credentials.local`；普通构建和离线测试不需要              |
 | 并行或自动化开发者 | [Worktrunk](https://worktrunk.dev/)；按需安装浏览器运行环境 | Worktrunk 用于多 worktree；浏览器环境运行 `vp exec agent-browser install` |
-| 部署维护者 | Vercel 项目权限；按需安装 Vercel CLI | 普通开发者不需要；生产域名维护还需要相应 DNS 权限 |
+| 部署维护者         | Vercel 项目权限；按需安装 Vercel CLI                        | 普通开发者不需要；生产域名维护还需要相应 DNS 权限                         |
 
 安装依赖并启动开发环境：
 
diff --git a/apps/docs/content/guide/getting-started.md b/apps/docs/content/guide/getting-started.md
index a573e58..06fa92d 100644
--- a/apps/docs/content/guide/getting-started.md
+++ b/apps/docs/content/guide/getting-started.md
@@ -12,7 +12,7 @@
 
 支持 PWA 的浏览器可以把 CC98 安装到桌面或主屏幕。安装入口通常位于地址栏或浏览器菜单中，名称可能是“安装应用”“添加到主屏幕”或“创建快捷方式”。安装后会以独立窗口打开，账号和外观设置仍由当前浏览器管理。
 
-页面提示新版本已经准备好时，点击“刷新”即可切换版本。选择“稍后”不会影响当前页面，下次发现更新时还会再次提示。
+页面提示新版本已经准备好时，点击“立即更新”即可切换版本。选择“稍后”不会影响当前页面，下次发现更新时还会再次提示。如果页面显示“当前版本已失效”，说明刚才打开的页面代码已经被新部署替换，需要更新后再继续访问。更新会重新加载当前页面，请先保存尚未提交的内容。
 
 ## 认识顶部导航
 
diff --git a/apps/website/build/runtime-cache.ts b/apps/website/build/runtime-cache.ts
new file mode 100644
index 0000000..8616cfb
--- /dev/null
+++ b/apps/website/build/runtime-cache.ts
@@ -0,0 +1,32 @@
+export function createAppAssetCachePlugin() {
+  const cacheWillUpdate = async (context: {
+    request: Request;
+    response: Response;
+  }): Promise<Response | null> => {
+    const { request, response } = context;
+    if (response.status !== 200) return null;
+
+    const contentType = response.headers.get("Content-Type")?.toLowerCase() ?? "";
+    const pathname = new URL(request.url).pathname.toLowerCase();
+
+    if (pathname.endsWith(".js")) {
+      return contentType.includes("javascript") || contentType.includes("ecmascript")
+        ? response
+        : null;
+    }
+    if (pathname.endsWith(".css")) {
+      return contentType.startsWith("text/css") ? response : null;
+    }
+    if (/\.(?:woff2?|ttf)$/.test(pathname)) {
+      return contentType.startsWith("font/") ||
+        contentType.startsWith("application/font-") ||
+        contentType.startsWith("application/x-font-") ||
+        contentType.startsWith("application/octet-stream")
+        ? response
+        : null;
+    }
+    return null;
+  };
+
+  return { cacheWillUpdate };
+}
diff --git a/apps/website/src/components/PwaStatusBanner.vue b/apps/website/src/components/PwaStatusBanner.vue
index 31a1a70..498b56c 100644
--- a/apps/website/src/components/PwaStatusBanner.vue
+++ b/apps/website/src/components/PwaStatusBanner.vue
@@ -1,25 +1,84 @@
 <script setup lang="ts">
-import { useOnline } from "@vueuse/core";
+import { useEventListener, useIntervalFn, useOnline } from "@vueuse/core";
 import { useRegisterSW } from "virtual:pwa-register/vue";
-import { ref } from "vue";
+import { computed, ref, shallowRef } from "vue";
 import { createLogger, logErrorOnce } from "../lib/logger";
+import {
+  createServiceWorkerUpdateChecker,
+  SERVICE_WORKER_UPDATE_INTERVAL,
+  waitForWaitingServiceWorker,
+} from "./pwa-update";
 import UiDialog from "./ui/Dialog.vue";
 
 const logger = createLogger("pwa");
 const isOnline = useOnline();
 const isUpdating = ref(false);
 const updateError = ref("");
+const versionExpired = ref(false);
+const registration = shallowRef<ServiceWorkerRegistration>();
+const checkForUpdate = createServiceWorkerUpdateChecker(() => registration.value);
 const { needRefresh, updateServiceWorker } = useRegisterSW({
+  onRegisteredSW(_swUrl, nextRegistration) {
+    registration.value = nextRegistration;
+  },
   onRegisterError(error) {
     logErrorOnce(logger, error, "Service Worker 注册失败");
   },
 });
 
+const promptOpen = computed({
+  get: () => needRefresh.value || versionExpired.value,
+  set: (open: boolean) => {
+    if (open) return;
+    needRefresh.value = false;
+    versionExpired.value = false;
+    updateError.value = "";
+  },
+});
+const promptTitle = computed(() => (versionExpired.value ? "当前版本已失效" : "发现新版本"));
+const promptDescription = computed(() =>
+  versionExpired.value
+    ? "页面代码已经更新，当前版本无法继续加载目标页面。立即更新会重新加载当前页面，请先保存尚未提交的内容。"
+    : "新版本已经准备好，立即更新会重新加载当前页面。请先保存尚未提交的内容。",
+);
+
+function requestUpdateCheck(force = false): void {
+  if (!navigator.onLine) return;
+  void checkForUpdate(force).catch((error: unknown) => {
+    logErrorOnce(logger, error, "Service Worker 更新检查失败");
+  });
+}
+
+useIntervalFn(() => requestUpdateCheck(), SERVICE_WORKER_UPDATE_INTERVAL);
+useEventListener(window, "online", () => requestUpdateCheck());
+useEventListener(document, "visibilitychange", () => {
+  if (document.visibilityState === "visible") requestUpdateCheck();
+});
+useEventListener(window, "vite:preloadError", (event: Event) => {
+  event.preventDefault();
+  versionExpired.value = true;
+  const error = (event as Event & { payload?: unknown }).payload ?? new Error("页面资源加载失败");
+  logErrorOnce(logger, error, "页面资源加载失败，当前版本可能已经失效");
+  requestUpdateCheck(true);
+});
+
 async function update(): Promise<void> {
   isUpdating.value = true;
   updateError.value = "";
   try {
-    await updateServiceWorker();
+    const currentRegistration = registration.value;
+    if (!currentRegistration?.waiting) {
+      await checkForUpdate(true);
+    }
+
+    if (
+      currentRegistration?.waiting ||
+      (currentRegistration && (await waitForWaitingServiceWorker(currentRegistration)))
+    ) {
+      await updateServiceWorker();
+    } else {
+      window.location.reload();
+    }
   } catch (error) {
     updateError.value = "更新失败，请稍后重试。";
     logErrorOnce(logger, error, "Service Worker 更新失败");
@@ -31,9 +90,9 @@ async function update(): Promise<void> {
 
 <template>
   <UiDialog
-    v-model:open="needRefresh"
-    title="发现新版本"
-    description="新版本已经准备好，立即更新会重新加载当前页面。请先保存尚未提交的内容。"
+    v-model:open="promptOpen"
+    :title="promptTitle"
+    :description="promptDescription"
     cancel-label="稍后"
     confirm-label="立即更新"
     :pending="isUpdating"
diff --git a/apps/website/src/components/pwa-update.ts b/apps/website/src/components/pwa-update.ts
new file mode 100644
index 0000000..b024ae0
--- /dev/null
+++ b/apps/website/src/components/pwa-update.ts
@@ -0,0 +1,71 @@
+export const SERVICE_WORKER_UPDATE_INTERVAL = 60 * 60 * 1000;
+const SERVICE_WORKER_UPDATE_THROTTLE = 5 * 60 * 1000;
+const SERVICE_WORKER_WAIT_TIMEOUT = 10_000;
+
+interface UpdateCheckerOptions {
+  now?: () => number;
+  throttle?: number;
+}
+
+export function createServiceWorkerUpdateChecker(
+  getRegistration: () => ServiceWorkerRegistration | undefined,
+  options: UpdateCheckerOptions = {},
+): (force?: boolean) => Promise<void> {
+  const now = options.now ?? Date.now;
+  const throttle = options.throttle ?? SERVICE_WORKER_UPDATE_THROTTLE;
+  let lastCheckedAt = Number.NEGATIVE_INFINITY;
+  let activeCheck: Promise<void> | undefined;
+
+  return async (force = false): Promise<void> => {
+    if (activeCheck) return activeCheck;
+
+    const registration = getRegistration();
+    if (!registration) return;
+
+    const checkedAt = now();
+    if (!force && checkedAt - lastCheckedAt < throttle) return;
+    lastCheckedAt = checkedAt;
+
+    const update = registration.update().then(() => undefined);
+    const tracked = update.finally(() => {
+      if (activeCheck === tracked) activeCheck = undefined;
+    });
+    activeCheck = tracked;
+    return tracked;
+  };
+}
+
+export async function waitForWaitingServiceWorker(
+  registration: ServiceWorkerRegistration,
+  timeout = SERVICE_WORKER_WAIT_TIMEOUT,
+): Promise<boolean> {
+  if (registration.waiting) return true;
+
+  const worker = registration.installing;
+  if (!worker) return false;
+  if (worker.state === "installed") return registration.waiting != null;
+  if (worker.state === "activated" || worker.state === "redundant") return false;
+
+  return await new Promise<boolean>((resolve) => {
+    let settled = false;
+    const timer = setTimeout(() => finish(false), timeout);
+
+    function finish(waiting: boolean): void {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      worker?.removeEventListener("statechange", handleStateChange);
+      resolve(waiting);
+    }
+
+    function handleStateChange(): void {
+      if (worker?.state === "installed") {
+        finish(registration.waiting != null);
+      } else if (worker?.state === "activated" || worker?.state === "redundant") {
+        finish(false);
+      }
+    }
+
+    worker.addEventListener("statechange", handleStateChange);
+  });
+}
diff --git a/apps/website/tests/pwa-update.test.ts b/apps/website/tests/pwa-update.test.ts
new file mode 100644
index 0000000..8f48040
--- /dev/null
+++ b/apps/website/tests/pwa-update.test.ts
@@ -0,0 +1,78 @@
+import { describe, expect, test, vi } from "vite-plus/test";
+import {
+  createServiceWorkerUpdateChecker,
+  waitForWaitingServiceWorker,
+} from "../src/components/pwa-update.ts";
+
+function registrationWithUpdate(update: () => Promise<unknown>): ServiceWorkerRegistration {
+  return { update } as unknown as ServiceWorkerRegistration;
+}
+
+describe("Service Worker 更新检查", () => {
+  test("合并并发检查并限制短时间内的重复请求", async () => {
+    let now = 1_000;
+    let finishUpdate: (() => void) | undefined;
+    let firstUpdate = true;
+    const update = vi.fn(() => {
+      if (!firstUpdate) return Promise.resolve();
+      firstUpdate = false;
+      return new Promise<void>((resolve) => {
+        finishUpdate = resolve;
+      });
+    });
+    const registration = registrationWithUpdate(update);
+    const check = createServiceWorkerUpdateChecker(() => registration, {
+      now: () => now,
+      throttle: 500,
+    });
+
+    const first = check();
+    const concurrent = check();
+    expect(update).toHaveBeenCalledTimes(1);
+    finishUpdate?.();
+    await Promise.all([first, concurrent]);
+
+    now = 1_200;
+    await check();
+    expect(update).toHaveBeenCalledTimes(1);
+
+    await check(true);
+    expect(update).toHaveBeenCalledTimes(2);
+
+    now = 1_700;
+    await check();
+    expect(update).toHaveBeenCalledTimes(3);
+  });
+
+  test("注册尚未完成时跳过检查", async () => {
+    const check = createServiceWorkerUpdateChecker(() => undefined);
+    await expect(check()).resolves.toBeUndefined();
+  });
+});
+
+describe("等待新 Service Worker", () => {
+  test("安装完成并进入 waiting 后返回 true", async () => {
+    const worker = new EventTarget() as EventTarget & { state: ServiceWorkerState };
+    worker.state = "installing";
+    const registration = {
+      installing: worker,
+      waiting: null,
+    } as unknown as ServiceWorkerRegistration;
+
+    const waiting = waitForWaitingServiceWorker(registration, 100);
+    Object.assign(registration, { waiting: worker });
+    worker.state = "installed";
+    worker.dispatchEvent(new Event("statechange"));
+
+    await expect(waiting).resolves.toBe(true);
+  });
+
+  test("没有正在安装的 Worker 时不等待", async () => {
+    const registration = {
+      installing: null,
+      waiting: null,
+    } as unknown as ServiceWorkerRegistration;
+
+    await expect(waitForWaitingServiceWorker(registration, 100)).resolves.toBe(false);
+  });
+});
diff --git a/apps/website/tests/runtime-cache.test.ts b/apps/website/tests/runtime-cache.test.ts
new file mode 100644
index 0000000..2d47cff
--- /dev/null
+++ b/apps/website/tests/runtime-cache.test.ts
@@ -0,0 +1,38 @@
+import { describe, expect, test } from "vite-plus/test";
+import { createAppAssetCachePlugin } from "../build/runtime-cache.ts";
+
+const plugin = createAppAssetCachePlugin();
+
+async function cacheable(url: string, contentType: string, status = 200): Promise<boolean> {
+  const response = new Response("content", {
+    headers: { "Content-Type": contentType },
+    status,
+  });
+  return (await plugin.cacheWillUpdate({ request: new Request(url), response })) === response;
+}
+
+describe("应用资源运行时缓存", () => {
+  test("只缓存类型正确的脚本和样式", async () => {
+    await expect(
+      cacheable("https://example.com/assets/page-123.js", "application/javascript"),
+    ).resolves.toBe(true);
+    await expect(cacheable("https://example.com/assets/page-123.js", "text/html")).resolves.toBe(
+      false,
+    );
+    await expect(
+      cacheable("https://example.com/assets/page-123.css", "text/css; charset=utf-8"),
+    ).resolves.toBe(true);
+  });
+
+  test("拒绝错误响应并接受常见字体类型", async () => {
+    await expect(
+      cacheable("https://example.com/assets/page-123.js", "application/javascript", 404),
+    ).resolves.toBe(false);
+    await expect(
+      cacheable("https://example.com/assets/font-123.woff2", "font/woff2"),
+    ).resolves.toBe(true);
+    await expect(
+      cacheable("https://example.com/assets/font-123.ttf", "application/octet-stream"),
+    ).resolves.toBe(true);
+  });
+});
diff --git a/apps/website/tests/vercel-routing.test.ts b/apps/website/tests/vercel-routing.test.ts
new file mode 100644
index 0000000..c90f598
--- /dev/null
+++ b/apps/website/tests/vercel-routing.test.ts
@@ -0,0 +1,32 @@
+import { readFileSync } from "node:fs";
+import { describe, expect, test } from "vite-plus/test";
+
+interface VercelConfig {
+  rewrites: Array<{ source: string; destination: string }>;
+}
+
+const config = JSON.parse(
+  readFileSync(new URL("../../../vercel.json", import.meta.url), "utf8"),
+) as VercelConfig;
+const spaRewrite = config.rewrites.find((rewrite) => rewrite.destination === "/index.html");
+
+function matchesSpaRewrite(path: string): boolean {
+  if (!spaRewrite) return false;
+  return new RegExp(`^${spaRewrite.source}$`).test(path);
+}
+
+describe("Vercel SPA 回退", () => {
+  test("业务路由回退到首页", () => {
+    expect(matchesSpaRewrite("/topic/123")).toBe(true);
+    expect(matchesSpaRewrite("/user/name/user.with.dot")).toBe(true);
+  });
+
+  test("静态资源和 PWA 文件不参与首页回退", () => {
+    expect(matchesSpaRewrite("/assets/TopicView-old.js")).toBe(false);
+    expect(matchesSpaRewrite("/sw.js")).toBe(false);
+    expect(matchesSpaRewrite("/manifest.webmanifest")).toBe(false);
+    expect(matchesSpaRewrite("/pwa-192x192.png")).toBe(false);
+    expect(matchesSpaRewrite("/apple-touch-icon.png")).toBe(false);
+    expect(matchesSpaRewrite("/favicon.ico")).toBe(false);
+  });
+});
diff --git a/apps/website/vite.config.ts b/apps/website/vite.config.ts
index cdafbb4..158c8d7 100644
--- a/apps/website/vite.config.ts
+++ b/apps/website/vite.config.ts
@@ -3,6 +3,7 @@ import vue from "@vitejs/plugin-vue";
 import UnoCSS from "unocss/vite";
 import { VitePWA } from "vite-plugin-pwa";
 import { appShellPlugin } from "./build/app-shell.js";
+import { createAppAssetCachePlugin } from "./build/runtime-cache.js";
 
 const pwaPlugins = VitePWA({
   injectRegister: "auto",
@@ -46,11 +47,10 @@ const pwaPlugins = VitePWA({
     runtimeCaching: [
       {
         urlPattern: /\/assets\/[^?]+\.(?:js|css|woff2?|ttf)$/,
-        handler: "NetworkFirst",
+        handler: "CacheFirst",
         options: {
-          cacheName: "app-assets-v1",
-          cacheableResponse: { statuses: [200] },
-          networkTimeoutSeconds: 3,
+          cacheName: "app-assets-v2",
+          plugins: [createAppAssetCachePlugin()],
           expiration: {
             maxEntries: 160,
             purgeOnQuotaError: true,
diff --git a/docs/exec-plans/README.md b/docs/exec-plans/README.md
index 7483d4c..a4e1720 100644
--- a/docs/exec-plans/README.md
+++ b/docs/exec-plans/README.md
@@ -27,7 +27,9 @@
 
 ## 进行中的计划
 
-当前没有进行中的计划。
+| 执行计划                                | 说明                                                   |
+| --------------------------------------- | ------------------------------------------------------ |
+| `active/2026-07-26-pwa-version-skew.md` | 修复部署切换后的懒加载失败、更新检查和静态资源错误缓存 |
 
 ## 已完成的计划
 
diff --git a/docs/exec-plans/active/2026-07-26-pwa-version-skew.md b/docs/exec-plans/active/2026-07-26-pwa-version-skew.md
new file mode 100644
index 0000000..20a6541
--- /dev/null
+++ b/docs/exec-plans/active/2026-07-26-pwa-version-skew.md
@@ -0,0 +1,60 @@
+# 修复 PWA 部署后的版本漂移
+
+## 背景
+
+网站使用路由懒加载和带内容哈希的构建产物。生产部署切换后，旧标签页仍会按上一版入口代码请求懒加载资源。当前 Vercel 配置把缺失的 `/assets/*` 请求改写成 `index.html`，响应同时继承静态资源的一年期缓存头。浏览器会收到 `200 text/html`，Service Worker 也可能把这份响应写入脚本缓存，最终由 Vue Router 记录为路由异常。
+
+Service Worker 通过 `useRegisterSW` 在页面加载时注册。应用没有主动调用 `ServiceWorkerRegistration.update()`，长时间打开的标签页通常要等到刷新或浏览器自行检查后才会显示更新提示。
+
+## 目标
+
+- 缺失的静态资源返回错误响应，不再回退到 `index.html`。
+- 已访问的带哈希脚本、样式和字体在新部署后仍可从 Cache Storage 使用。
+- 页面重新可见、恢复联网和持续打开期间主动检查 Service Worker 更新。
+- 懒加载资源失效时显示更新提示，避免页面只留下路由异常。
+- 保留用户确认后再刷新页面的更新流程。
+
+## 非目标
+
+- 不预缓存全部路由资源。
+- 不接入 Vercel Skew Protection 或自行改写构建资源 URL。
+- 不改变 API、图片和第三方媒体的缓存边界。
+- 不自动刷新正在编辑内容的页面。
+
+## 方案
+
+Vercel 的 SPA 回退明确排除 `/assets/*`、Service Worker、Manifest 和固定 PWA 文件。业务路由仍返回 `index.html`，缺失静态文件交给 Vercel 返回 404。
+
+脚本、样式和字体已经带内容哈希，运行时缓存改用 `CacheFirst`。缓存写入同时检查状态码和响应类型，HTML、错误页与类型不匹配的响应不能进入缓存。使用新的缓存名，避免复用已经可能被污染的条目。
+
+PWA 状态组件保存注册结果，通过一个带并发合并和最小检查间隔的更新检查器调用 `registration.update()`。检查由页面重新可见、网络恢复和一小时定时器触发。Vite 的 `vite:preloadError` 会阻止未处理异常，标记当前版本已经失效，并立即检查 Service Worker。用户确认更新时等待新 Worker 进入 waiting 状态；没有可激活的新 Worker 时再回退到普通页面刷新。
+
+## 实施步骤
+
+- [x] 修正 Vercel SPA 回退范围，补配置契约测试。
+- [x] 调整带哈希资源的运行时缓存策略和响应校验。
+- [x] 加入主动更新检查与懒加载失败处理。
+- [x] 补并发、节流、Worker 等待和缓存响应的回归测试。
+- [x] 同步前端缓存规范和执行计划索引。
+- [ ] 运行全量检查、生产构建和浏览器更新场景验证。
+
+## 验证
+
+- `vp run ready` 全量通过。
+- 构建后的 `sw.js` 使用新的 `CacheFirst` 资源缓存，并包含状态码和 Content-Type 校验。
+- 业务深层路由仍能加载，缺失 `/assets/*.js` 不返回 `index.html`。
+- 模拟 `vite:preloadError` 后出现版本失效提示，确认更新只刷新一次。
+- 页面重新可见和恢复联网时会触发更新检查，短时间重复事件不会并发请求。
+
+## 进展与调整
+
+- 2026-07-26：从远端 `main` 创建 `fix/pwa-version-skew` worktree。主 worktree 有用户未提交修改，本任务没有读取或覆盖这些修改。
+- 2026-07-26：实现 Vercel 路由排除、`CacheFirst` 资源缓存、响应类型校验、主动更新检查和预加载失败提示，新增 8 项回归测试。
+- 2026-07-26：`vp run ready` 全量通过。生产预览中首页、页面切换和深层路由刷新正常；模拟 `vite:preloadError` 后能显示版本失效提示，“稍后”和“立即更新”行为符合预期。
+- 2026-07-26：本地 Vite Preview 会自行把缺失资源回退到 `index.html`，不能验证 Vercel 路由。创建 PR 后需在 Vercel Preview 确认缺失 `/assets/*.js` 返回 404 且不是 HTML，再完成计划归档。
+
+## 决策记录
+
+- 不依赖 Service Worker 内部定时器。Worker 会被浏览器挂起，更新检查由受控页面发起。
+- 不自动刷新 chunk 加载失败的页面。论坛存在发帖和编辑流程，刷新继续由用户确认。
+- 继续按需缓存访问过的路由，不扩大安装时预缓存范围。
diff --git a/docs/frontend.md b/docs/frontend.md
index f5fdbac..8ed8b69 100644
--- a/docs/frontend.md
+++ b/docs/frontend.md
@@ -29,15 +29,15 @@
 
 ### 静态资源缓存
 
-生产环境的 `/assets/*` 均带内容指纹，使用一年期 `immutable` HTTP 缓存；`index.html`、Service Worker 和注册脚本必须保持可重新验证。修改缓存头时不能把无内容指纹的站点根文件一并设为长期缓存。
+生产环境的 `/assets/*` 均带内容指纹，使用一年期 `immutable` HTTP 缓存；`index.html`、Service Worker 和注册脚本必须保持可重新验证。Vercel 的 SPA 回退只处理业务路由，静态资源、Service Worker、Manifest 和固定 PWA 文件必须保留真实的错误响应，不能用 `index.html` 代替。
 
 Service Worker 只预缓存首页 App Shell，包括全局入口、首页路由依赖、Web App Manifest 和少量界面图片。构建插件从 Rollup 的网站入口和 `HomeView` 动态入口递归收集静态依赖、关联样式和首页直接引用的图片，拆包结果变化后不需要维护文件名通配规则。其他路由的懒加载 chunk、皮肤横幅和卡片预览图不进入预缓存。
 
-访问其他路由后，其带内容指纹的脚本、样式和字体写入有条目上限的运行时缓存，离线时可以再次启动这些页面的代码。正式横幅和皮肤雪球君按访问写入各自的 Cache Storage，使用内容哈希更新并限制条目数量；缓存条件同时检查 `200` 状态和图片内容类型，避免 SPA 回退响应被误存成图片。
+访问其他路由后，其带内容指纹的脚本、样式和字体通过 `CacheFirst` 写入有条目上限的运行时缓存，离线或新部署切换后仍可使用已经访问过的页面代码。缓存写入同时检查 `200` 状态和资源类型，HTML 与错误响应不能存到脚本、样式或字体 URL。正式横幅和皮肤雪球君按访问写入各自的 Cache Storage，使用内容哈希更新并限制条目数量。
 
 应用外壳只保证页面代码和首页界面能启动，不缓存 API 响应、头像、帖子图片、附件或第三方媒体。离线状态下，已访问路由可以打开页面代码，但依赖服务端的数据继续进入现有错误状态。未访问过的路由不承诺首次离线打开。
 
-网站通过 Web App Manifest 提供名称、启动地址、独立窗口显示模式和安装图标。Service Worker 注册代码随应用入口打包，不单独生成 `registerSW.js`。发现新 Worker 进入等待状态后，页面显示更新提示，用户确认刷新时才切换版本。
+网站通过 Web App Manifest 提供名称、启动地址、独立窗口显示模式和安装图标。Service Worker 注册代码随应用入口打包，不单独生成 `registerSW.js`。页面重新可见、恢复联网和持续打开期间会主动检查更新，检查需要合并并发请求并限制频率。发现新 Worker 进入等待状态后，页面显示更新提示，用户确认刷新时才切换版本。懒加载资源因部署切换而失效时，Vite 的预加载错误也进入同一提示流程，不自动刷新正在编辑内容的页面。
 
 Cache Storage 负责请求与响应形式的静态资源。localStorage 不保存 Base64 图片，IndexedDB 留给草稿、待同步操作等结构化业务数据。扩展离线能力前先检查生成的预缓存清单和安装流量，不把 API 响应直接纳入 App Shell。
 
diff --git a/vercel.json b/vercel.json
index d51c38e..1c129b6 100644
--- a/vercel.json
+++ b/vercel.json
@@ -42,5 +42,10 @@
       ]
     }
   ],
-  "rewrites": [{ "source": "/(.*)", "destination": "/index.html" }]
+  "rewrites": [
+    {
+      "source": "/((?!assets/|sw\\.js$|manifest\\.webmanifest$|pwa-[^/]+\\.png$|apple-touch-icon\\.png$|favicon\\.ico$).*)",
+      "destination": "/index.html"
+    }
+  ]
 }

From 6b8deadf65ee00f4c2da1e0607c7d2edb7fe65b3 Mon Sep 17 00:00:00 2001
From: shellRaining <shellRaining@gmail.com>
Date: Sun, 26 Jul 2026 00:59:52 +0800
Subject: [PATCH 2/3] =?UTF-8?q?docs:=20=E5=BD=92=E6=A1=A3=20PWA=20?=
 =?UTF-8?q?=E7=89=88=E6=9C=AC=E6=BC=82=E7=A7=BB=E4=BF=AE=E5=A4=8D=E8=AE=A1?=
 =?UTF-8?q?=E5=88=92?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/exec-plans/README.md                     |  5 ++--
 .../2026-07-26-pwa-version-skew.md            | 23 ++++++++++++++-----
 2 files changed, 19 insertions(+), 9 deletions(-)
 rename docs/exec-plans/{active => completed}/2026-07-26-pwa-version-skew.md (71%)

diff --git a/docs/exec-plans/README.md b/docs/exec-plans/README.md
index a4e1720..774e7b0 100644
--- a/docs/exec-plans/README.md
+++ b/docs/exec-plans/README.md
@@ -27,14 +27,13 @@
 
 ## 进行中的计划
 
-| 执行计划                                | 说明                                                   |
-| --------------------------------------- | ------------------------------------------------------ |
-| `active/2026-07-26-pwa-version-skew.md` | 修复部署切换后的懒加载失败、更新检查和静态资源错误缓存 |
+当前没有进行中的计划。
 
 ## 已完成的计划
 
 | 执行计划                                                            | 说明                                                   |
 | ------------------------------------------------------------------- | ------------------------------------------------------ |
+| `completed/2026-07-26-pwa-version-skew.md`                          | 部署切换后的懒加载失败、主动更新检查和错误缓存修复完成 |
 | `completed/2026-07-25-color-token-audit.md`                         | 全站颜色字面量迁移、自动检查和亮暗模式回归已完成       |
 | `completed/2026-07-25-installable-pwa.md`                           | 可安装 PWA、可靠首页应用外壳和访问后路由缓存已完成     |
 | `completed/2026-07-24-seasonal-dark-themes.md`                      | 春季、夏季和秋季暗色调色板与视觉回归已完成             |
diff --git a/docs/exec-plans/active/2026-07-26-pwa-version-skew.md b/docs/exec-plans/completed/2026-07-26-pwa-version-skew.md
similarity index 71%
rename from docs/exec-plans/active/2026-07-26-pwa-version-skew.md
rename to docs/exec-plans/completed/2026-07-26-pwa-version-skew.md
index 20a6541..11c1aae 100644
--- a/docs/exec-plans/active/2026-07-26-pwa-version-skew.md
+++ b/docs/exec-plans/completed/2026-07-26-pwa-version-skew.md
@@ -36,22 +36,33 @@ PWA 状态组件保存注册结果，通过一个带并发合并和最小检查
 - [x] 加入主动更新检查与懒加载失败处理。
 - [x] 补并发、节流、Worker 等待和缓存响应的回归测试。
 - [x] 同步前端缓存规范和执行计划索引。
-- [ ] 运行全量检查、生产构建和浏览器更新场景验证。
+- [x] 运行全量检查、生产构建和浏览器更新场景验证。
 
 ## 验证
 
-- `vp run ready` 全量通过。
+- `vp run ready` 全量通过，网站 34 个测试文件共 299 项测试通过。
 - 构建后的 `sw.js` 使用新的 `CacheFirst` 资源缓存，并包含状态码和 Content-Type 校验。
-- 业务深层路由仍能加载，缺失 `/assets/*.js` 不返回 `index.html`。
-- 模拟 `vite:preloadError` 后出现版本失效提示，确认更新只刷新一次。
-- 页面重新可见和恢复联网时会触发更新检查，短时间重复事件不会并发请求。
+- 本地生产预览的首页、页面切换和深层路由刷新正常。
+- 模拟 `vite:preloadError` 后出现版本失效提示，“稍后”关闭提示，“立即更新”只触发一次重新加载。
+- Vercel Preview 中缺失 `/assets/definitely-missing-version.js` 返回 `404 text/plain`，业务深层路由返回 `200 text/html`，`sw.js` 返回 `200 application/javascript` 并保持 `max-age=0, must-revalidate`。
+- 更新检查器的回归测试覆盖并发合并、节流、强制检查和 Worker 等待状态。
 
 ## 进展与调整
 
 - 2026-07-26：从远端 `main` 创建 `fix/pwa-version-skew` worktree。主 worktree 有用户未提交修改，本任务没有读取或覆盖这些修改。
 - 2026-07-26：实现 Vercel 路由排除、`CacheFirst` 资源缓存、响应类型校验、主动更新检查和预加载失败提示，新增 8 项回归测试。
 - 2026-07-26：`vp run ready` 全量通过。生产预览中首页、页面切换和深层路由刷新正常；模拟 `vite:preloadError` 后能显示版本失效提示，“稍后”和“立即更新”行为符合预期。
-- 2026-07-26：本地 Vite Preview 会自行把缺失资源回退到 `index.html`，不能验证 Vercel 路由。创建 PR 后需在 Vercel Preview 确认缺失 `/assets/*.js` 返回 404 且不是 HTML，再完成计划归档。
+- 2026-07-26：本地 Vite Preview 会自行把缺失资源回退到 `index.html`，因此在 PR #44 的 Vercel Preview 完成最终路由验收。缺失脚本返回 404 且不是 HTML，业务路由和 Service Worker 响应正常。
+
+## 结果
+
+部署切换后，已经访问过的带哈希资源可以继续从 Cache Storage 使用。未访问资源已经被新部署移除时，Vercel 不再用首页 HTML 冒充脚本响应，页面会显示明确的版本失效提示。长时间打开的标签页也会在重新可见、恢复联网和每小时定时检查时主动发现更新。
+
+根目录 `README.md` 的表格变化来自 `vp check --fix` 对主分支近期内容的格式化，没有改变文意。
+
+## 遗留项
+
+当前没有影响本计划交付的遗留项。Vercel Skew Protection 仍属于独立的可选增强，不纳入本次修复。
 
 ## 决策记录
 

From 23909663e3f4afc00f33decf5dc2f3ec5112aa71 Mon Sep 17 00:00:00 2001
From: shellRaining <shellRaining@gmail.com>
Date: Sun, 26 Jul 2026 11:13:25 +0800
Subject: [PATCH 3/3] =?UTF-8?q?fix(pwa):=20=E4=BF=AE=E6=AD=A3=E8=B5=84?=
 =?UTF-8?q?=E6=BA=90=E5=8A=A0=E8=BD=BD=E5=A4=B1=E8=B4=A5=E8=BE=B9=E7=95=8C?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md                                     |  2 +-
 apps/docs/content/guide/getting-started.md    |  2 +-
 apps/website/build/runtime-cache.ts           | 65 +++++++++++--------
 .../src/components/PwaStatusBanner.vue        | 24 ++++---
 apps/website/tests/runtime-cache.test.ts      | 34 ++++++++++
 apps/website/vite.config.ts                   |  2 +-
 .../completed/2026-07-26-pwa-version-skew.md  | 15 +++--
 docs/frontend.md                              |  4 +-
 8 files changed, 100 insertions(+), 48 deletions(-)

diff --git a/README.md b/README.md
index c93a65a..5e500f0 100644
--- a/README.md
+++ b/README.md
@@ -52,7 +52,7 @@ vp run ready   # format + lint + typecheck + test + build
 
 ## 测试部署
 
-测试站部署在 Vercel，项目根目录保持为仓库根目录。Vercel 会按 `vercel.json` 构建主站及其传递依赖，并发布 `apps/website/dist`。主站源码、静态资源、API 契约源码、UBB 或相关构建配置发生变化时才会部署；测试、探测数据、生成文档和 README 等非构建输入不会触发主站部署。Vue Router 使用 history 模式，所有未命中静态文件的请求都会回退到 `index.html`。
+测试站部署在 Vercel，项目根目录保持为仓库根目录。Vercel 会按 `vercel.json` 构建主站及其传递依赖，并发布 `apps/website/dist`。主站源码、静态资源、API 契约源码、UBB 或相关构建配置发生变化时才会部署；测试、探测数据、生成文档和 README 等非构建输入不会触发主站部署。Vue Router 使用 history 模式，只有业务路由未命中时回退到 `index.html`；缺失静态资源、Service Worker、Manifest 和固定 PWA 文件保留真实错误响应。
 
 用户文档使用独立的 Vercel 项目 `cc98-docs`，根目录是 `apps/docs`。只有文档内容、文档站配置、静态资源或相关依赖发生变化时才部署文档站。PR 会生成文档预览，`main` 分支发布到 `https://cc98-docs.vercel.app`。
 
diff --git a/apps/docs/content/guide/getting-started.md b/apps/docs/content/guide/getting-started.md
index 06fa92d..18e42bf 100644
--- a/apps/docs/content/guide/getting-started.md
+++ b/apps/docs/content/guide/getting-started.md
@@ -12,7 +12,7 @@
 
 支持 PWA 的浏览器可以把 CC98 安装到桌面或主屏幕。安装入口通常位于地址栏或浏览器菜单中，名称可能是“安装应用”“添加到主屏幕”或“创建快捷方式”。安装后会以独立窗口打开，账号和外观设置仍由当前浏览器管理。
 
-页面提示新版本已经准备好时，点击“立即更新”即可切换版本。选择“稍后”不会影响当前页面，下次发现更新时还会再次提示。如果页面显示“当前版本已失效”，说明刚才打开的页面代码已经被新部署替换，需要更新后再继续访问。更新会重新加载当前页面，请先保存尚未提交的内容。
+页面提示新版本已经准备好时，点击“立即更新”即可切换版本。选择“稍后”不会影响当前页面，下次发现更新时还会再次提示。如果页面显示“页面资源加载失败”，说明目标页面所需资源没有加载成功，可能是网络波动或网站刚刚更新。联网后点击“重新加载”即可重试。重新加载前，请先保存尚未提交的内容。
 
 ## 认识顶部导航
 
diff --git a/apps/website/build/runtime-cache.ts b/apps/website/build/runtime-cache.ts
index 8616cfb..b84fe03 100644
--- a/apps/website/build/runtime-cache.ts
+++ b/apps/website/build/runtime-cache.ts
@@ -1,32 +1,45 @@
+interface AppAssetResponseContext {
+  request: Request;
+  response: Response;
+}
+
+function validateAppAssetResponse({ request, response }: AppAssetResponseContext): Response | null {
+  if (response.status !== 200) return null;
+
+  const contentType = response.headers.get("Content-Type")?.toLowerCase() ?? "";
+  const pathname = new URL(request.url).pathname.toLowerCase();
+
+  if (pathname.endsWith(".js")) {
+    return contentType.includes("javascript") || contentType.includes("ecmascript")
+      ? response
+      : null;
+  }
+  if (pathname.endsWith(".css")) {
+    return contentType.startsWith("text/css") ? response : null;
+  }
+  if (/\.(?:woff2?|ttf)$/.test(pathname)) {
+    return contentType.startsWith("font/") ||
+      contentType.startsWith("application/font-") ||
+      contentType.startsWith("application/x-font-") ||
+      contentType.startsWith("application/octet-stream")
+      ? response
+      : null;
+  }
+  return null;
+}
+
 export function createAppAssetCachePlugin() {
-  const cacheWillUpdate = async (context: {
+  const cacheWillUpdate = async (context: AppAssetResponseContext): Promise<Response | null> =>
+    validateAppAssetResponse(context);
+
+  const cachedResponseWillBeUsed = async (context: {
     request: Request;
-    response: Response;
+    cachedResponse?: Response;
   }): Promise<Response | null> => {
-    const { request, response } = context;
-    if (response.status !== 200) return null;
-
-    const contentType = response.headers.get("Content-Type")?.toLowerCase() ?? "";
-    const pathname = new URL(request.url).pathname.toLowerCase();
-
-    if (pathname.endsWith(".js")) {
-      return contentType.includes("javascript") || contentType.includes("ecmascript")
-        ? response
-        : null;
-    }
-    if (pathname.endsWith(".css")) {
-      return contentType.startsWith("text/css") ? response : null;
-    }
-    if (/\.(?:woff2?|ttf)$/.test(pathname)) {
-      return contentType.startsWith("font/") ||
-        contentType.startsWith("application/font-") ||
-        contentType.startsWith("application/x-font-") ||
-        contentType.startsWith("application/octet-stream")
-        ? response
-        : null;
-    }
-    return null;
+    const { request, cachedResponse } = context;
+    if (!cachedResponse) return null;
+    return validateAppAssetResponse({ request, response: cachedResponse });
   };
 
-  return { cacheWillUpdate };
+  return { cacheWillUpdate, cachedResponseWillBeUsed };
 }
diff --git a/apps/website/src/components/PwaStatusBanner.vue b/apps/website/src/components/PwaStatusBanner.vue
index 498b56c..91b052c 100644
--- a/apps/website/src/components/PwaStatusBanner.vue
+++ b/apps/website/src/components/PwaStatusBanner.vue
@@ -14,7 +14,7 @@ const logger = createLogger("pwa");
 const isOnline = useOnline();
 const isUpdating = ref(false);
 const updateError = ref("");
-const versionExpired = ref(false);
+const preloadFailed = ref(false);
 const registration = shallowRef<ServiceWorkerRegistration>();
 const checkForUpdate = createServiceWorkerUpdateChecker(() => registration.value);
 const { needRefresh, updateServiceWorker } = useRegisterSW({
@@ -27,20 +27,21 @@ const { needRefresh, updateServiceWorker } = useRegisterSW({
 });
 
 const promptOpen = computed({
-  get: () => needRefresh.value || versionExpired.value,
+  get: () => needRefresh.value || preloadFailed.value,
   set: (open: boolean) => {
     if (open) return;
     needRefresh.value = false;
-    versionExpired.value = false;
+    preloadFailed.value = false;
     updateError.value = "";
   },
 });
-const promptTitle = computed(() => (versionExpired.value ? "当前版本已失效" : "发现新版本"));
+const promptTitle = computed(() => (preloadFailed.value ? "页面资源加载失败" : "发现新版本"));
 const promptDescription = computed(() =>
-  versionExpired.value
-    ? "页面代码已经更新，当前版本无法继续加载目标页面。立即更新会重新加载当前页面，请先保存尚未提交的内容。"
+  preloadFailed.value
+    ? "目标页面所需资源未能加载，可能是网络波动或网站刚刚更新。重新加载当前页面后可以重试，请先保存尚未提交的内容。"
     : "新版本已经准备好，立即更新会重新加载当前页面。请先保存尚未提交的内容。",
 );
+const confirmLabel = computed(() => (preloadFailed.value ? "重新加载" : "立即更新"));
 
 function requestUpdateCheck(force = false): void {
   if (!navigator.onLine) return;
@@ -55,10 +56,11 @@ useEventListener(document, "visibilitychange", () => {
   if (document.visibilityState === "visible") requestUpdateCheck();
 });
 useEventListener(window, "vite:preloadError", (event: Event) => {
+  if (!navigator.onLine) return;
   event.preventDefault();
-  versionExpired.value = true;
+  preloadFailed.value = true;
   const error = (event as Event & { payload?: unknown }).payload ?? new Error("页面资源加载失败");
-  logErrorOnce(logger, error, "页面资源加载失败，当前版本可能已经失效");
+  logErrorOnce(logger, error, "页面资源加载失败");
   requestUpdateCheck(true);
 });
 
@@ -80,7 +82,9 @@ async function update(): Promise<void> {
       window.location.reload();
     }
   } catch (error) {
-    updateError.value = "更新失败，请稍后重试。";
+    updateError.value = preloadFailed.value
+      ? "重新加载失败，请稍后重试。"
+      : "更新失败，请稍后重试。";
     logErrorOnce(logger, error, "Service Worker 更新失败");
   } finally {
     isUpdating.value = false;
@@ -94,7 +98,7 @@ async function update(): Promise<void> {
     :title="promptTitle"
     :description="promptDescription"
     cancel-label="稍后"
-    confirm-label="立即更新"
+    :confirm-label="confirmLabel"
     :pending="isUpdating"
     @confirm="update"
   >
diff --git a/apps/website/tests/runtime-cache.test.ts b/apps/website/tests/runtime-cache.test.ts
index 2d47cff..0be2448 100644
--- a/apps/website/tests/runtime-cache.test.ts
+++ b/apps/website/tests/runtime-cache.test.ts
@@ -11,6 +11,19 @@ async function cacheable(url: string, contentType: string, status = 200): Promis
   return (await plugin.cacheWillUpdate({ request: new Request(url), response })) === response;
 }
 
+async function reusable(url: string, contentType: string, status = 200): Promise<boolean> {
+  const cachedResponse = new Response("content", {
+    headers: { "Content-Type": contentType },
+    status,
+  });
+  return (
+    (await plugin.cachedResponseWillBeUsed({
+      request: new Request(url),
+      cachedResponse,
+    })) === cachedResponse
+  );
+}
+
 describe("应用资源运行时缓存", () => {
   test("只缓存类型正确的脚本和样式", async () => {
     await expect(
@@ -35,4 +48,25 @@ describe("应用资源运行时缓存", () => {
       cacheable("https://example.com/assets/font-123.ttf", "application/octet-stream"),
     ).resolves.toBe(true);
   });
+
+  test("复用类型正确的脚本和样式缓存", async () => {
+    await expect(
+      reusable("https://example.com/assets/page-123.js", "application/javascript"),
+    ).resolves.toBe(true);
+    await expect(
+      reusable("https://example.com/assets/page-123.css", "text/css; charset=utf-8"),
+    ).resolves.toBe(true);
+  });
+
+  test("拒绝被 HTML 污染的缓存响应", async () => {
+    await expect(reusable("https://example.com/assets/page-123.js", "text/html")).resolves.toBe(
+      false,
+    );
+  });
+
+  test("拒绝错误状态的缓存响应", async () => {
+    await expect(
+      reusable("https://example.com/assets/page-123.js", "application/javascript", 404),
+    ).resolves.toBe(false);
+  });
 });
diff --git a/apps/website/vite.config.ts b/apps/website/vite.config.ts
index 158c8d7..26682dc 100644
--- a/apps/website/vite.config.ts
+++ b/apps/website/vite.config.ts
@@ -49,7 +49,7 @@ const pwaPlugins = VitePWA({
         urlPattern: /\/assets\/[^?]+\.(?:js|css|woff2?|ttf)$/,
         handler: "CacheFirst",
         options: {
-          cacheName: "app-assets-v2",
+          cacheName: "app-assets-v1",
           plugins: [createAppAssetCachePlugin()],
           expiration: {
             maxEntries: 160,
diff --git a/docs/exec-plans/completed/2026-07-26-pwa-version-skew.md b/docs/exec-plans/completed/2026-07-26-pwa-version-skew.md
index 11c1aae..5cbc527 100644
--- a/docs/exec-plans/completed/2026-07-26-pwa-version-skew.md
+++ b/docs/exec-plans/completed/2026-07-26-pwa-version-skew.md
@@ -11,7 +11,7 @@ Service Worker 通过 `useRegisterSW` 在页面加载时注册。应用没有主
 - 缺失的静态资源返回错误响应，不再回退到 `index.html`。
 - 已访问的带哈希脚本、样式和字体在新部署后仍可从 Cache Storage 使用。
 - 页面重新可见、恢复联网和持续打开期间主动检查 Service Worker 更新。
-- 懒加载资源失效时显示更新提示，避免页面只留下路由异常。
+- 联网时，懒加载资源失败会显示重新加载提示，避免页面只留下路由异常。
 - 保留用户确认后再刷新页面的更新流程。
 
 ## 非目标
@@ -25,9 +25,9 @@ Service Worker 通过 `useRegisterSW` 在页面加载时注册。应用没有主
 
 Vercel 的 SPA 回退明确排除 `/assets/*`、Service Worker、Manifest 和固定 PWA 文件。业务路由仍返回 `index.html`，缺失静态文件交给 Vercel 返回 404。
 
-脚本、样式和字体已经带内容哈希，运行时缓存改用 `CacheFirst`。缓存写入同时检查状态码和响应类型，HTML、错误页与类型不匹配的响应不能进入缓存。使用新的缓存名，避免复用已经可能被污染的条目。
+脚本、样式和字体已经带内容哈希，运行时缓存改用 `CacheFirst`。缓存写入和读取复用同一套状态码与响应类型校验，HTML、错误页与类型不匹配的响应不能进入缓存，也不能作为命中结果使用。继续复用原缓存名，不合规的旧条目会被视为未命中，再由有效网络响应替换。
 
-PWA 状态组件保存注册结果，通过一个带并发合并和最小检查间隔的更新检查器调用 `registration.update()`。检查由页面重新可见、网络恢复和一小时定时器触发。Vite 的 `vite:preloadError` 会阻止未处理异常，标记当前版本已经失效，并立即检查 Service Worker。用户确认更新时等待新 Worker 进入 waiting 状态；没有可激活的新 Worker 时再回退到普通页面刷新。
+PWA 状态组件保存注册结果，通过一个带并发合并和最小检查间隔的更新检查器调用 `registration.update()`。检查由页面重新可见、网络恢复和一小时定时器触发。联网时，Vite 的 `vite:preloadError` 会阻止未处理异常，显示中性的资源加载失败提示并立即检查 Service Worker；离线时不接管异常，保留离线提示和路由错误处理。用户确认更新时等待新 Worker 进入 waiting 状态；没有可激活的新 Worker 时再回退到普通页面刷新。
 
 ## 实施步骤
 
@@ -40,10 +40,10 @@ PWA 状态组件保存注册结果，通过一个带并发合并和最小检查
 
 ## 验证
 
-- `vp run ready` 全量通过，网站 34 个测试文件共 299 项测试通过。
-- 构建后的 `sw.js` 使用新的 `CacheFirst` 资源缓存，并包含状态码和 Content-Type 校验。
+- `vp run ready` 全量通过，网站 34 个测试文件共 302 项测试通过。
+- 构建后的 `sw.js` 使用 `CacheFirst` 资源缓存，并在缓存写入和读取时校验状态码与 Content-Type。
 - 本地生产预览的首页、页面切换和深层路由刷新正常。
-- 模拟 `vite:preloadError` 后出现版本失效提示，“稍后”关闭提示，“立即更新”只触发一次重新加载。
+- 在线模拟 `vite:preloadError` 后出现资源加载失败提示，“稍后”关闭提示，“重新加载”只触发一次页面重载；离线模拟时不显示该对话框。
 - Vercel Preview 中缺失 `/assets/definitely-missing-version.js` 返回 `404 text/plain`，业务深层路由返回 `200 text/html`，`sw.js` 返回 `200 application/javascript` 并保持 `max-age=0, must-revalidate`。
 - 更新检查器的回归测试覆盖并发合并、节流、强制检查和 Worker 等待状态。
 
@@ -53,10 +53,11 @@ PWA 状态组件保存注册结果，通过一个带并发合并和最小检查
 - 2026-07-26：实现 Vercel 路由排除、`CacheFirst` 资源缓存、响应类型校验、主动更新检查和预加载失败提示，新增 8 项回归测试。
 - 2026-07-26：`vp run ready` 全量通过。生产预览中首页、页面切换和深层路由刷新正常；模拟 `vite:preloadError` 后能显示版本失效提示，“稍后”和“立即更新”行为符合预期。
 - 2026-07-26：本地 Vite Preview 会自行把缺失资源回退到 `index.html`，因此在 PR #44 的 Vercel Preview 完成最终路由验收。缺失脚本返回 404 且不是 HTML，业务路由和 Service Worker 响应正常。
+- 2026-07-26：根据 review 修正预加载失败边界，离线时不再误报版本失效；运行时缓存改为读写双向校验并复用原缓存名，避免遗留整份旧缓存。新增 3 项缓存读取回归测试，`vp run ready` 全量通过，生产预览的在线与离线场景验证符合预期。
 
 ## 结果
 
-部署切换后，已经访问过的带哈希资源可以继续从 Cache Storage 使用。未访问资源已经被新部署移除时，Vercel 不再用首页 HTML 冒充脚本响应，页面会显示明确的版本失效提示。长时间打开的标签页也会在重新可见、恢复联网和每小时定时检查时主动发现更新。
+部署切换后，已经访问过且通过校验的带哈希资源可以继续从 Cache Storage 使用，历史污染条目会被忽略并由有效响应替换。未访问资源已经被新部署移除时，Vercel 不再用首页 HTML 冒充脚本响应；联网页面会显示资源加载失败提示，离线页面保留原有错误处理。长时间打开的标签页也会在重新可见、恢复联网和每小时定时检查时主动发现更新。
 
 根目录 `README.md` 的表格变化来自 `vp check --fix` 对主分支近期内容的格式化，没有改变文意。
 
diff --git a/docs/frontend.md b/docs/frontend.md
index 8ed8b69..c9a4038 100644
--- a/docs/frontend.md
+++ b/docs/frontend.md
@@ -33,11 +33,11 @@
 
 Service Worker 只预缓存首页 App Shell，包括全局入口、首页路由依赖、Web App Manifest 和少量界面图片。构建插件从 Rollup 的网站入口和 `HomeView` 动态入口递归收集静态依赖、关联样式和首页直接引用的图片，拆包结果变化后不需要维护文件名通配规则。其他路由的懒加载 chunk、皮肤横幅和卡片预览图不进入预缓存。
 
-访问其他路由后，其带内容指纹的脚本、样式和字体通过 `CacheFirst` 写入有条目上限的运行时缓存，离线或新部署切换后仍可使用已经访问过的页面代码。缓存写入同时检查 `200` 状态和资源类型，HTML 与错误响应不能存到脚本、样式或字体 URL。正式横幅和皮肤雪球君按访问写入各自的 Cache Storage，使用内容哈希更新并限制条目数量。
+访问其他路由后，其带内容指纹的脚本、样式和字体通过 `CacheFirst` 写入有条目上限的运行时缓存，离线或新部署切换后仍可使用已经访问过的页面代码。缓存写入和读取都检查 `200` 状态及资源类型，HTML 与错误响应不能作为脚本、样式或字体使用；校验规则变更时继续复用原缓存名，由有效网络响应替换不合规条目。正式横幅和皮肤雪球君按访问写入各自的 Cache Storage，使用内容哈希更新并限制条目数量。
 
 应用外壳只保证页面代码和首页界面能启动，不缓存 API 响应、头像、帖子图片、附件或第三方媒体。离线状态下，已访问路由可以打开页面代码，但依赖服务端的数据继续进入现有错误状态。未访问过的路由不承诺首次离线打开。
 
-网站通过 Web App Manifest 提供名称、启动地址、独立窗口显示模式和安装图标。Service Worker 注册代码随应用入口打包，不单独生成 `registerSW.js`。页面重新可见、恢复联网和持续打开期间会主动检查更新，检查需要合并并发请求并限制频率。发现新 Worker 进入等待状态后，页面显示更新提示，用户确认刷新时才切换版本。懒加载资源因部署切换而失效时，Vite 的预加载错误也进入同一提示流程，不自动刷新正在编辑内容的页面。
+网站通过 Web App Manifest 提供名称、启动地址、独立窗口显示模式和安装图标。Service Worker 注册代码随应用入口打包，不单独生成 `registerSW.js`。页面重新可见、恢复联网和持续打开期间会主动检查更新，检查需要合并并发请求并限制频率。发现新 Worker 进入等待状态后，页面显示更新提示，用户确认刷新时才切换版本。联网时，Vite 的预加载错误会显示中性的资源加载失败提示并触发更新检查；离线时保留离线提示和原有错误处理，不把网络失败误报为版本失效，也不自动刷新正在编辑内容的页面。
 
 Cache Storage 负责请求与响应形式的静态资源。localStorage 不保存 Base64 图片，IndexedDB 留给草稿、待同步操作等结构化业务数据。扩展离线能力前先检查生成的预缓存清单和安装流量，不把 API 响应直接纳入 App Shell。