From 6031c689de45571e62f03ec79ee61ffd1d3b9f31 Mon Sep 17 00:00:00 2001
From: yourname <yourname@email.com>
Date: Sun, 12 Apr 2026 02:31:23 +0000
Subject: [PATCH] =?UTF-8?q?sync:=20=E6=B7=BB=E5=8A=A0Next.js=20allowedDevO?=
 =?UTF-8?q?rigins=E9=85=8D=E7=BD=AE=E8=AF=B4=E6=98=8E=EF=BC=8C=E6=9B=B4?=
 =?UTF-8?q?=E6=96=B0HMR=E9=99=8D=E7=BA=A7=E7=AD=96=E7=95=A5=20-=20?=
 =?UTF-8?q?=E6=96=B0=E5=A2=9EallowedDevOrigins=E9=85=8D=E7=BD=AE=E8=AF=B4?=
 =?UTF-8?q?=E6=98=8E=EF=BC=8C=E6=94=AF=E6=8C=81=E5=A4=96=E7=BD=91=E5=9F=9F?=
 =?UTF-8?q?=E5=90=8DHMR=E7=83=AD=E9=87=8D=E8=BD=BD=20-=20=E6=9B=B4?=
 =?UTF-8?q?=E6=96=B0HMR=E9=99=8D=E7=BA=A7=E7=AD=96=E7=95=A5=E4=B8=BA?=
 =?UTF-8?q?=E5=A4=87=E9=80=89=E6=96=B9=E6=A1=88=EF=BC=8C=E4=BC=98=E5=85=88?=
 =?UTF-8?q?=E4=BD=BF=E7=94=A8next=20dev=E5=BC=80=E5=8F=91=E4=BD=93?=
 =?UTF-8?q?=E9=AA=8C=E6=9B=B4=E5=A5=BD=20-=20=E9=80=82=E9=85=8DNext.js=201?=
 =?UTF-8?q?5+=E7=9A=84=E6=96=B0=E7=89=B9=E6=80=A7?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .claude/skills/d8d-dev/phase-00-setup.md      | 34 +++++++-
 .../d8d-dev/reference/platform-nextjs.md      | 84 +++++++++++++++++--
 2 files changed, 108 insertions(+), 10 deletions(-)

diff --git a/.claude/skills/d8d-dev/phase-00-setup.md b/.claude/skills/d8d-dev/phase-00-setup.md
index 73ff3a0..3a76ed2 100644
--- a/.claude/skills/d8d-dev/phase-00-setup.md
+++ b/.claude/skills/d8d-dev/phase-00-setup.md
@@ -66,7 +66,11 @@
      }
      ```
    - 标记：Epic 0 完成后此文件才可生效（项目目录需先存在）
-   - ⛔ **HMR 降级策略**：外网域名 E2E 测试/旅程验证时，如果 HMR WebSocket 失败（控制台 `webpack-hmr` 错误），必须切换到生产模式：
+   - ⛔ **HMR 降级策略（备选）**：配置了 `allowedDevOrigins` 后，外网域名的 HMR 通常可以正常工作。仅在以下情况下降级到生产模式：
+     - 配置了 `allowedDevOrigins` 后 HMR 仍失败
+     - 需要最大化测试稳定性（生产模式无 HMR 干扰）
+
+     降级步骤（`next start` 替代 `next dev`）：
      ```bash
      npx next build
      pm2 stop app && pm2 delete app
@@ -188,7 +192,33 @@
    - 此步骤创建的 .env.local 不应提交到 git（应在 .gitignore 中排除）
    - 更新 pipeline-context.md 记录注入状态
 
-4.8. **MinIO 外网地址注入（⛔ 强制）**
+4.8. **Next.js allowedDevOrigins 配置（⛔ 外网域名访问时强制）**
+
+   当通过外网域名（如 `*.dev.d8d.fun`）访问 Next.js 开发服务器时，必须在 `next.config.ts` 中配置 `allowedDevOrigins`，否则会出现 "Invalid Host header" 错误。
+
+   **配置示例**：
+   ```typescript
+   // next.config.ts
+   import type { NextConfig } from "next";
+
+   const nextConfig: NextConfig = {
+     allowedDevOrigins: [
+       "*.dev.d8d.fun",
+       "localhost",
+     ],
+   };
+
+   export default nextConfig;
+   ```
+
+   **配置后重启服务**：
+   ```bash
+   pm2 restart vividspark
+   ```
+
+   详见 `./reference/platform-nextjs.md` §10
+
+4.9. **MinIO 外网地址注入（⛔ 强制）**
 
    检测容器环境变量 `MINIO_HOST`，将外网地址注入到 `.env` 中的 `S3_PUBLIC_URL`：
 
diff --git a/.claude/skills/d8d-dev/reference/platform-nextjs.md b/.claude/skills/d8d-dev/reference/platform-nextjs.md
index 9f0f498..9c8f5d2 100644
--- a/.claude/skills/d8d-dev/reference/platform-nextjs.md
+++ b/.claude/skills/d8d-dev/reference/platform-nextjs.md
@@ -231,11 +231,19 @@ NPM 代理主机默认配置会阻断 WebSocket，导致：
 
 `get_proxy_host` 确认：`block_exploits: false` + `allow_websocket_upgrade: true`
 
-### §7.1 HMR 降级策略（⛔ E2E 测试/旅程验证时强制）
+### §7.1 HMR 降级策略（备选方案）
+
+#### 前置条件
+
+配置了 `allowedDevOrigins` 后，外网域名的 HMR 通常可以正常工作，**不再需要降级到 `next start`**。
+
+仅在以下情况下考虑降级：
+- 配置了 `allowedDevOrigins` 后 HMR 仍失败
+- 需要最大化测试稳定性（生产模式无 HMR 干扰）
 
 #### 问题描述
 
-即使 NPM 代理已正确配置（`block_exploits: false` + `allow_websocket_upgrade: true`），
+即使 NPM 代理已正确配置（`block_exploits: false` + `allow_websocket_upgrade: true`）且已配置 `allowedDevOrigins`，
 通过外网域名访问 `next dev` 时 HMR WebSocket 仍可能失败（握手阶段 Invalid status line）。
 这导致：
 - 浏览器控制台持续 `WebSocket connection to 'ws://.../_next/webpack-hmr' failed: Error during WebSocket handshake`
@@ -246,10 +254,9 @@ NPM 代理主机默认配置会阻断 WebSocket，导致：
 
 #### 检测条件
 
-满足以下条件时触发降级：
-1. 浏览器控制台出现 HMR WebSocket 连接失败错误
-2. NPM 代理已正确配置（`allow_websocket_upgrade: true`）
-3. 正在执行 E2E 测试或旅程验证
+满足以下条件时考虑降级：
+1. 已配置 `allowedDevOrigins` 但 HMR WebSocket 仍连接失败
+2. 正在执行 E2E 测试或旅程验证，且 HMR 干扰测试稳定性
 
 #### 降级步骤
 
@@ -276,8 +283,8 @@ pm2 start "npx next dev --port 3001" --name app
 #### 注意事项
 
 - **代码修改后需重新 build**：生产模式下修改源码不会自动生效，必须 `next build` 后重启
-- **E2E/旅程验证优先用 `next start`**：避免 HMR 干扰测试稳定性
-- **开发调试用 `next dev`**：需要热重载时使用，通过 localhost 访问可避免 HMR 问题
+- **开发调试优先用 `next dev`**：通过外网域名访问需配置 `allowedDevOrigins`，可获得热重载体验
+- **仅在必要时用 `next start`**：当 HMR 干扰测试稳定性或配置 `allowedDevOrigins` 后仍失败时使用
 
 ---
 
@@ -364,3 +371,64 @@ MinIO bucket 默认私有，所有通过 URL 直接访问的资源（图片、
 browser_network_requests(static=true, filter="\\.(jpg|jpeg|png|gif|webp|svg|mp4|webm)$")
 # 状态码 403/404 → 资源不可访问 → AUTO-FIX
 ```
+
+---
+
+## 10. allowedDevOrigins 配置（⛔ 外网域名访问时强制）
+
+### 问题描述
+
+Next.js 15+ 引入了 `allowedDevOrigins` 配置项，用于指定开发服务器允许的 origin。
+
+当通过外网域名（如 `*.dev.d8d.fun`）访问 `next dev` 开发服务器时，如果未配置 `allowedDevOrigins`，会出现以下错误：
+- 浏览器页面显示 "Invalid Host header"
+- HMR WebSocket 连接失败
+
+### 配置方法
+
+在 `next.config.ts`（或 `next.config.js`）中添加 `allowedDevOrigins`：
+
+```typescript
+// next.config.ts
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  allowedDevOrigins: [
+    "*.dev.d8d.fun",  // 允许所有 dev.d8d.fun 子域名
+    "localhost",      // 允许 localhost
+  ],
+  // 其他配置...
+};
+
+export default nextConfig;
+```
+
+### 配置后重启服务
+
+修改配置后必须重启 Next.js 开发服务器：
+
+```bash
+# 如果使用 pm2
+pm2 restart vividspark
+
+# 或直接重启
+pm2 stop vividspark && pm2 delete vividspark
+pm2 start "pnpm dev" --name vividspark
+```
+
+### 验证配置
+
+1. 重启服务后，通过外网域名访问（如 `https://admin-custom-xxx.dev.d8d.fun`）
+2. 确认页面正常加载，不再出现 "Invalid Host header" 错误
+3. 打开浏览器控制台，确认 HMR WebSocket 连接成功（无 `webpack-hmr` 错误）
+
+### 与 HMR 降级策略的关系
+
+配置了 `allowedDevOrigins` 后，外网域名的 HMR 通常可以正常工作，**不再需要降级到 `next start`**。
+
+仅在以下情况下考虑降级：
+- 配置了 `allowedDevOrigins` 后 HMR 仍失败
+- 需要最大化测试稳定性（生产模式无 HMR 干扰）
+
+详见 §7.1
+
-- 
2.49.1