[Bug]: Rspress dev 在默认启用 lazyCompilation 时可能触发无限重建与全页刷新循环（virtual-site-data.js not accepted）

[lichao-from-2026]

Version

System:
    OS: macOS 15.7.3
    CPU: (14) arm64 Apple M4 Pro
    Memory: 5.71 GB / 48.00 GB
    Shell: 3.2.57 - /bin/bash
  Browsers:
    Chrome: 148.0.7778.168
    Safari: 18.6

Details

标题

Rspress dev 在启用 lazyCompilation 时可能触发无限重建与全页刷新循环（virtual-site-data.js not accepted）

摘要（可直接放在 Issue 顶部）

在 rspress dev 中，当站点页面数量较多且导航/链接关系较复杂时（多级 _nav.json / _meta.json、首页/目录页包含大量页面链接），如果启用/使用 lazyCompilation，可能出现持续的“增量编译 → virtual-site-data 变更 → HMR 不接受 → full reload → 再触发增量编译”的死循环，导致终端无限重建、浏览器频繁整页刷新与明显闪烁。将 builderConfig.dev.lazyCompilation 设为 false 可稳定规避。

---

现象（实际行为）

• 终端持续交替输出构建日志（例如不断在 docs/index.md 与其他页面之间切换构建）。
• 浏览器控制台反复出现：
  • [rsbuild] HMR update failed, performing full reload
  • 同时伴随大量 [HMR] Reload all CSS
• 用户体验：页面频繁整页刷新/闪烁（例如鼠标移动到顶部导航时可明显感知）。

预期行为

• dev 模式应当稳定 HMR（或在必要时单次 full reload），不应进入无限循环的 rebuild + full reload。

---

复现步骤（本地）

1. 准备一个页面数量较多且导航层级较深的 Rspress 站点：
   • 多级 _nav.json / _meta.json
   • 首页或导航页包含大量链接（指向多个文档页面）
   • 可参考我提供的代码仓库，其中机器人学的站点就很符合这种情况，设置 lazyCompilation: true 即可复现。
   • 代码仓库：https://github.com/lichao-from-2026/multiDocSite
2. 确认 dev 模式启用/使用 lazyCompilation（默认行为或显式打开）。
3. 执行：

   rspress dev

4. 打开首页（例如 /）。
5. 观察：
   • 终端持续重复 start building ... / ready built in ...
   • 浏览器控制台持续报 HMR update failed，并触发 full reload 循环

---

关键日志

浏览器控制台（HMR 失败 + full reload）

[error] [rsbuild] HMR update failed, performing full reload:
  Error: Aborted because ./.rspress/runtime/virtual-site-data.js is not accepted
  Update propagation:
    virtual-site-data.js
    → initPageData.js
    → useLinkNavigate.js
    → theme/index.js
    → shared-docs-theme/src/index.ts
    → ./theme/index.tsx

终端侧（反复编译特征）

start   building docs/index.md
ready   built in ...
start   building <another-page>.md
ready   built in ...
start   building docs/index.md
ready   built in ...
...（无限重复）

---

环境信息

• OS: macOS 15.7.3（Build 24G419）
• Node.js: v22.22.2
• pnpm: 10.26.2
• Rspress: v2.0.10（启动日志显示 🔥 Rspress v2.0.10）

---

已验证结论（排查结果）

• 与 writeToDisk 无关：即使设置 builderConfig.dev.writeToDisk: false，循环仍会发生。
• 触发点与 .rspress/runtime/virtual-site-data.js 的更新相关：日志明确提示该模块 “is not accepted”，随后触发 full reload。
• 更容易触发的条件：页面数量更多、导航层级更深、链接更密集时（lazyCompilation 在 dev 期间持续“发现新页面/生成站点元数据”的概率更高）。

---

规避方案（项目侧已验证有效）

在 rspress.config.ts 中关闭 lazyCompilation 后，问题消失：

builderConfig: {
  dev: {
    lazyCompilation: false,
  },
}

关闭后表现：

• dev 启动会一次性全量编译（首编可能变慢），但后续稳定，不再出现 full reload loop。

---

最小复现建议（建议维护者用于快速定位）

建议提供一个最小 repro（10~30 个页面即可）：

1. 创建 Rspress 站点，保持 dev 模式的 lazyCompilation 行为。
2. 准备：
   • docs/index.md（包含多个页面链接，如 [A](/a)、[B](/b) ...）
   • docs/a.md、docs/b.md、docs/c.md...（建议至少 10 个）
   • _nav.json 至少 2~3 层嵌套 items，并把这些页面都纳入导航
3. 启动 rspress dev，打开首页，观察是否复现：
   • virtual-site-data.js 触发更新
   • HMR not accepted → full reload
   • 进而循环

---

附加信息（可选：初步推断，供讨论）

从日志看 virtual-site-data.js 及其依赖链路未进行 HMR accept；如果 lazyCompilation 在 dev 期间会持续增量更新该模块，那么可能出现“更新必 full reload”的链式反应。可能需要在框架层面对该模块更新策略或 HMR accept 做兼容处理。

Reproduce link

https://github.com/lichao-from-2026/multiDocSite

Reproduce Steps

复现步骤（本地）

1. 准备一个页面数量较多且导航层级较深的 Rspress 站点：
   • 多级 _nav.json / _meta.json
   • 首页或导航页包含大量链接（指向多个文档页面）
   • 可参考我提供的代码仓库，其中机器人学的站点就很符合这种情况，设置 lazyCompilation: true ，单独启动此子应用即可复现。
   • 代码仓库：https://github.com/lichao-from-2026/multiDocSite
2. 确认 dev 模式启用/使用 lazyCompilation（默认行为或显式打开）。
3. 执行：

   rspress dev

4. 打开首页（例如 /）。
5. 观察：
   • 终端持续重复 start building ... / ready built in ...
   • 浏览器控制台持续报 HMR update failed，并触发 full reload 循环

---

最小复现建议（建议维护者用于快速定位）

建议提供一个最小 repro（10~30 个页面即可）：

1. 创建 Rspress 站点，保持 dev 模式的 lazyCompilation 行为。
2. 准备：
   • docs/index.md（包含多个页面链接，如 [A](/a)、[B](/b) ...）
   • docs/a.md、docs/b.md、docs/c.md...（建议至少 10 个）
   • _nav.json 至少 2~3 层嵌套 items，并把这些页面都纳入导航
3. 启动 rspress dev，打开首页，观察是否复现：
   • virtual-site-data.js 触发更新
   • HMR not accepted → full reload
   • 进而循环

---