From d26f470d57afecd52b9bb7fa3f2f66f89b84ad41 Mon Sep 17 00:00:00 2001
From: yourname <yourname@email.com>
Date: Wed, 8 Apr 2026 04:36:17 +0000
Subject: [PATCH] =?UTF-8?q?sync:=20=E6=B7=BB=E5=8A=A0=20HMR=20=E9=99=8D?=
 =?UTF-8?q?=E7=BA=A7=E7=AD=96=E7=95=A5=20=C2=A77.1=20=E2=80=94=20E2E=20?=
 =?UTF-8?q?=E6=B5=8B=E8=AF=95=E6=97=B6=20next=20dev=20=E2=86=92=20next=20s?=
 =?UTF-8?q?tart?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .claude/skills/d8d-dev/phase-00-setup.md      |  7 +++
 .../d8d-dev/reference/platform-nextjs.md      | 48 +++++++++++++++++++
 2 files changed, 55 insertions(+)

diff --git a/.claude/skills/d8d-dev/phase-00-setup.md b/.claude/skills/d8d-dev/phase-00-setup.md
index 13d0ad4..73ff3a0 100644
--- a/.claude/skills/d8d-dev/phase-00-setup.md
+++ b/.claude/skills/d8d-dev/phase-00-setup.md
@@ -66,6 +66,13 @@
      }
      ```
    - 标记：Epic 0 完成后此文件才可生效（项目目录需先存在）
+   - ⛔ **HMR 降级策略**：外网域名 E2E 测试/旅程验证时，如果 HMR WebSocket 失败（控制台 `webpack-hmr` 错误），必须切换到生产模式：
+     ```bash
+     npx next build
+     pm2 stop app && pm2 delete app
+     pm2 start "npx next start --port 3001" --name app
+     ```
+     详见 `./reference/platform-nextjs.md` §7.1
 
 4.5. **外网域名发现与连通性验证（NPM MCP）**
    - project-slug 推导规则：取项目根目录名（basename of pwd），追加 `-group` 后缀
diff --git a/.claude/skills/d8d-dev/reference/platform-nextjs.md b/.claude/skills/d8d-dev/reference/platform-nextjs.md
index 6026419..9f0f498 100644
--- a/.claude/skills/d8d-dev/reference/platform-nextjs.md
+++ b/.claude/skills/d8d-dev/reference/platform-nextjs.md
@@ -231,6 +231,54 @@ NPM 代理主机默认配置会阻断 WebSocket，导致：
 
 `get_proxy_host` 确认：`block_exploits: false` + `allow_websocket_upgrade: true`
 
+### §7.1 HMR 降级策略（⛔ E2E 测试/旅程验证时强制）
+
+#### 问题描述
+
+即使 NPM 代理已正确配置（`block_exploits: false` + `allow_websocket_upgrade: true`），
+通过外网域名访问 `next dev` 时 HMR WebSocket 仍可能失败（握手阶段 Invalid status line）。
+这导致：
+- 浏览器控制台持续 `WebSocket connection to 'ws://.../_next/webpack-hmr' failed: Error during WebSocket handshake`
+- React 状态被 HMR 重连机制重置（表单值丢失）
+- Playwright E2E 测试中 `browser_type` 填入的值被清空
+
+**生产模式（`next start`）不依赖 WebSocket/HMR，不受此问题影响。**
+
+#### 检测条件
+
+满足以下条件时触发降级：
+1. 浏览器控制台出现 HMR WebSocket 连接失败错误
+2. NPM 代理已正确配置（`allow_websocket_upgrade: true`）
+3. 正在执行 E2E 测试或旅程验证
+
+#### 降级步骤
+
+```bash
+# 1. 构建生产版本
+npx next build
+
+# 2. 停止 dev 进程，启动生产模式
+pm2 stop app && pm2 delete app
+pm2 start "npx next start --port 3001" --name app
+
+# 3. 等待启动完成
+sleep 3 && curl -sf --max-time 5 http://localhost:3001 -o /dev/null -w "%{http_code}"
+```
+
+#### 回退到开发模式
+
+E2E 测试/旅程验证完成后，如需恢复热重载开发：
+```bash
+pm2 stop app && pm2 delete app
+pm2 start "npx next dev --port 3001" --name app
+```
+
+#### 注意事项
+
+- **代码修改后需重新 build**：生产模式下修改源码不会自动生效，必须 `next build` 后重启
+- **E2E/旅程验证优先用 `next start`**：避免 HMR 干扰测试稳定性
+- **开发调试用 `next dev`**：需要热重载时使用，通过 localhost 访问可避免 HMR 问题
+
 ---
 
 ## 8. MinIO 外网地址配置（⛔ 强制）