From 3206f8f49b41d53ee8c951cc8027002307bcbe81 Mon Sep 17 00:00:00 2001
From: Suzumiya <suzmii@qq.com>
Date: Mon, 5 Oct 2026 17:14:32 +0800
Subject: [PATCH] =?UTF-8?q?=E4=BF=AE=E5=A4=8D=E5=9C=A8=E7=BA=BF=E6=B8=B8?=
 =?UTF-8?q?=E7=8E=A9=E5=8A=A0=E8=BD=BD=E4=BD=93=E9=AA=8C=EF=BC=9A=E5=8A=A0?=
 =?UTF-8?q?=E8=BD=BD=E6=9C=9F=E9=BB=91=E5=B1=8F/=E7=A9=BA=E7=99=BD?=
 =?UTF-8?q?=E4=B8=8E=E5=8F=91=E8=A1=8C=E8=B5=84=E6=BA=90=E4=BC=A0=E8=BE=93?=
 =?UTF-8?q?=E5=BC=80=E9=94=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- packages/shared 新增共享游戏加载面 PlatformGameLoadingSurface：封面/标题 + 动效进度 + 按时长推进的阶段文案（准备/资源/引擎）+ 慢加载提示，附用例
- 网页游玩页用共享加载面替换近黑壳上的一行小字，加载上限改为共享常量 PLATFORM_GAME_LOADING_TIMEOUT_MS
- 后台审核试玩补加载面、20 秒超时与「重新创建试玩会话」入口，新会话重置加载态；补两条用例
- 发行网关（api-server）对文本类发行资源按 Accept-Encoding 下发 gzip，并下发强 ETag、命中 If-None-Match 返回 304；补 5 条 Rust 用例
- E2E 脚本 check-game-distribution-ops-rollback-e2e 补压缩/Vary/ETag/304/不接受 gzip 四条断言
- 同步 pitfalls、开发运维文档、nginx README 与两份里程碑记录
---
 .../AdminGameDistributionReviewPage.test.tsx  |  99 ++++
 .../pages/AdminGameDistributionReviewPage.tsx |  66 ++-
 apps/admin-web/src/styles/admin.css           |  14 +-
 deploy/nginx/README.md                        |   4 +-
 ...】后台游戏审核详情与待审版本试玩-2026-10-02.md |   7 +
 ...�碑】游戏分发目录详情与在线游玩-2026-09-18.md |   6 +
 docs/project-memory/shared-memory/pitfalls.md |   9 +
 ...发运维】本地开发验证与生产运维-2026-05-15.md |   1 +
 .../PlatformGameLoadingSurface.test.tsx       |  98 ++++
 .../components/PlatformGameLoadingSurface.tsx | 113 +++++
 packages/shared/src/components/index.ts       |  12 +
 packages/shared/src/components/styles.css     | 173 ++++++-
 ...eck-game-distribution-ops-rollback-e2e.mjs |  73 +++
 server-rs/Cargo.lock                          |   1 +
 server-rs/crates/api-server/Cargo.toml        |   1 +
 .../src/modules/game_distribution.rs          | 443 +++++++++++++++++-
 .../GameDistributionPages.test.tsx            |  22 +
 .../game-distribution/GamePlayPage.tsx        |  18 +-
 .../game-distribution/gameDistribution.css    |  10 -
 19 files changed, 1141 insertions(+), 29 deletions(-)
 create mode 100644 packages/shared/src/components/PlatformGameLoadingSurface.test.tsx
 create mode 100644 packages/shared/src/components/PlatformGameLoadingSurface.tsx

diff --git a/apps/admin-web/src/pages/AdminGameDistributionReviewPage.test.tsx b/apps/admin-web/src/pages/AdminGameDistributionReviewPage.test.tsx
index 3ca7ab6be..c2be88fb8 100644
--- a/apps/admin-web/src/pages/AdminGameDistributionReviewPage.test.tsx
+++ b/apps/admin-web/src/pages/AdminGameDistributionReviewPage.test.tsx
@@ -1,6 +1,7 @@
 /* @vitest-environment jsdom */
 
 import {
+  act,
   fireEvent,
   render,
   screen,
@@ -9,6 +10,8 @@ import {
 } from '@testing-library/react';
 import { beforeEach, expect, test, vi } from 'vitest';
 
+import { PLATFORM_GAME_LOADING_TIMEOUT_MS } from '@genarrative/shared/components';
+
 import {
   createAdminGameDistributionPreviewSession,
   getAdminGameDistributionVersion,
@@ -317,3 +320,99 @@ test('详情展示发布者和冻结资料，并试玩当前待审版本', async
     ),
   );
 });
+
+/** 打开详情并点开试玩，返回试玩 iframe。 */
+async function openPendingVersionPreview() {
+  render(
+    <AdminGameDistributionReviewPage
+      token="admin-token"
+      onUnauthorized={vi.fn()}
+    />,
+  );
+  await screen.findByText(gameTitle);
+  fireEvent.click(screen.getByRole('button', { name: '详情' }));
+  await screen.findAllByText(/测试作者/u);
+  fireEvent.click(screen.getByRole('button', { name: '试玩当前待审版本' }));
+  return screen.findByTitle('测试游戏 待审版本试玩');
+}
+
+test('试玩期间先给加载面，待审版本真正载入后让位给画面', async () => {
+  vi.mocked(getAdminGameDistributionVersion).mockResolvedValue(detailResponse);
+  vi.mocked(createAdminGameDistributionPreviewSession).mockResolvedValue({
+    previewUrl:
+      'http://127.0.0.1:8082/api/game-distribution/admin-previews/preview-1/',
+    expiresAt: '2026-10-02T12:10:00Z',
+    versionId: 'version-1',
+  });
+
+  const frame = await openPendingVersionPreview();
+
+  // 加载期不能只留一片空白：审核员要看到正在加载哪个游戏。
+  const loadingSurface = screen.getByRole('status');
+  expect(loadingSurface.textContent).toContain('测试游戏');
+  expect(
+    loadingSurface.classList.contains('platform-game-loading--panel'),
+  ).toBe(true);
+
+  fireEvent.load(frame);
+  await waitFor(() => expect(screen.queryByRole('status')).toBeNull());
+});
+
+test('试玩加载超过上限后给出超时说明与重建会话入口', async () => {
+  vi.mocked(getAdminGameDistributionVersion).mockResolvedValue(detailResponse);
+  vi.mocked(createAdminGameDistributionPreviewSession)
+    .mockResolvedValueOnce({
+      previewUrl:
+        'http://127.0.0.1:8082/api/game-distribution/admin-previews/preview-1/',
+      expiresAt: '2026-10-02T12:10:00Z',
+      versionId: 'version-1',
+    })
+    .mockResolvedValueOnce({
+      previewUrl:
+        'http://127.0.0.1:8082/api/game-distribution/admin-previews/preview-2/',
+      expiresAt: '2026-10-02T12:20:00Z',
+      versionId: 'version-1',
+    });
+
+  render(
+    <AdminGameDistributionReviewPage
+      token="admin-token"
+      onUnauthorized={vi.fn()}
+    />,
+  );
+  await screen.findByText(gameTitle);
+  fireEvent.click(screen.getByRole('button', { name: '详情' }));
+  await screen.findAllByText(/测试作者/u);
+
+  // 试玩会话与超时定时器都必须落在假定时器窗口内，才能按上限推进等待。
+  vi.useFakeTimers();
+  try {
+    fireEvent.click(screen.getByRole('button', { name: '试玩当前待审版本' }));
+    await act(async () => {
+      await Promise.resolve();
+    });
+    expect(screen.getByTitle('测试游戏 待审版本试玩')).toBeTruthy();
+    expect(screen.queryByText('试玩版本加载超时')).toBeNull();
+
+    await act(async () => {
+      vi.advanceTimersByTime(PLATFORM_GAME_LOADING_TIMEOUT_MS);
+    });
+    expect(screen.getByRole('status').textContent).toContain(
+      '试玩版本加载超时',
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: '重新创建试玩会话' }));
+    await act(async () => {
+      await Promise.resolve();
+    });
+    expect(createAdminGameDistributionPreviewSession).toHaveBeenCalledTimes(2);
+    // 新会话必须回到加载态，不能沿用上一个会话的「已就绪」或超时结论。
+    const rebuilt = screen.getByTitle('测试游戏 待审版本试玩');
+    expect(rebuilt.getAttribute('src')).toBe(
+      'http://127.0.0.1:8082/api/game-distribution/admin-previews/preview-2/',
+    );
+    expect(screen.queryByText('试玩版本加载超时')).toBeNull();
+  } finally {
+    vi.useRealTimers();
+  }
+});
diff --git a/apps/admin-web/src/pages/AdminGameDistributionReviewPage.tsx b/apps/admin-web/src/pages/AdminGameDistributionReviewPage.tsx
index f63a9c79e..eb816f0b2 100644
--- a/apps/admin-web/src/pages/AdminGameDistributionReviewPage.tsx
+++ b/apps/admin-web/src/pages/AdminGameDistributionReviewPage.tsx
@@ -10,6 +10,8 @@ import {
   formatAdminDateTime,
   GameDetailDisplay,
   Modal,
+  PLATFORM_GAME_LOADING_TIMEOUT_MS,
+  PlatformGameLoadingSurface,
   TextField,
 } from '@genarrative/shared/components';
 import { RefreshCcw } from 'lucide-react';
@@ -591,6 +593,20 @@ function AdminGameDistributionReviewDetailView({
   onReject: () => void;
   onApprove: () => void;
 }) {
+  // 试玩会话是按 version 现建的：新会话必须回到加载态，不能沿用上一个会话的 ready。
+  const [isPreviewFrameReady, setIsPreviewFrameReady] = useState(false);
+  const [isPreviewTimedOut, setIsPreviewTimedOut] = useState(false);
+
+  useEffect(() => {
+    setIsPreviewFrameReady(false);
+    setIsPreviewTimedOut(false);
+    if (!previewUrl) return undefined;
+    const timer = window.setTimeout(() => {
+      setIsPreviewTimedOut(true);
+    }, PLATFORM_GAME_LOADING_TIMEOUT_MS);
+    return () => window.clearTimeout(timer);
+  }, [previewUrl]);
+
   if (!detail) {
     return (
       <AdminPage wide>
@@ -606,6 +622,10 @@ function AdminGameDistributionReviewDetailView({
     );
   }
 
+  const coverUrl = detail.game.coverObjectKey
+    ? assetUrls[detail.game.coverObjectKey]
+    : '';
+
   return (
     <AdminPage wide>
       <AdminPageHeading
@@ -682,13 +702,45 @@ function AdminGameDistributionReviewDetailView({
             <AdminAlert tone="warning">{previewError}</AdminAlert>
           ) : null}
           {previewUrl ? (
-            <iframe
-              title={`${detail.game.title} 待审版本试玩`}
-              src={previewUrl}
-              sandbox="allow-scripts"
-              referrerPolicy="no-referrer"
-              className="admin-game-review-preview"
-            />
+            <div className="admin-game-review-preview-shell">
+              {isPreviewFrameReady ? null : (
+                <PlatformGameLoadingSurface
+                  tone="panel"
+                  title={detail.game.title}
+                  cover={
+                    coverUrl ? (
+                      <img alt={`${detail.game.title} 封面`} src={coverUrl} />
+                    ) : null
+                  }
+                  message={isPreviewTimedOut ? '试玩版本加载超时' : undefined}
+                  hint={
+                    isPreviewTimedOut
+                      ? '可以重新创建试玩会话，或稍后再试。'
+                      : undefined
+                  }
+                />
+              )}
+              <iframe
+                title={`${detail.game.title} 待审版本试玩`}
+                src={previewUrl}
+                sandbox="allow-scripts"
+                referrerPolicy="no-referrer"
+                className="admin-game-review-preview"
+                onLoad={() => setIsPreviewFrameReady(true)}
+              />
+            </div>
+          ) : null}
+          {previewUrl && isPreviewTimedOut && !isPreviewFrameReady ? (
+            <AdminActionRow className="admin-review-actions">
+              <AdminButton
+                variant="secondary"
+                type="button"
+                disabled={isPreviewLoading}
+                onClick={onPreview}
+              >
+                {isPreviewLoading ? '准备试玩…' : '重新创建试玩会话'}
+              </AdminButton>
+            </AdminActionRow>
           ) : null}
         </section>
       </GameDetailDisplay>
diff --git a/apps/admin-web/src/styles/admin.css b/apps/admin-web/src/styles/admin.css
index cca933070..d156c128e 100644
--- a/apps/admin-web/src/styles/admin.css
+++ b/apps/admin-web/src/styles/admin.css
@@ -3590,16 +3590,28 @@ button:disabled {
   color: var(--platform-text-strong);
 }
 
+.admin-game-review-preview-shell {
+  /* 加载面（PlatformGameLoadingSurface）按绝对定位铺在预览区上，外壳必须是定位祖先。 */
+  position: relative;
+  margin-top: 1rem;
+  min-height: 42rem;
+  overflow: hidden;
+  border-radius: 1rem;
+}
+
 .admin-game-review-preview {
   display: block;
   width: 100%;
   min-height: 42rem;
-  margin-top: 1rem;
   border: 1px solid var(--platform-surface-border);
   border-radius: 1rem;
   background: #fff;
 }
 
+.admin-game-review-preview-shell .platform-game-loading {
+  border-radius: 1rem;
+}
+
 /*
  * 游戏管理列表（AdminGameManagementPage）专属排布，选择器全部框在本页表格内，
  * 不影响其它后台页面：
diff --git a/deploy/nginx/README.md b/deploy/nginx/README.md
index e022e295c..fe1c64fd3 100644
--- a/deploy/nginx/README.md
+++ b/deploy/nginx/README.md
@@ -104,7 +104,9 @@ curl -sSI -H 'Accept-Encoding: br' \
 
 - 现役发行入口是平台同源路径 `https://<平台域名>/games/<gameId>/`。三份常驻模板（`genarrative.conf`、`genarrative-dev-http.conf`、容器 `deploy/container/nginx.conf`）都内联同一条同源发行入口 location，把 `/games/<gameId>/` 与 `/games/<gameId>/<asset>` 转发到 `api-server` 发行网关；不再需要独立发行域名、`*.games.<域名>` 通配 DNS 或通配 TLS。
 - 该 location 的正则必须整体加双引号：`location ~ "^/games/(?<game_id>game_[0-9a-f]{32})(?<game_path>/.*)?$"`。不加引号时 nginx 会把 `{32}` 当块定界符，`nginx -t` 报 `pcre2_compile() failed: missing closing parenthesis`。
-- 发行入口不使用 Cookie：边缘转发前设置 `proxy_set_header Cookie ""`；`api-server` 发行网关也会拒绝带 Cookie 的请求。响应头（`X-Content-Type-Options`、CORP、无凭据 CORS、HTML CSP、内容类型白名单与 `Cache-Control: public, max-age=60, must-revalidate`）由 `api-server` 发行网关设置，边缘不覆盖。
+- 发行入口不使用 Cookie：边缘转发前设置 `proxy_set_header Cookie ""`；`api-server` 发行网关也会拒绝带 Cookie 的请求。响应头（`X-Content-Type-Options`、CORP、无凭据 CORS、HTML CSP、内容类型白名单、`ETag` 与 `Cache-Control: public, max-age=60, must-revalidate`）由 `api-server` 发行网关设置，边缘不覆盖。
+- 传输编码：发行网关自己对文本类资源（HTML/JS/CSS/JSON/SVG/WASM，≥1 KiB）下发 `Content-Encoding: gzip` + `Vary: Accept-Encoding`，边缘的 gzip/Brotli 不会二次压缩（两边都以「上游已带 `Content-Encoding` 就跳过」收口）。因此直连 api-server（本地 dev 的 Vite 代理、或关闭边缘压缩的 Pingora 模式）时用户拿到的字节与生产边缘一致，不再出现「本地/未压缩边缘下引擎包原样 1.31 MiB」的落差。
+- 条件请求：命中 `If-None-Match` 时发行网关直接返回 `304`（无正文，保留 `Cache-Control` 与 `ETag`），所以 60 秒 `max-age` 之后的重复游玩只重验证、不重下整包；下架与换版仍按 60 秒窗口在新请求上生效。
 - 隔离靠 iframe 沙箱而不是独立来源：游戏文档跑在 `sandbox="allow-scripts"` 的不透明来源里，读不到主站 Cookie、storage 与 DOM，离开页面即随 iframe 卸载。
 - 审核通过时 `api-server` 按 gameId 派生同源路径 `/games/<gameId>/` 作为 `entryUrl` 写入公开投影，部署侧不再需要配置发行域名。换版本或下架只改变后端公开投影，边缘不需要改配置。
 - 门禁：`npm run check:nginx-spa-routes` 校验三份模板的 SPA allowlist（含 `/games`、`/games/detail`、`/games/play`、`/games/mine`、`/games/publish`、`/pay`、`/profile/payment`）与收银台深链前缀路由 `location ~* "^/pay/[^/]+/?$"`（`/pay/<checkoutToken>` 只放行「前缀 + 恰好一个路径段」；只放行裸前缀会让真实收银台链接落到默认 location 变 404），脚本自带正/反用例。历史上的独立来源模板与专属门禁已随同源方案上线删除。
diff --git a/docs/project-memory/plans/【里程碑】后台游戏审核详情与待审版本试玩-2026-10-02.md b/docs/project-memory/plans/【里程碑】后台游戏审核详情与待审版本试玩-2026-10-02.md
index ffceb220c..628a0464b 100644
--- a/docs/project-memory/plans/【里程碑】后台游戏审核详情与待审版本试玩-2026-10-02.md
+++ b/docs/project-memory/plans/【里程碑】后台游戏审核详情与待审版本试玩-2026-10-02.md
@@ -49,3 +49,10 @@
 - 自动化：admin-web 详情/动作测试、api-server 预览会话和权限测试、DTO/类型检查、编码和 diff 检查。
 - 运行时：本地管理员打开待审版本，确认资料、封面/截图和待审包试玩；确认旧公开版本不会被误播。
 - 边界：过期 Token、错误 versionId、Cookie、越权管理员、缺入口、资源 404、CAS 冲突和幂等重放。
+
+## 本轮核对（2026-10-05，试玩加载体验与超时收口）
+
+- 「试玩当前待审版本」原先只渲染 `<iframe class="admin-game-review-preview">`：加载期是一块 `min-height: 42rem` 的空白，没有加载文案、没有超时、没有失败提示（会话过期或资源 404 会永远停在空白）。2026-10-05 起与网页游玩页共用共享加载面 `PlatformGameLoadingSurface`（`packages/shared`）：加载期显示游戏标题/封面/动效进度与阶段文案，iframe `onLoad` 后才让位给画面。
+- 加载上限与网页游玩页统一为 `PLATFORM_GAME_LOADING_TIMEOUT_MS`（20 秒）：超时后加载面换成「试玩版本加载超时」并给出「重新创建试玩会话」入口；新建会话会重置加载态，不会沿用上一个会话的 ready。
+- 用例：`apps/admin-web/src/pages/AdminGameDistributionReviewPage.test.tsx` 新增两条（加载面在画面载入后让位、超过上限后给出超时说明与重建入口，重建后新会话 URL 生效且回到加载态）。
+- 仍未变化：预览会话 token 与 `no-store`、`sandbox="allow-scripts"`、Cookie 拒绝、版本绑定与审核 CAS 口径都不动。
diff --git a/docs/project-memory/plans/【里程碑】游戏分发目录详情与在线游玩-2026-09-18.md b/docs/project-memory/plans/【里程碑】游戏分发目录详情与在线游玩-2026-09-18.md
index 2f5fc6306..972932738 100644
--- a/docs/project-memory/plans/【里程碑】游戏分发目录详情与在线游玩-2026-09-18.md
+++ b/docs/project-memory/plans/【里程碑】游戏分发目录详情与在线游玩-2026-09-18.md
@@ -333,3 +333,9 @@
 - **详情页返回按来源回到上一页**：`GameDetailPage` 左上角原来是写死的「返回游戏广场」，并且直接 `setSelectionStage('games')`（等于 push 一条新的 `/games`）。从「我的游戏」点进详情再返回就落到广场，从广场进详情返回也会多压一条重复历史。现在文案简化为「返回」，行为改成优先 `window.history.back()`，由 `ActiveApp` 已有的 `popstate` 同步把舞台还原成真正的来源页（我的游戏 / 广场）；游玩页的返回同样处理，避免详情↔游玩互相 push。协议侧给应用写入的历史条目补了 `__genarrativeAppHistoryDepth`，新增 `hasAppHistoryBackEntry()` 判断「当前条目是应用内导航写入的且存在上一页」；直接打开详情深链、或原生壳里没有可回退条目时，才 `replaceAppHistoryPath` 兜底到广场（游玩页兜底到自己的详情）。回归用例 `activeAppPageRoutes.test.ts` 锁定深度标记语义，`PlatformEntryActiveFlowShell.test.tsx`「游戏详情返回」两条锁定原生返回与深链兜底。
 - **游戏分发的返回文案统一成「返回」**：`GameDetailPage`、`GamePlayPage`（含超时面板里的按钮）、`MyGamesPage`、`GamePublishPage` 四处原本是「返回游戏广场 / 返回详情」，同一套流程里出现三种写法；现在统一成「返回」，目标页仍由各自的 `onBack`（广场 / 我的游戏 / 详情）决定，按钮不再承诺一个可能不对的目的地。`GameDistributionPages.test.tsx` 的断言同步改为 `/^返回$/u`。游玩页工具栏上那个按钮展示的是游戏名（退出开始面板后就靠它认游戏），不属于「返回 xx」文案，保持不动。
 - 验证：`npx vitest run src/components/game-distribution/GameDistributionPages.test.tsx`（21 passed）、`npx vitest run src/components/platform-entry/PlatformEntryActiveFlowShell.test.tsx`（22 passed）、`npx vitest run src/routing/activeAppPageRoutes.test.ts`、`npm run typecheck`、`npx eslint`（五个改动文件）、`npm run check:encoding`、`git diff --check` 全部通过；启动面板的溢出可达性、「我的游戏」移动端横向溢出都用真实 Chromium 静态夹具量过（见 pitfalls 同日条目），详情返回链在真实 Chromium（dev 栈 390x844）实测 `/games`→详情→返回=`/games`、深链直开详情→返回=`/games`、详情→立即玩→返回详情=`/games/detail?id=…`。视觉与真机横竖屏走查仍需人工/截图评审（沿用阶段 C 第 8 条未取证口径）。
+
+## 本轮核对（2026-10-05，游玩页加载体验与发行资源传输）
+
+- 游玩页此前在 `onLoad` 前只盖一行 `游戏正在启动…`（近黑壳上），用户反馈「一直黑屏」。现在加载期显示共享加载面 `PlatformGameLoadingSurface`（`packages/shared`，封面/标题 + 动效进度 + 按时长推进的阶段文案），`onLoad` 后淡入画面；超时面板与重试/返回不变，上限仍与后台试玩统一为 `PLATFORM_GAME_LOADING_TIMEOUT_MS`（20 秒）。
+- 发行网关（`api-server`）对文本类发行资源下发 `Content-Encoding: gzip` + `Vary: Accept-Encoding`，并下发强 `ETag`：`If-None-Match` 命中返回 304。`max-age=60, must-revalidate` 与撤销窗口不变，差别只是 60 秒之后重复游玩不再重下整包。后台试玩会话仍是 `no-store` 且无 ETag。
+- 证据：真实栈 4 Mbps/100 ms 模拟链路对照（改前 3298 ms / 4587 ms 才出画面，且期间无有效加载反馈），发行网关字节数对照见 PR；`cargo test -p api-server --bin api-server -- game_distribution` 与三条前端用例（共享加载面、游玩页、后台试玩）为回归门禁。
diff --git a/docs/project-memory/shared-memory/pitfalls.md b/docs/project-memory/shared-memory/pitfalls.md
index f30bca711..95905d797 100644
--- a/docs/project-memory/shared-memory/pitfalls.md
+++ b/docs/project-memory/shared-memory/pitfalls.md
@@ -6406,3 +6406,12 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/` 
 - **别踩**：不要写成裸前缀正则（`^/pay`）——它会吞掉 `/payment/x`、`/paycheckout/x` 这类同名邻居；也不要把深链塞进精确 allowlist 的 alternatives 里（`pay` 的 alternatives 只匹配 `/pay`）。
 - **判据/取证**：`node --test scripts/check-nginx-spa-routes.test.mjs`（正/反用例，含「写回精确匹配即红」）、`npm run check:nginx-spa-routes`、`npm run check:pingora-route-parity`、`cargo test -p pingora-gateway -- pay_checkout_deep_link matches_nginx_route_parity_matrix`；线上复验 `curl -s -o /dev/null -w '%{http_code}' https://<平台域名>/pay/<checkoutToken>` → 200 且正文与 `/` 同一份 `index.html`。
 - **关联**：`scripts/check-nginx-spa-routes.mjs`、`deploy/pingora/nginx-route-parity.matrix.json`、`server-rs/crates/pingora-gateway/src/main.rs`、`server-rs/crates/api-server/src/payment.rs`、`deploy/nginx/genarrative.conf`。
+
+## 2026-10-05 在线游玩「一直黑屏」：加载面缺失 + 发行网关不压不发 ETag
+
+- **现象**：用户反馈「进入游玩…加载有点慢，一直黑屏体验不好」。真实栈（真实发行包 + Chromium + 4 Mbps/100 ms 模拟链路）实测：网页游玩页点击「开始游戏」后 99.3% 像素亮度 < 24 的近黑面板 + 一行 `游戏正在启动…`，游戏画面 **3298 ms** 才出现；后台审核页点「试玩当前待审版本」后 iframe 直接以 `opacity:1` 出现、区域**全白空白** 4587 ms，页面**全程没有任何加载文案**。
+- **根因**：① 网页游玩页的加载态只有一行小字盖在 `#17131b` 近黑壳上，没有封面/进度/阶段文案，`ready` 判定又只看 iframe `onLoad`（文档加载完成 ≠ 游戏可玩）；② 后台试玩只有 `<iframe class="admin-game-review-preview">`，没有加载态、没有超时、没有失败处理，会话过期或资源 404 会永远停在空白；③ 发行网关把 ZIP 解压后的原文直出，`phaser.min.js` 1,375,976 B 原样下发（`Content-Encoding: none`），也没有 ETag —— 4 Mbps 下光这一个文件就 ~2.7 s，且 60 秒 `max-age` 过后浏览器只能重下整包。
+- **处理（现行口径）**：新增共享组件 `PlatformGameLoadingSurface`（`packages/shared`，封面/标题 + 动效进度 + 按时长推进的阶段文案 + 慢加载提示），网页游玩页与后台试玩共用；两端的加载上限统一为 `PLATFORM_GAME_LOADING_TIMEOUT_MS`（20 秒），后台超时后给出「重新创建试玩会话」。发行网关对文本类资源（HTML/JS/CSS/JSON/SVG/WASM，≥1 KiB、客户端接受 gzip）下发 `Content-Encoding: gzip` + `Vary: Accept-Encoding`，并下发按 `versionId + 资源路径` 摘要的强 ETag，命中 `If-None-Match` 返回 304（无正文）。
+- **边界**：镜像/音频/视频等已是压缩格式的资源不压；后台试玩会话仍是 `no-store` 且不给 ETag；`max-age=60, must-revalidate` 与撤销窗口不变（换版/下架仍最迟 60 秒对新请求生效，304 只是在窗口之后省掉重下）。边缘 gzip/Brotli 与本层不冲突：两边都以「响应已带 `Content-Encoding` 就跳过」收口；但 Pingora 网关在自身压缩关闭时会**移除** `accept-encoding`（`normalize_accept_encoding_for_gateway_compression`），那种部署形态下源站压缩不会生效，属于网关侧口径。
+- **验证**：`cargo test -p api-server --bin api-server -- game_distribution`（新增 ETag 作用域、`If-None-Match` 列表/弱校验命中、`gzip;q=0` 拒绝、文本压缩与二进制/小文件不压、304 无正文等用例）；`npx vitest run packages/shared/src/components/PlatformGameLoadingSurface.test.tsx`、`src/components/game-distribution/GameDistributionPages.test.tsx`、`apps/admin-web/src/pages/AdminGameDistributionReviewPage.test.tsx`；真实栈复跑探针后发行网关 `phaser.min.js` 由 1,376 KB 降到约 330 KB，用户端/后台端改后同链路对照见 PR。
+- **关联**：`packages/shared/src/components/PlatformGameLoadingSurface.tsx`、`src/components/game-distribution/GamePlayPage.tsx`、`apps/admin-web/src/pages/AdminGameDistributionReviewPage.tsx`、`server-rs/crates/api-server/src/modules/game_distribution.rs`、`deploy/nginx/README.md`。
diff --git a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
index dc13e3894..60dfa28ec 100644
--- a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
+++ b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
@@ -744,6 +744,7 @@ Jenkins 按 web / api / Spacetime module / build / deploy / publish 拆分
 - 路由约定：`https://<平台域名>/games/<gameId>/` 是该游戏的入口，`/games/<gameId>/<asset>` 映射到发行网关 `/api/game-distribution/releases/<gameId>/<asset>`。同源发行入口 location 写在 `deploy/nginx/genarrative.conf`（生产 HTTPS）、`deploy/nginx/genarrative-dev-http.conf`（开发 HTTP）与 `deploy/container/nginx.conf`（容器）里。正则必须整体加双引号：`location ~ "^/games/(?<game_id>game_[0-9a-f]{32})(?<game_path>/.*)?$"`，否则 nginx 会把 `{32}` 当块定界符并在 `nginx -t` 报 missing closing parenthesis。
 - 会话与隔离：边缘在转发前 `proxy_set_header Cookie ""`，发行网关自身也对带 `Cookie` 的请求返回 `403`；游戏文档跑在 iframe `sandbox="allow-scripts"` 的不透明来源里，读不到主站 Cookie、storage 与 DOM，离开页面即随 iframe 卸载整套游戏代码。
 - 响应头与缓存：`X-Content-Type-Options`、CORP（`cross-origin`）、无凭据 CORS、HTML CSP、内容类型白名单与 `Cache-Control: public, max-age=60, must-revalidate` 都由发行网关设置，边缘不覆盖。换版与下架只改变后端公开投影，因此**最迟 60 秒**内新请求不再拿到旧版本；已经下载到浏览器的脚本无法远程抹除，撤销能力以"停止继续分发"为准。
+- 传输与条件请求（2026-10-05）：发行网关对文本类资源（HTML/JS/CSS/JSON/SVG/WASM，≥1 KiB）在客户端接受 `gzip` 时下发 `Content-Encoding: gzip` 并带 `Vary: Accept-Encoding`；图片、音频、视频等已是压缩格式的资源保持原样。同时下发强 `ETag`（按 `versionId + 资源路径` 摘要），命中 `If-None-Match` 时返回 `304`（无正文、保留 `Cache-Control` 与 `ETag`），所以 60 秒缓存窗口之后浏览器只需重验证而不是重下整包；`max-age` 与 `must-revalidate` 都不变，撤销窗口仍是 60 秒。后台试玩会话固定 `no-store`，不给 ETag。
 - 审核动作：管理员只提交审核结论与公开修订号，`entryUrl` 由 `api-server` 按 gameId 派生**同源路径** `/games/{gameId}/` 写入公开投影；dev / release / 预览环境口径完全一致，入口不再由部署侧配置，历史数据里的绝对 URL 继续兼容。
 - 门禁：
 
diff --git a/packages/shared/src/components/PlatformGameLoadingSurface.test.tsx b/packages/shared/src/components/PlatformGameLoadingSurface.test.tsx
new file mode 100644
index 000000000..da389d2cb
--- /dev/null
+++ b/packages/shared/src/components/PlatformGameLoadingSurface.test.tsx
@@ -0,0 +1,98 @@
+/* @vitest-environment jsdom */
+
+import { act, render, screen } from '@testing-library/react';
+import { afterEach, describe, expect, test, vi } from 'vitest';
+
+import {
+  PLATFORM_GAME_LOADING_ASSET_PHASE_MS,
+  PLATFORM_GAME_LOADING_ENGINE_PHASE_MS,
+  PLATFORM_GAME_LOADING_SLOW_PHASE_MS,
+  PlatformGameLoadingSurface,
+  resolvePlatformGameLoadingMessage,
+} from './PlatformGameLoadingSurface';
+
+function readMessage() {
+  return screen
+    .getByRole('status')
+    .querySelector('.platform-game-loading__message')?.textContent;
+}
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+describe('PlatformGameLoadingSurface', () => {
+  test('阶段文案随等待时长推进，慢加载才追加提示行', () => {
+    vi.useFakeTimers();
+    render(<PlatformGameLoadingSurface title="星尘防线" />);
+
+    const surface = screen.getByRole('status');
+    expect(surface.getAttribute('aria-busy')).toBe('true');
+    expect(surface.getAttribute('aria-label')).toContain('星尘防线');
+    expect(readMessage()).toBe(resolvePlatformGameLoadingMessage(0));
+    expect(surface.querySelector('.platform-game-loading__hint')).toBeNull();
+
+    act(() => {
+      vi.advanceTimersByTime(PLATFORM_GAME_LOADING_ASSET_PHASE_MS);
+    });
+    expect(readMessage()).toBe(
+      resolvePlatformGameLoadingMessage(PLATFORM_GAME_LOADING_ASSET_PHASE_MS),
+    );
+    expect(
+      screen.getByRole('status').querySelector('.platform-game-loading__hint'),
+    ).toBeNull();
+
+    act(() => {
+      vi.advanceTimersByTime(
+        PLATFORM_GAME_LOADING_ENGINE_PHASE_MS -
+          PLATFORM_GAME_LOADING_ASSET_PHASE_MS,
+      );
+    });
+    expect(readMessage()).toBe(
+      resolvePlatformGameLoadingMessage(PLATFORM_GAME_LOADING_ENGINE_PHASE_MS),
+    );
+
+    act(() => {
+      vi.advanceTimersByTime(
+        PLATFORM_GAME_LOADING_SLOW_PHASE_MS -
+          PLATFORM_GAME_LOADING_ENGINE_PHASE_MS,
+      );
+    });
+    expect(
+      screen.getByRole('status').querySelector('.platform-game-loading__hint')
+        ?.textContent,
+    ).toBeTruthy();
+  });
+
+  test('宿主文案与提示覆盖默认阶段文案，封面按宿主给的内容渲染', () => {
+    render(
+      <PlatformGameLoadingSurface
+        title="待审版本试玩"
+        tone="panel"
+        message="正在创建试玩会话…"
+        hint="会话过期后请重新创建"
+        cover={<img alt="封面" src="data:image/gif;base64,R0lGOD" />}
+      />,
+    );
+
+    const surface = screen.getByRole('status');
+    expect(surface.className).toContain('platform-game-loading--panel');
+    expect(readMessage()).toBe('正在创建试玩会话…');
+    expect(
+      surface.querySelector('.platform-game-loading__hint')?.textContent,
+    ).toBe('会话过期后请重新创建');
+    expect(screen.getByRole('img', { name: '封面' })).toBeTruthy();
+  });
+
+  test('没有封面时渲染图标占位而不是空白区块', () => {
+    const { container } = render(
+      <PlatformGameLoadingSurface title="加载中" tone="player" />,
+    );
+
+    const surface = container.querySelector('.platform-game-loading');
+    expect(surface?.className).toContain('platform-game-loading--player');
+    expect(
+      surface?.querySelector('.platform-game-loading__cover svg'),
+    ).toBeTruthy();
+  });
+});
diff --git a/packages/shared/src/components/PlatformGameLoadingSurface.tsx b/packages/shared/src/components/PlatformGameLoadingSurface.tsx
new file mode 100644
index 000000000..f9545cc35
--- /dev/null
+++ b/packages/shared/src/components/PlatformGameLoadingSurface.tsx
@@ -0,0 +1,113 @@
+import { Gamepad2 } from 'lucide-react';
+import { useEffect, useState, type ReactNode } from 'react';
+
+/** 阶段文案切换点：先「准备」，再「资源」，最后「引擎」。 */
+export const PLATFORM_GAME_LOADING_ASSET_PHASE_MS = 1_500;
+export const PLATFORM_GAME_LOADING_ENGINE_PHASE_MS = 6_000;
+/** 超过这个时长仍未进入游戏，补一行「比平时久」的状态，避免用户以为卡死。 */
+export const PLATFORM_GAME_LOADING_SLOW_PHASE_MS = 12_000;
+/**
+ * 发行包首屏加载上限。
+ *
+ * 网页游玩页与后台审核试玩共用同一口径：超过上限就给出显式超时与重试，而不是让
+ * 用户对着加载面无限期等待。
+ */
+export const PLATFORM_GAME_LOADING_TIMEOUT_MS = 20_000;
+
+export type PlatformGameLoadingSurfaceTone = 'player' | 'panel';
+
+export type PlatformGameLoadingSurfaceProps = {
+  /** 游戏标题：加载面用来说明正在加载哪一个游戏。 */
+  title: string;
+  /**
+   * 封面内容由宿主提供：网页端与后台端各自持有素材换签逻辑，共享组件只负责摆放，
+   * 缺省时退化为平台图标占位。
+   */
+  cover?: ReactNode | null;
+  /** `player` 用于暗色播放器壳，`panel` 用于浅色后台面板。 */
+  tone?: PlatformGameLoadingSurfaceTone;
+  /** 覆盖默认阶段文案（例如宿主自己知道正在创建试玩会话）。 */
+  message?: string;
+  /** 追加一行提示（例如失败的兜底说明）。 */
+  hint?: string;
+  className?: string;
+};
+
+const DEFAULT_COPY_BY_PHASE: Record<'prepare' | 'assets' | 'engine', string> = {
+  prepare: '正在准备游戏…',
+  assets: '正在加载游戏资源…',
+  engine: '正在启动游戏引擎…',
+};
+
+/** 按已等待时长给出阶段文案；与 `PlatformGameLoadingSurface` 内的计时同源。 */
+export function resolvePlatformGameLoadingMessage(elapsedMs: number) {
+  if (elapsedMs >= PLATFORM_GAME_LOADING_ENGINE_PHASE_MS) {
+    return DEFAULT_COPY_BY_PHASE.engine;
+  }
+  if (elapsedMs >= PLATFORM_GAME_LOADING_ASSET_PHASE_MS) {
+    return DEFAULT_COPY_BY_PHASE.assets;
+  }
+  return DEFAULT_COPY_BY_PHASE.prepare;
+}
+
+/**
+ * 平台通用「游戏加载面」。
+ *
+ * 发行包（Phaser/Vite 产物）首屏要下完整个引擎与资源，网络稍慢就是好几秒；这段时间
+ * 网页游玩页与后台审核试玩都必须给出**看得见的**加载反馈，而不是近黑面板上的一行小字
+ * 或一片空白。阶段文案由组件自己按时长推进，宿主只负责在真正进入游戏后把它换掉。
+ */
+export function PlatformGameLoadingSurface({
+  title,
+  cover = null,
+  tone = 'panel',
+  message,
+  hint,
+  className,
+}: PlatformGameLoadingSurfaceProps) {
+  const [elapsedMs, setElapsedMs] = useState(0);
+
+  useEffect(() => {
+    const startedAt = Date.now();
+    const timer = window.setInterval(() => {
+      setElapsedMs(Date.now() - startedAt);
+    }, 500);
+    return () => window.clearInterval(timer);
+  }, []);
+
+  const statusMessage = message ?? resolvePlatformGameLoadingMessage(elapsedMs);
+  const slowHint =
+    !hint && elapsedMs >= PLATFORM_GAME_LOADING_SLOW_PHASE_MS
+      ? '加载时间比平时更久，仍在继续…'
+      : hint;
+
+  return (
+    <div
+      role="status"
+      aria-live="polite"
+      aria-busy="true"
+      aria-label={`${title} ${statusMessage}`}
+      className={[
+        'platform-game-loading',
+        `platform-game-loading--${tone}`,
+        className,
+      ]
+        .filter(Boolean)
+        .join(' ')}
+    >
+      <div className="platform-game-loading__cover">
+        {cover ?? <Gamepad2 aria-hidden="true" />}
+      </div>
+      <div className="platform-game-loading__copy">
+        <strong className="platform-game-loading__title">{title}</strong>
+        <p className="platform-game-loading__message">{statusMessage}</p>
+        <div className="platform-game-loading__track" aria-hidden="true">
+          <span className="platform-game-loading__fill" />
+        </div>
+        {slowHint ? (
+          <p className="platform-game-loading__hint">{slowHint}</p>
+        ) : null}
+      </div>
+    </div>
+  );
+}
diff --git a/packages/shared/src/components/index.ts b/packages/shared/src/components/index.ts
index c60cc131a..44d723259 100644
--- a/packages/shared/src/components/index.ts
+++ b/packages/shared/src/components/index.ts
@@ -44,6 +44,18 @@ export type {
   PlatformFilterToolbarTabItem,
 } from './PlatformFilterToolbar';
 export { PlatformFilterToolbar } from './PlatformFilterToolbar';
+export type {
+  PlatformGameLoadingSurfaceProps,
+  PlatformGameLoadingSurfaceTone,
+} from './PlatformGameLoadingSurface';
+export {
+  PLATFORM_GAME_LOADING_ASSET_PHASE_MS,
+  PLATFORM_GAME_LOADING_ENGINE_PHASE_MS,
+  PLATFORM_GAME_LOADING_SLOW_PHASE_MS,
+  PLATFORM_GAME_LOADING_TIMEOUT_MS,
+  PlatformGameLoadingSurface,
+  resolvePlatformGameLoadingMessage,
+} from './PlatformGameLoadingSurface';
 export type {
   PlatformIconBadgeProps,
   PlatformIconBadgeShape,
diff --git a/packages/shared/src/components/styles.css b/packages/shared/src/components/styles.css
index 64da136c9..0c1d6c7f0 100644
--- a/packages/shared/src/components/styles.css
+++ b/packages/shared/src/components/styles.css
@@ -1398,7 +1398,8 @@ textarea.genarrative-ui-text-field__control {
   .genarrative-ui-switch,
   .genarrative-ui-progress__fill,
   .genarrative-ui-spinner,
-  .genarrative-ui-skeleton {
+  .genarrative-ui-skeleton,
+  .platform-game-loading__fill {
     transition: none;
     animation: none;
   }
@@ -1541,3 +1542,173 @@ textarea.genarrative-ui-text-field__control {
   )::after {
   content: attr(aria-label);
 }
+
+/*
+ * 平台「游戏加载面」：发行包（Phaser/Vite 产物）首屏要下完整个引擎与资源，网络稍慢就是
+ * 好几秒；网页游玩页与后台审核试玩都必须在这段时间给出看得见的加载反馈，而不是近黑面板
+ * 上的一行小字或一片空白。
+ *
+ * 样式放在这里而不是任一宿主的业务样式表：后台 `admin-web` 只引入本文件与 `theme.css`，
+ * 没有 Tailwind，因此共享组件不能只靠工具类撑起外观。
+ */
+.platform-game-loading {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  justify-content: center;
+  gap: clamp(1rem, 3vw, 2.25rem);
+  padding: clamp(1rem, 4vw, 2.5rem);
+  overflow-y: auto;
+}
+
+.platform-game-loading--player {
+  background: linear-gradient(135deg, #1e1820, #302329);
+  color: #fff8f0;
+}
+
+.platform-game-loading--panel {
+  background: var(--platform-panel-fill-soft, rgba(255, 254, 252, 0.96));
+  color: var(--platform-text-base, #6f5848);
+}
+
+.platform-game-loading__cover {
+  display: grid;
+  aspect-ratio: 4 / 3;
+  width: clamp(6.5rem, 18vw, 11rem);
+  flex: 0 0 auto;
+  place-items: center;
+  overflow: hidden;
+  border-radius: 1.1rem;
+}
+
+.platform-game-loading--player .platform-game-loading__cover {
+  background: rgba(255, 255, 255, 0.08);
+  box-shadow: inset 0 0 0 1px rgba(255, 255, 255, 0.08);
+}
+
+.platform-game-loading--panel .platform-game-loading__cover {
+  background: rgba(199, 101, 61, 0.1);
+  box-shadow: inset 0 0 0 1px var(--platform-surface-border, rgba(226, 203, 184, 0.88));
+}
+
+.platform-game-loading__cover img {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
+/*
+ * 宿主自己的封面组件（例如游玩页的 `.game-cover`）带自己的最小高度与内边距；加载面只借
+ * 它的图，盒子尺寸一律由加载面决定，否则封面会把封面槽撑破。
+ */
+.platform-game-loading__cover > * {
+  width: 100%;
+  height: 100%;
+  min-height: 0;
+  border-radius: inherit;
+}
+
+.platform-game-loading__cover svg {
+  width: 2.4rem;
+  height: 2.4rem;
+  opacity: 0.55;
+}
+
+.platform-game-loading__copy {
+  display: grid;
+  min-width: 0;
+  max-width: 26rem;
+  gap: 0.55rem;
+}
+
+.platform-game-loading__title {
+  overflow: hidden;
+  font-size: clamp(1.05rem, 2.2vw, 1.5rem);
+  line-height: 1.3;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.platform-game-loading__message {
+  margin: 0;
+  font-size: 0.85rem;
+  font-weight: 600;
+}
+
+.platform-game-loading--player .platform-game-loading__message {
+  color: rgba(255, 241, 227, 0.78);
+}
+
+.platform-game-loading--panel .platform-game-loading__message {
+  color: var(--platform-text-soft, #988476);
+}
+
+.platform-game-loading__track {
+  position: relative;
+  height: 0.35rem;
+  overflow: hidden;
+  border-radius: 999px;
+}
+
+.platform-game-loading--player .platform-game-loading__track {
+  background: rgba(255, 255, 255, 0.14);
+}
+
+.platform-game-loading--panel .platform-game-loading__track {
+  background: var(--platform-track-fill, rgba(226, 203, 184, 0.45));
+}
+
+.platform-game-loading__fill {
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  width: 38%;
+  border-radius: inherit;
+  animation: platform-game-loading-sweep 1.2s ease-in-out infinite;
+}
+
+.platform-game-loading--player .platform-game-loading__fill {
+  background: linear-gradient(90deg, rgba(255, 196, 150, 0.4), #ffb27a);
+}
+
+.platform-game-loading--panel .platform-game-loading__fill {
+  background: var(--platform-button-primary-fill, #c7653d);
+}
+
+.platform-game-loading__hint {
+  margin: 0;
+  font-size: 0.72rem;
+}
+
+.platform-game-loading--player .platform-game-loading__hint {
+  color: rgba(255, 241, 227, 0.6);
+}
+
+.platform-game-loading--panel .platform-game-loading__hint {
+  color: var(--platform-text-muted, #a38f80);
+}
+
+@keyframes platform-game-loading-sweep {
+  from {
+    transform: translateX(-110%);
+  }
+  to {
+    transform: translateX(280%);
+  }
+}
+
+@media (max-width: 560px) {
+  .platform-game-loading {
+    align-content: safe center;
+    text-align: center;
+  }
+  .platform-game-loading__copy {
+    max-width: 100%;
+  }
+  .platform-game-loading__track {
+    margin: 0 auto;
+    width: min(14rem, 100%);
+  }
+}
diff --git a/scripts/check-game-distribution-ops-rollback-e2e.mjs b/scripts/check-game-distribution-ops-rollback-e2e.mjs
index 28ae7af44..9b89b0408 100644
--- a/scripts/check-game-distribution-ops-rollback-e2e.mjs
+++ b/scripts/check-game-distribution-ops-rollback-e2e.mjs
@@ -18,6 +18,7 @@
 //   E2E_ADMIN_USER=... E2E_ADMIN_PASSWORD=... npm run check:game-distribution-ops-rollback-e2e
 import { createHash, randomBytes } from 'node:crypto';
 import { readdirSync, readFileSync, statSync } from 'node:fs';
+import http from 'node:http';
 import path from 'node:path';
 
 import JSZip from 'jszip';
@@ -99,6 +100,37 @@ async function release(pathname) {
   return { status: response.status, body, headers: response.headers };
 }
 
+/// 原样请求（不自动解压）：压缩与条件请求必须看真实线字节，不能让 fetch 帮忙解码。
+function releaseRaw(pathname, { acceptEncoding, ifNoneMatch } = {}) {
+  return new Promise((resolve, reject) => {
+    const target = new URL(`${API}${pathname}`);
+    const headers = {};
+    if (acceptEncoding) headers['accept-encoding'] = acceptEncoding;
+    if (ifNoneMatch) headers['if-none-match'] = ifNoneMatch;
+    const request = http.request(
+      {
+        hostname: target.hostname,
+        port: target.port,
+        path: `${target.pathname}${target.search}`,
+        headers,
+      },
+      (response) => {
+        const chunks = [];
+        response.on('data', (chunk) => chunks.push(chunk));
+        response.on('end', () =>
+          resolve({
+            status: response.statusCode,
+            headers: response.headers,
+            body: Buffer.concat(chunks),
+          }),
+        );
+      },
+    );
+    request.on('error', reject);
+    request.end();
+  });
+}
+
 async function adminToken() {
   const login = await api('/admin/api/login', {
     method: 'POST',
@@ -397,6 +429,47 @@ async function main() {
   );
   assertReleaseHeaders('v1 CSS', baselineCss, { html: false });
 
+  // 传输与条件请求契约：引擎包动辄 1 MiB 以上，文本资源必须按 Accept-Encoding 压缩，
+  // 并在 60 秒缓存窗口之后靠 ETag 重验证（304）而不是重下整包。
+  const releasePath = `/api/game-distribution/releases/${gameId}/index.html`;
+  const compressedHtml = await releaseRaw(releasePath, {
+    acceptEncoding: 'gzip',
+  });
+  check(
+    '发行文本资源按 Accept-Encoding 压缩并声明 Vary',
+    compressedHtml.status === 200 &&
+      compressedHtml.headers['content-encoding'] === 'gzip' &&
+      String(compressedHtml.headers.vary ?? '').includes('accept-encoding') &&
+      compressedHtml.body.length < Buffer.byteLength(baselineRelease.body),
+    `encoding=${compressedHtml.headers['content-encoding'] ?? ''} vary=${compressedHtml.headers.vary ?? ''} bytes=${compressedHtml.body.length}/${Buffer.byteLength(baselineRelease.body)}`,
+  );
+  const releaseEtag = baselineRelease.headers.get('etag') ?? '';
+  check(
+    '发行资源下发强 ETag',
+    /^"[0-9a-f]{32}"$/u.test(releaseEtag),
+    `etag=${releaseEtag}`,
+  );
+  const revalidated = await releaseRaw(releasePath, {
+    ifNoneMatch: releaseEtag,
+  });
+  check(
+    'If-None-Match 命中时返回 304 且不带正文',
+    revalidated.status === 304 &&
+      revalidated.body.length === 0 &&
+      revalidated.headers['cache-control'] === RELEASE_CACHE_CONTROL &&
+      revalidated.headers.etag === releaseEtag,
+    `status=${revalidated.status} body=${revalidated.body.length} cache-control=${revalidated.headers['cache-control'] ?? ''}`,
+  );
+  const identityHtml = await releaseRaw(releasePath, {
+    acceptEncoding: 'identity',
+  });
+  check(
+    '客户端不接受 gzip 时不下发压缩体',
+    identityHtml.status === 200 &&
+      identityHtml.headers['content-encoding'] === undefined,
+    `encoding=${identityHtml.headers['content-encoding'] ?? ''}`,
+  );
+
   const pendingIds = {};
   for (const marker of ['V2-OK', 'V3-OK']) {
     const built = await buildPackage(marker);
diff --git a/server-rs/Cargo.lock b/server-rs/Cargo.lock
index ea9aba518..ce39c0b95 100644
--- a/server-rs/Cargo.lock
+++ b/server-rs/Cargo.lock
@@ -208,6 +208,7 @@ dependencies = [
  "bytes",
  "cbc",
  "dotenvy",
+ "flate2",
  "futures-util",
  "hex",
  "hmac",
diff --git a/server-rs/crates/api-server/Cargo.toml b/server-rs/crates/api-server/Cargo.toml
index 6292a9490..a3c78d255 100644
--- a/server-rs/crates/api-server/Cargo.toml
+++ b/server-rs/crates/api-server/Cargo.toml
@@ -12,6 +12,7 @@ base64 = { workspace = true }
 cbc = { workspace = true }
 bytes = { workspace = true }
 dotenvy = { workspace = true }
+flate2 = { workspace = true }
 hex = { workspace = true }
 image = { workspace = true, features = ["jpeg", "png", "webp"] }
 http-body-util = { workspace = true }
diff --git a/server-rs/crates/api-server/src/modules/game_distribution.rs b/server-rs/crates/api-server/src/modules/game_distribution.rs
index bc7905ed6..f666868b9 100644
--- a/server-rs/crates/api-server/src/modules/game_distribution.rs
+++ b/server-rs/crates/api-server/src/modules/game_distribution.rs
@@ -1,5 +1,6 @@
 use std::{
     collections::{BTreeMap, HashMap, VecDeque},
+    io::Write,
     sync::{Arc, Mutex, OnceLock},
     time::{Instant, SystemTime, UNIX_EPOCH},
 };
@@ -16,6 +17,7 @@ use axum::{
     response::Response,
     routing::{get, post, put},
 };
+use flate2::{Compression as GzipCompression, write::GzEncoder};
 use module_game_distribution::{
     MAX_PACKAGE_BYTES, ReleaseAssetError, ReleasePackageError, ReleasePackageManifest,
     compute_request_digest, extract_release_asset, normalize_review_comment,
@@ -30,6 +32,7 @@ use platform_oss::{
 };
 use serde::Deserialize;
 use serde_json::{Value, json};
+use sha2::{Digest, Sha256};
 use shared_contracts::admin::{
     AdminGameReview, AdminGameReviewDetailResponse, AdminGameReviewGame, AdminGameReviewGameInfo,
     AdminGameReviewGamesQuery, AdminGameReviewGamesResponse, AdminGameReviewModerationRequest,
@@ -863,19 +866,103 @@ async fn serve_release_asset(
         return Err(AppError::from_status(StatusCode::NOT_FOUND));
     }
     let package = release_package_bytes(&state, &game_id, &version.version_id).await?;
+    let etag = release_asset_etag(&version.version_id, &asset_path);
     release_package_asset_response(
         &package,
         &asset_path,
-        content_type,
-        "public, max-age=60, must-revalidate",
+        ReleaseAssetResponseInput {
+            content_type,
+            cache_control: "public, max-age=60, must-revalidate",
+            etag: Some(&etag),
+            if_none_match: headers.get(header::IF_NONE_MATCH),
+            accept_encoding: headers.get(header::ACCEPT_ENCODING),
+        },
     )
 }
+/// 单次发行资源响应的输入：内容类型、缓存策略、条件请求与压缩协商。
+struct ReleaseAssetResponseInput<'a> {
+    content_type: &'static str,
+    cache_control: &'static str,
+    /// 为空表示该响应不可缓存（后台试玩会话是 `no-store`），条件请求与 ETag 都不参与。
+    etag: Option<&'a str>,
+    if_none_match: Option<&'a HeaderValue>,
+    accept_encoding: Option<&'a HeaderValue>,
+}
+
+/// 低于这个字节数的响应不做 gzip：压缩头与字典开销会把收益吃掉。
+const RELEASE_COMPRESSION_MIN_BYTES: usize = 1024;
+
+/// 发行资源的强 ETag：同一版本同一路径的字节在包被冻结后不会改变。
+///
+/// 用摘要而不是拼字符串：资源路径来自 URL，可能带上 ETag 的保留字符（引号、反斜杠）。
+fn release_asset_etag(version_id: &str, asset_path: &str) -> String {
+    let mut hasher = Sha256::new();
+    hasher.update(version_id.as_bytes());
+    hasher.update([0]);
+    hasher.update(asset_path.as_bytes());
+    let digest = hasher.finalize();
+    format!("\"{}\"", hex::encode(&digest[..16]))
+}
+
+/// `If-None-Match` 命中判定：支持 `*`、弱校验前缀 `W/` 与逗号分隔列表。
+fn if_none_match_matches(header: Option<&HeaderValue>, etag: &str) -> bool {
+    let Some(value) = header.and_then(|value| value.to_str().ok()) else {
+        return false;
+    };
+    value.split(',').any(|candidate| {
+        let candidate = candidate.trim();
+        candidate == "*" || candidate.trim_start_matches("W/") == etag
+    })
+}
+
+/// 客户端是否接受 gzip；`gzip;q=0` 与 `*;q=0` 表示明确拒绝。
+fn accepts_gzip_encoding(header: Option<&HeaderValue>) -> bool {
+    let Some(value) = header.and_then(|value| value.to_str().ok()) else {
+        return false;
+    };
+    value.split(',').any(|entry| {
+        let mut parts = entry.split(';');
+        let coding = parts.next().unwrap_or_default().trim();
+        if !coding.eq_ignore_ascii_case("gzip") && coding != "*" {
+            return false;
+        }
+        !parts.any(|parameter| {
+            parameter
+                .trim()
+                .strip_prefix("q=")
+                .and_then(|value| value.trim().parse::<f32>().ok())
+                .is_some_and(|quality| quality <= 0.0)
+        })
+    })
+}
+
+/// 只压文本类发行资源；图片、音频、视频本身已是压缩格式，再压一遍只是浪费 CPU。
+fn is_compressible_release_content_type(content_type: &str) -> bool {
+    content_type.starts_with("text/")
+        || content_type.contains("javascript")
+        || content_type.contains("json")
+        || content_type.contains("svg")
+        || content_type.contains("application/wasm")
+}
+
+fn gzip_release_asset(content: &[u8]) -> Option<Vec<u8>> {
+    let mut encoder = GzEncoder::new(Vec::new(), GzipCompression::new(6));
+    encoder.write_all(content).ok()?;
+    encoder.finish().ok()
+}
+
 fn release_package_asset_response(
     package: &[u8],
     asset_path: &str,
-    content_type: &'static str,
-    cache_control: &'static str,
+    input: ReleaseAssetResponseInput<'_>,
 ) -> Result<Response, AppError> {
+    let ReleaseAssetResponseInput {
+        content_type,
+        cache_control,
+        etag,
+        if_none_match,
+        accept_encoding,
+    } = input;
     let content = match extract_release_asset(package, asset_path) {
         Ok(content) => content,
         Err(ReleaseAssetError::FileTooLarge) => {
@@ -884,12 +971,32 @@ fn release_package_asset_response(
         }
         Err(_) => return Err(AppError::from_status(StatusCode::NOT_FOUND)),
     };
+    // 条件请求必须在确认资源存在于包内之后判定：`If-None-Match: *` 只表示「任一份表示
+    // 存在就复用」，对包内不存在的路径仍要 404。
+    if let Some(etag) = etag
+        && if_none_match_matches(if_none_match, etag)
+    {
+        return Ok(release_asset_not_modified_response(etag, cache_control));
+    }
     let content = normalize_release_asset_references(content, content_type);
     let content = inject_release_storage_bootstrap(content, content_type);
+    // 发行包里的字节是 ZIP 解压后的原文：不压缩时 Phaser 4 的 1.31 MiB 引擎包会原样
+    // 走完用户网络，而它在包内本来就是 deflate 压缩的。
+    let compressed = (accepts_gzip_encoding(accept_encoding)
+        && is_compressible_release_content_type(content_type)
+        && content.len() >= RELEASE_COMPRESSION_MIN_BYTES)
+        .then(|| gzip_release_asset(&content))
+        .flatten();
+    let (body, content_encoding) = match compressed {
+        Some(compressed) => (compressed, Some("gzip")),
+        None => (content, None),
+    };
     Ok(release_asset_response_with_cache(
-        content,
+        body,
         content_type,
         cache_control,
+        etag,
+        content_encoding,
     ))
 }
 
@@ -964,6 +1071,8 @@ fn release_asset_response_with_cache(
     content: Vec<u8>,
     content_type: &'static str,
     cache_control: &'static str,
+    etag: Option<&str>,
+    content_encoding: Option<&'static str>,
 ) -> Response {
     let mut response = Response::new(Body::from(content));
     let headers = response.headers_mut();
@@ -980,6 +1089,20 @@ fn release_asset_response_with_cache(
         header::CACHE_CONTROL,
         HeaderValue::from_static(cache_control),
     );
+    // 发行资源可能带 gzip 表示；共享缓存必须按 Accept-Encoding 分桶，否则会把压缩体
+    // 发给不支持它的客户端。
+    headers.insert(header::VARY, HeaderValue::from_static("accept-encoding"));
+    if let Some(etag) = etag {
+        if let Ok(value) = HeaderValue::from_str(etag) {
+            headers.insert(header::ETAG, value);
+        }
+    }
+    if let Some(content_encoding) = content_encoding {
+        headers.insert(
+            header::CONTENT_ENCODING,
+            HeaderValue::from_static(content_encoding),
+        );
+    }
     // 发行文档运行在 allow-scripts 的 opaque origin 沙箱里，其同包资源请求不再与
     // 网关同源；CORP 必须允许跨来源，ES modules 还需要不带 credentials 的 CORS，
     // 否则游戏自己的脚本会被浏览器拦下（实测 net::ERR_BLOCKED_BY_RESPONSE）。
@@ -1004,6 +1127,25 @@ fn release_asset_response_with_cache(
     response
 }
 
+/// 条件请求命中：只回报校验器与缓存策略，不带正文。
+///
+/// 发行包在版本冻结后不可变，浏览器在 `max-age=60, must-revalidate` 之后只要拿到同一个
+/// ETag 就能停在 304，不必把整个引擎包再下一次。
+fn release_asset_not_modified_response(etag: &str, cache_control: &'static str) -> Response {
+    let mut response = Response::new(Body::empty());
+    *response.status_mut() = StatusCode::NOT_MODIFIED;
+    let headers = response.headers_mut();
+    headers.insert(
+        header::CACHE_CONTROL,
+        HeaderValue::from_static(cache_control),
+    );
+    headers.insert(header::VARY, HeaderValue::from_static("accept-encoding"));
+    if let Ok(value) = HeaderValue::from_str(etag) {
+        headers.insert(header::ETAG, value);
+    }
+    response
+}
+
 async fn list_games(
     State(state): State<AppState>,
     Extension(ctx): Extension<RequestContext>,
@@ -2587,7 +2729,18 @@ async fn serve_admin_version_preview_asset_inner(
         return Err(AppError::from_status(StatusCode::NOT_FOUND));
     }
     let package = release_package_bytes(&state, &version.game_id, &version.version_id).await?;
-    release_package_asset_response(&package, &asset_path, content_type, "no-store")
+    // 试玩会话是短期私有预览：不给 ETag，也不允许任何缓存。
+    release_package_asset_response(
+        &package,
+        &asset_path,
+        ReleaseAssetResponseInput {
+            content_type,
+            cache_control: "no-store",
+            etag: None,
+            if_none_match: None,
+            accept_encoding: headers.get(header::ACCEPT_ENCODING),
+        },
+    )
 }
 
 /// 审核通过时派生的发行入口：平台同源路径 `/games/{gameId}/`。
@@ -4687,6 +4840,8 @@ mod tests {
             b"x".to_vec(),
             "text/javascript; charset=utf-8",
             "public, max-age=60, must-revalidate",
+            None,
+            None,
         );
         assert_eq!(
             response
@@ -4748,6 +4903,8 @@ mod tests {
             b"<html></html>".to_vec(),
             "text/html; charset=utf-8",
             "public, max-age=60, must-revalidate",
+            None,
+            None,
         );
         assert_eq!(
             html.headers().get(header::X_CONTENT_TYPE_OPTIONS).unwrap(),
@@ -4759,6 +4916,8 @@ mod tests {
             vec![1, 2, 3],
             "image/png",
             "public, max-age=60, must-revalidate",
+            None,
+            None,
         );
         assert_eq!(
             image.headers().get(header::CONTENT_TYPE).unwrap(),
@@ -4771,6 +4930,278 @@ mod tests {
         );
     }
 
+    #[test]
+    fn release_asset_etag_is_scoped_to_version_and_path() {
+        let etag = release_asset_etag("version_1", "assets/phaser.min.js");
+        assert_eq!(etag, release_asset_etag("version_1", "assets/phaser.min.js"));
+        assert_ne!(etag, release_asset_etag("version_2", "assets/phaser.min.js"));
+        assert_ne!(etag, release_asset_etag("version_1", "assets/game.js"));
+        assert!(etag.starts_with('"'), "ETag 必须是带引号的实体标记：{etag}");
+    }
+
+    #[test]
+    fn release_asset_conditional_request_matches_lists_and_weak_validators() {
+        let etag = "\"abc\"";
+        for accepted in ["*", "\"abc\"", "W/\"abc\"", "\"zzz\", \"abc\"", " W/\"abc\" "] {
+            assert!(
+                if_none_match_matches(
+                    Some(&HeaderValue::from_str(accepted).expect("header")),
+                    etag
+                ),
+                "应命中的 If-None-Match：{accepted}"
+            );
+        }
+        for rejected in ["\"zzz\"", "", "\"abcd\""] {
+            assert!(
+                !if_none_match_matches(
+                    Some(&HeaderValue::from_str(rejected).expect("header")),
+                    etag
+                ),
+                "不应命中的 If-None-Match：{rejected}"
+            );
+        }
+        assert!(!if_none_match_matches(None, etag));
+    }
+
+    #[test]
+    fn release_asset_gzip_acceptance_honours_quality_zero() {
+        for accepted in ["gzip", "GZIP", "*", "br, gzip;q=0.8", "deflate, gzip"] {
+            assert!(
+                accepts_gzip_encoding(Some(
+                    &HeaderValue::from_str(accepted).expect("header")
+                )),
+                "应接受 gzip：{accepted}"
+            );
+        }
+        for rejected in ["", "br", "gzip;q=0", "*;q=0.0", "identity"] {
+            assert!(
+                !accepts_gzip_encoding(Some(
+                    &HeaderValue::from_str(rejected).expect("header")
+                )),
+                "不应接受 gzip：{rejected}"
+            );
+        }
+        assert!(!accepts_gzip_encoding(None));
+    }
+
+    /// 造一个最小发行包：条目内容是给定字节。
+    fn release_package_fixture(asset_name: &str, asset_body: &[u8]) -> Vec<u8> {
+        let mut buffer = std::io::Cursor::new(Vec::new());
+        {
+            let mut writer = zip::ZipWriter::new(&mut buffer);
+            writer
+                .start_file(
+                    asset_name,
+                    zip::write::SimpleFileOptions::default()
+                        .compression_method(zip::CompressionMethod::Deflated),
+                )
+                .expect("zip entry");
+            writer.write_all(asset_body).expect("zip body");
+            writer.finish().expect("finish zip");
+        }
+        buffer.into_inner()
+    }
+
+    async fn release_response_body(response: Response) -> Vec<u8> {
+        axum::body::to_bytes(response.into_body(), usize::MAX)
+            .await
+            .expect("响应正文")
+            .to_vec()
+    }
+
+    fn gunzip(bytes: &[u8]) -> Vec<u8> {
+        use std::io::Read;
+
+        let mut decoder = flate2::read::GzDecoder::new(bytes);
+        let mut decoded = Vec::new();
+        decoder.read_to_end(&mut decoded).expect("解压 gzip");
+        decoded
+    }
+
+    #[tokio::test]
+    async fn release_asset_response_gzips_accepted_text_and_keeps_binary_untouched() {
+        let script = "console.log('genarrative-game');\n".repeat(64);
+        let package = release_package_fixture("assets/game.js", script.as_bytes());
+        let gzip = HeaderValue::from_static("gzip, deflate, br");
+        let cache_control = "public, max-age=60, must-revalidate";
+
+        let compressed = release_package_asset_response(
+            &package,
+            "assets/game.js",
+            ReleaseAssetResponseInput {
+                content_type: "text/javascript; charset=utf-8",
+                cache_control,
+                etag: None,
+                if_none_match: None,
+                accept_encoding: Some(&gzip),
+            },
+        )
+        .expect("压缩发行资源");
+        assert_eq!(
+            compressed
+                .headers()
+                .get(header::CONTENT_ENCODING)
+                .expect("Content-Encoding"),
+            "gzip"
+        );
+        assert_eq!(
+            compressed.headers().get(header::VARY).expect("Vary"),
+            "accept-encoding"
+        );
+        let body = release_response_body(compressed).await;
+        assert_eq!(gunzip(&body), script.as_bytes());
+        assert!(body.len() < script.len() / 2, "gzip 应显著小于原文");
+
+        let identity = release_package_asset_response(
+            &package,
+            "assets/game.js",
+            ReleaseAssetResponseInput {
+                content_type: "text/javascript; charset=utf-8",
+                cache_control,
+                etag: None,
+                if_none_match: None,
+                accept_encoding: None,
+            },
+        )
+        .expect("未协商压缩");
+        assert!(
+            !identity.headers().contains_key(header::CONTENT_ENCODING),
+            "客户端不接受 gzip 时不得下发压缩体"
+        );
+        assert_eq!(release_response_body(identity).await, script.as_bytes());
+
+        // 小文件不值得压：头与字典开销会把收益吃掉，而且不能被贴上 gzip 标记。
+        let tiny_package = release_package_fixture("assets/tiny.js", b"console.log(1);");
+        let tiny = release_package_asset_response(
+            &tiny_package,
+            "assets/tiny.js",
+            ReleaseAssetResponseInput {
+                content_type: "text/javascript; charset=utf-8",
+                cache_control,
+                etag: None,
+                if_none_match: None,
+                accept_encoding: Some(&gzip),
+            },
+        )
+        .expect("小文件响应");
+        assert!(!tiny.headers().contains_key(header::CONTENT_ENCODING));
+
+        // 图片本身已是压缩格式，再压一遍只是浪费 CPU。
+        let image_bytes = vec![7_u8; 4096];
+        let image_package = release_package_fixture("assets/hero.png", &image_bytes);
+        let image = release_package_asset_response(
+            &image_package,
+            "assets/hero.png",
+            ReleaseAssetResponseInput {
+                content_type: "image/png",
+                cache_control,
+                etag: None,
+                if_none_match: None,
+                accept_encoding: Some(&gzip),
+            },
+        )
+        .expect("图片响应");
+        assert!(!image.headers().contains_key(header::CONTENT_ENCODING));
+        assert_eq!(release_response_body(image).await, image_bytes);
+    }
+
+    #[tokio::test]
+    async fn release_asset_response_answers_matching_etag_with_304() {
+        let script = "console.log('genarrative-game');\n".repeat(64);
+        let package = release_package_fixture("assets/game.js", script.as_bytes());
+        let etag = release_asset_etag("version_1", "assets/game.js");
+        let cache_control = "public, max-age=60, must-revalidate";
+        let conditional = HeaderValue::from_str(&etag).expect("etag header");
+
+        let served = release_package_asset_response(
+            &package,
+            "assets/game.js",
+            ReleaseAssetResponseInput {
+                content_type: "text/javascript; charset=utf-8",
+                cache_control,
+                etag: Some(&etag),
+                if_none_match: None,
+                accept_encoding: None,
+            },
+        )
+        .expect("首次响应");
+        assert_eq!(served.headers().get(header::ETAG).expect("ETag"), etag.as_str());
+        assert_eq!(
+            served.headers().get(header::CACHE_CONTROL).expect("缓存策略"),
+            cache_control
+        );
+
+        let not_modified = release_package_asset_response(
+            &package,
+            "assets/game.js",
+            ReleaseAssetResponseInput {
+                content_type: "text/javascript; charset=utf-8",
+                cache_control,
+                etag: Some(&etag),
+                if_none_match: Some(&conditional),
+                accept_encoding: None,
+            },
+        )
+        .expect("条件请求");
+        assert_eq!(not_modified.status(), StatusCode::NOT_MODIFIED);
+        assert_eq!(
+            not_modified.headers().get(header::CACHE_CONTROL).expect("缓存策略"),
+            cache_control
+        );
+        assert_eq!(
+            not_modified.headers().get(header::ETAG).expect("ETag"),
+            etag.as_str()
+        );
+        assert!(release_response_body(not_modified).await.is_empty());
+
+        let stale = HeaderValue::from_static("\"stale\"");
+        let refreshed = release_package_asset_response(
+            &package,
+            "assets/game.js",
+            ReleaseAssetResponseInput {
+                content_type: "text/javascript; charset=utf-8",
+                cache_control,
+                etag: Some(&etag),
+                if_none_match: Some(&stale),
+                accept_encoding: None,
+            },
+        )
+        .expect("过期校验器");
+        assert_eq!(refreshed.status(), StatusCode::OK);
+        assert_eq!(release_response_body(refreshed).await, script.as_bytes());
+
+        // `*` 也需要资源真的在包内：包内没有的路径必须 404，不能用 304 糊过去。
+        let wildcard = HeaderValue::from_static("*");
+        let wildcard_hit = release_package_asset_response(
+            &package,
+            "assets/game.js",
+            ReleaseAssetResponseInput {
+                content_type: "text/javascript; charset=utf-8",
+                cache_control,
+                etag: Some(&etag),
+                if_none_match: Some(&wildcard),
+                accept_encoding: None,
+            },
+        )
+        .expect("通配校验器");
+        assert_eq!(wildcard_hit.status(), StatusCode::NOT_MODIFIED);
+
+        let missing_etag = release_asset_etag("version_1", "assets/missing.js");
+        let missing = release_package_asset_response(
+            &package,
+            "assets/missing.js",
+            ReleaseAssetResponseInput {
+                content_type: "text/javascript; charset=utf-8",
+                cache_control,
+                etag: Some(&missing_etag),
+                if_none_match: Some(&wildcard),
+                accept_encoding: None,
+            },
+        )
+        .expect_err("包内不存在的路径必须 404");
+        assert_eq!(missing.status_code(), StatusCode::NOT_FOUND);
+    }
+
     #[test]
     fn release_package_cache_evicts_by_entry_and_byte_budget() {
         let mut cache = ReleasePackageCache::default();
diff --git a/src/components/game-distribution/GameDistributionPages.test.tsx b/src/components/game-distribution/GameDistributionPages.test.tsx
index 4ecd4ebc3..d3b2e52c6 100644
--- a/src/components/game-distribution/GameDistributionPages.test.tsx
+++ b/src/components/game-distribution/GameDistributionPages.test.tsx
@@ -464,6 +464,28 @@ describe('GamePlayPage', () => {
     expect(recordGamePlayMock).toHaveBeenCalledWith('game-1');
   });
 
+  it('shows the shared loading surface until the release frame is ready', async () => {
+    render(<GamePlayPage gameId="game-1" onBack={vi.fn()} />);
+
+    await screen.findByRole('button', { name: /开始游戏/u });
+    fireEvent.click(screen.getByRole('button', { name: /开始游戏/u }));
+    const iframe = await screen.findByTitle('星轨防线 在线游玩');
+
+    // 发行包首屏要下完整个引擎：加载期必须有看得见的加载面，而不是一行小字或黑屏。
+    const loadingSurface = screen.getByRole('status');
+    expect(loadingSurface.textContent).toContain('星轨防线');
+    expect(
+      loadingSurface.classList.contains('platform-game-loading--player'),
+    ).toBe(true);
+    expect(
+      loadingSurface.querySelector('.platform-game-loading__track'),
+    ).not.toBeNull();
+
+    fireEvent.load(iframe);
+    expect(screen.queryByRole('status')).toBeNull();
+    expect(iframe.className.includes('game-player-frame--ready')).toBe(true);
+  });
+
   it('rejects an unsafe release entry URL before rendering an iframe', async () => {
     getGameMock.mockResolvedValueOnce(
       createGame({
diff --git a/src/components/game-distribution/GamePlayPage.tsx b/src/components/game-distribution/GamePlayPage.tsx
index f4f1efebd..ce560566f 100644
--- a/src/components/game-distribution/GamePlayPage.tsx
+++ b/src/components/game-distribution/GamePlayPage.tsx
@@ -1,5 +1,9 @@
 import './gameDistribution.css';
 
+import {
+  PLATFORM_GAME_LOADING_TIMEOUT_MS,
+  PlatformGameLoadingSurface,
+} from '@genarrative/shared/components';
 import {
   ArrowLeft,
   Expand,
@@ -26,8 +30,11 @@ import { GameCover } from './GameGalleryPage';
 
 type GamePlayPageProps = { gameId: string | null; onBack: () => void };
 
-/** 发行包首屏加载上限：超过后给出显式超时与重试，不用无限期“正在启动”。 */
-export const GAME_PLAY_STARTUP_TIMEOUT_MS = 20_000;
+/**
+ * 发行包首屏加载上限：超过后给出显式超时与重试，不用无限期等待。
+ * 与后台审核试玩共用同一口径（`PLATFORM_GAME_LOADING_TIMEOUT_MS`）。
+ */
+export const GAME_PLAY_STARTUP_TIMEOUT_MS = PLATFORM_GAME_LOADING_TIMEOUT_MS;
 
 type GameStartupState = 'idle' | 'loading' | 'ready' | 'timeout';
 
@@ -212,7 +219,12 @@ export function GamePlayPage({ gameId, onBack }: GamePlayPageProps) {
           </div>
         ) : null}
         {hasStarted && startupState === 'loading' ? (
-          <div className="game-player-loading">游戏正在启动…</div>
+          <PlatformGameLoadingSurface
+            key={`game-loading-${frameRunId}`}
+            tone="player"
+            title={game.title}
+            cover={<GameCover game={game} compact />}
+          />
         ) : null}
         {hasStarted && startupState === 'timeout' ? (
           <PlatformStatusMessage
diff --git a/src/components/game-distribution/gameDistribution.css b/src/components/game-distribution/gameDistribution.css
index ea2a86285..e3d692bf0 100644
--- a/src/components/game-distribution/gameDistribution.css
+++ b/src/components/game-distribution/gameDistribution.css
@@ -517,15 +517,6 @@
 .game-player-frame--ready {
   opacity: 1;
 }
-.game-player-loading {
-  position: absolute;
-  inset: 0;
-  display: grid;
-  place-items: center;
-  color: rgba(255, 241, 227, 0.75);
-  font-size: 0.88rem;
-  font-weight: 700;
-}
 .game-play-safety-note {
   margin: 0;
   color: var(--platform-text-soft);
@@ -645,7 +636,6 @@
     -webkit-box-orient: vertical;
     -webkit-line-clamp: 2;
   }
-  .game-player-loading,
   .game-player-timeout {
     font-size: 0.8rem;
   }