@fulgurjs/federation 5.9.1 → 5.9.2

package/examples/templates/react-react/pnpm-lock.yaml

@@ -11,8 +11,8 @@ importers:
   host:
     dependencies:
       '@fulgurjs/federation':
-        specifier: 5.9.0
-        version: 5.9.0(react-dom@19.3.0(react@19.3.0))(react-router-dom@7.18.4(react-dom@19.3.0(react@19.3.0))(react@19.3.0))(react@19.3.0)(vite@6.4.3)
+        specifier: 5.9.1
+        version: 5.9.1(react-dom@19.3.0(react@19.3.0))(react-router-dom@7.18.4(react-dom@19.3.0(react@19.3.0))(react@19.3.0))(react@19.3.0)(vite@6.4.3)
       react:
         specifier: ^19.1.0
         version: 19.3.0
@@ -42,8 +42,8 @@ importers:
   remote:
     dependencies:
       '@fulgurjs/federation':
-        specifier: 5.9.0
-        version: 5.9.0(react-dom@19.3.0(react@19.3.0))(react-router-dom@7.18.4(react-dom@19.3.0(react@19.3.0))(react@19.3.0))(react@19.3.0)(vite@6.4.3)
+        specifier: 5.9.1
+        version: 5.9.1(react-dom@19.3.0(react@19.3.0))(react-router-dom@7.18.4(react-dom@19.3.0(react@19.3.0))(react@19.3.0))(react@19.3.0)(vite@6.4.3)
       react:
         specifier: ^19.1.0
         version: 19.3.0
@@ -464,8 +464,8 @@ packages:
     cpu: [x64]
     os: [win32]
 
-  '@fulgurjs/federation@5.9.0':
-    resolution: {integrity: sha512-9dNKsdR8KwGCWLhMRHIYQ8oslI6MiOVqKIyYjhbhYmT7FGBwlPu4tV6v3SQPOEak4m65yqsnWeiqM6zsO55kZQ==}
+  '@fulgurjs/federation@5.9.1':
+    resolution: {integrity: sha512-c6/fTaIG08IRA6KJ+F05YnNh2PtVDPV7+frA1WGgAOHuR1uw5ijwaZjsIOSDENuS37ISiTeznv0fl+Yh9WDhQQ==}
     engines: {node: '>=18'}
     hasBin: true
     peerDependencies:
@@ -1169,7 +1169,7 @@ snapshots:
   '@esbuild/win32-x64@0.27.7':
     optional: true
 
-  '@fulgurjs/federation@5.9.0(react-dom@19.3.0(react@19.3.0))(react-router-dom@7.18.4(react-dom@19.3.0(react@19.3.0))(react@19.3.0))(react@19.3.0)(vite@6.4.3)':
+  '@fulgurjs/federation@5.9.1(react-dom@19.3.0(react@19.3.0))(react-router-dom@7.18.4(react-dom@19.3.0(react@19.3.0))(react@19.3.0))(react@19.3.0)(vite@6.4.3)':
     dependencies:
       es-module-lexer: 1.7.0
       esbuild: 0.27.7

package/examples/templates/react-react/pnpm-workspace.yaml

@@ -2,7 +2,7 @@ packages:
   - host
   - remote
 minimumReleaseAgeExclude:
-  - '@fulgurjs/federation@5.7.1 || 5.8.0 || 5.9.0'
+  - '@fulgurjs/federation@5.7.1 || 5.8.0 || 5.9.0 || 5.9.1'
 # pnpm >=12 构建脚本批准（12 起弃用 onlyBuiltDependencies；pnpm 9-11 忽略本键：
 # esbuild >=0.16 二进制经 optionalDependencies 平台包分发，postinstall 仅校验，不阻塞安装）
 allowBuilds:

package/examples/templates/react-react/remote/package.json

@@ -9,7 +9,7 @@
     "preview": "vite preview --port 5203 --strictPort"
   },
   "dependencies": {
-    "@fulgurjs/federation": "5.9.0",
+    "@fulgurjs/federation": "5.9.1",
     "react": "^19.1.0",
     "react-dom": "^19.1.0"
   },

package/examples/templates/react-react/scripts/dev.mjs

@@ -9,8 +9,12 @@
  * 行为契约（与模板 README 一致）：
  * - 启动前预检全部端口：任何端口被占用则拒绝启动并指认处理方法（绝不按端口杀别人的进程）；
  * - 按 dev.config.json 顺序（远程在前宿主在后）启动各应用，逐个探活；
- * - 任一应用启动失败/超时/中途退出：整组停止（只杀本次启动的子进程），非零退出并打印该应用日志尾部；
+ * - 每个进程从 spawn 起就进入全生命周期监督（启动前/探活中/部分就绪/全组就绪/关闭中）：
+ *   任一应用在任何阶段异常退出 → 整组停止（只杀本次启动的子进程），非零退出并打印该应用日志尾部；
+ *   不存在「探活通过后、全组就绪前」的监督空窗；
  * - Ctrl+C / SIGTERM：清理本次启动的全部子进程后退出；不依赖 PID 文件；
+ * - 停止采用 POSIX 进程组信号：即使包管理器父进程已退出，同组的孙进程（dev server）也会被终止，
+ *   不留下仍监听端口的孤儿；Windows 走 taskkill /T /F 兜底路径（父进程已退出时无法追溯孙进程，见 README）；
  * - 全部就绪后打印访问入口；探活 = 端口可连接（dev server 已监听），页面可用以浏览器验收为准。
  *
  * 平台：macOS/Linux 实测；Windows 走 taskkill 兜底路径，未经验证（见模板 README）。
@@ -71,7 +75,8 @@ async function preflight() {
     const win = `netstat -ano | findstr :${app.port}`
     console.error(
       `  ${app.name} → 端口 ${app.port} 已监听。查看占用：${process.platform === 'win32' ? win : posix}；` +
-        `结束占用进程，或同步修改 ${app.dir}/package.json 的 dev/preview 端口与宿主 fulgurjs.config.ts 的 remotes dev 地址后重试`,
+        `结束占用进程，或同步修改以下整组配置后重试：${app.dir}/package.json 的 dev/preview --port、` +
+        `宿主 fulgurjs.config.ts 的 remotes dev 地址、scripts/dev.config.json 里该应用的 port`,
     )
   }
   console.error('[dev] 本启动器只清理自己启动的进程，不会替你结束端口上的既有服务。')
@@ -89,6 +94,18 @@ function spawnApp(app) {
   children.set(app.name, child)
   child.stdout.on('data', (c) => { recordOutput(app.name, c); String(c).split('\n').filter(Boolean).forEach((l) => printAppLine(app.name, l)) })
   child.stderr.on('data', (c) => { recordOutput(app.name, c); String(c).split('\n').filter(Boolean).forEach((l) => printAppLine(app.name, l)) })
+  // spawn 起即全生命周期监督：探活中、部分就绪、全组就绪、关闭中任何阶段退出都不漏
+  child.once('exit', (code, signal) => {
+    if (!shuttingDown) {
+      void failStartup(
+        app.name,
+        `意外退出（退出码 ${code ?? 'null'}${signal ? `，信号 ${signal}` : ''}）——整组停止；若是启动命令失败，看下方日志尾部`,
+      )
+    }
+  })
+  child.once('error', (e) => {
+    if (!shuttingDown) void failStartup(app.name, `进程无法启动：${e.message}（检查 pnpm 是否可用：pnpm -v）`)
+  })
   return child
 }
 
@@ -109,33 +126,79 @@ async function waitReady(app, child) {
   return { ok: false, reason: `${Math.round(readyTimeoutMs / 1000)}s 内端口 ${app.port} 未就绪（dev server 未监听）` }
 }
 
+/**
+ * 整组终止：向进程组发信号（detached 子进程是组长；组长已退出时组内孙进程仍在，组信号依然送达）。
+ * 不检查直接子进程是否已退出——那会跳过组信号、留下仍监听端口的孙进程。
+ * Windows 用 taskkill /T /F 树杀；父进程已退出时 taskkill 无法追溯，属平台兜底限制。
+ */
 function killTree(appName) {
   const child = children.get(appName)
-  if (!child || child.exitCode !== null || child.signalCode !== null) return Promise.resolve()
-  return new Promise((resolve) => {
-    const force = setTimeout(() => {
-      try { process.kill(process.platform === 'win32' ? child.pid : -child.pid, 'SIGKILL') } catch { /* 已退出 */ }
-    }, 3000).unref()
-    child.once('exit', () => { clearTimeout(force); resolve() })
+  if (!child) return Promise.resolve()
+  const pid = child.pid
+  const isWin = process.platform === 'win32'
+  const directDead = child.exitCode !== null || child.signalCode !== null
+  const signalGroup = (hard) => {
     try {
-      if (process.platform === 'win32') spawn('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore' })
-      else process.kill(-child.pid, 'SIGTERM')
-    } catch { clearTimeout(force); resolve() }
+      if (isWin) {
+        if (!directDead) spawn('taskkill', ['/pid', String(pid), '/T', '/F'], { stdio: 'ignore' })
+      } else {
+        process.kill(-pid, hard ? 'SIGKILL' : 'SIGTERM')
+      }
+    } catch {
+      /* ESRCH：组内已无进程 */
+    }
+  }
+  return new Promise((resolve) => {
+    let done = false
+    const finish = () => {
+      if (done) return
+      done = true
+      clearTimeout(forceTimer)
+      resolve()
+    }
+    // 这些定时器必须是 ref 的：直接子进程已退出时它们是事件循环里唯一的句柄，
+    // unref 会让循环提前 drain（进程以退出码 13 结束），shutdown 的收尾就永远走不完
+    const forceTimer = setTimeout(() => {
+      signalGroup(true)
+      setTimeout(finish, 500)
+    }, 3000)
+    if (!directDead) child.once('exit', finish)
+    signalGroup(false)
+    if (directDead || isWin) {
+      // 直接子进程已退出（或 Windows 树杀无法等 exit 事件）：给组信号固定传播宽限
+      setTimeout(finish, 500)
+    }
   })
 }
 
+/** 统一失败通道：任何阶段的失败都从这里走（shuttingDown 幂等，多事件并发不冲突） */
+async function failStartup(name, reason) {
+  if (shuttingDown) return
+  console.error(color('31', `\n[dev] 启动失败：${name} —— ${reason}`))
+  const tail = tailOf.get(name) ?? []
+  if (tail.length) {
+    console.error(color('31', `[dev] ${name} 日志尾部（最后 ${tail.length} 行）：`))
+    for (const line of tail) console.error(`  [${name}] ${line}`)
+  }
+  await shutdown(EXIT.startupFailed, `[dev] 正在停止本次启动的其余应用…`)
+}
+
 async function shutdown(exitCode, reason) {
   if (shuttingDown) return
   shuttingDown = true
   if (reason) console.log(`[dev] ${reason}`)
   console.log(`[dev] 正在停止本次启动的 ${children.size} 个应用…`)
+  // 看门狗：清理最多等 15s，绝不因单个 killTree 挂起而无法退出
+  const watchdog = setTimeout(() => process.exit(exitCode), 15000)
+  watchdog.unref()
   await Promise.all([...children.keys()].map(killTree))
+  clearTimeout(watchdog)
   console.log('[dev] 已全部停止。')
   process.exit(exitCode)
 }
 
-process.on('SIGINT', () => void shutdown(EXIT.signal, '[dev] 收到 Ctrl+C'))
-process.on('SIGTERM', () => void shutdown(143, '[dev] 收到 SIGTERM'))
+process.on('SIGINT', () => void shutdown(EXIT.signal, '收到 Ctrl+C'))
+process.on('SIGTERM', () => void shutdown(143, '收到 SIGTERM'))
 
 await preflight()
 
@@ -145,29 +208,19 @@ for (const app of apps) {
   const child = spawnApp(app)
   const ready = await waitReady(app, child)
   if (!ready.ok) {
-    console.error(color('31', `\n[dev] 启动失败：${app.name} —— ${ready.reason}`))
-    const tail = tailOf.get(app.name) ?? []
-    if (tail.length) {
-      console.error(color('31', `[dev] ${app.name} 日志尾部（最后 ${tail.length} 行）：`))
-      for (const line of tail) console.error(`  [${app.name}] ${line}`)
-    }
-    await Promise.all([...children.keys()].map(killTree))
-    console.error(`[dev] 已停止本次启动的全部进程（${children.size} 个）。修复上面的问题后重新运行 pnpm dev。`)
-    process.exit(EXIT.startupFailed)
+    await failStartup(app.name, ready.reason)
+  }
+  if (shuttingDown) {
+    // 失败通道已接管（含并发事件抢先置位的情况）：停在这里等 shutdown 退出，绝不宣布就绪
+    await new Promise(() => {})
   }
   printAppLine(app.name, `就绪 → http://localhost:${app.port}/`)
 }
 
-console.log(color('32', '\n[dev] 全部应用已就绪：'))
+console.log(color('32', '\n[dev] 全部应用已就绪（持续监督中，任一应用退出会整组停止）：'))
 for (const app of [...apps].reverse()) {
   console.log(`  http://localhost:${app.port}/    ${app.name}`)
 }
 console.log('[dev] Ctrl+C 停止全部应用（只清理本次启动的进程）。dev server 已监听 ≠ 页面必然可用，验收请以浏览器实际加载为准。\n')
 
-// 运行期任何子应用退出（崩溃/被外部杀掉）→ 整组停止，不让半残组合冒充正常运行
-for (const [name, child] of children) {
-  child.once('exit', (code) => {
-    if (!shuttingDown) void shutdown(EXIT.startupFailed, `[dev] ${name} 意外退出（退出码 ${code}）——停止其余应用`)
-  })
-}
 await new Promise(() => {})

package/examples/templates/showcase/README.md

@@ -1,6 +1,6 @@
 # 双向桥接 URL 同步（examples/templates/showcase）
 
-`@fulgurjs/federation` 5.8.0「桥接 URL 同步」（`/bridge/router/*`，README §8.3）的双向旗舰演示：
+`@fulgurjs/federation` 5.9.1「桥接 URL 同步」（`/bridge/router/*`，README §8.3）的双向旗舰演示：
 两个方向的宿主 × 子应用各一套——
 
 - **vue-host（:5334）× react-remote（:5333）**：Vue Router 4 宿主 + `createReactBridgeRouter` React 子应用
@@ -107,3 +107,13 @@ curl --noproxy '*' -s -o /dev/null -w '%{http_code}\n' http://localhost:5335/@fu
 pnpm run typecheck   # React 工程 tsc --noEmit；Vue 工程 vue-tsc --noEmit
 pnpm run build
 ```
+
+## 改端口（整组同步，漏一处启动器会被旧端口卡住）
+
+四个应用的端口出现在三处，改任何一个都要整组同步：
+
+1. 各应用 `package.json` 的 `dev` 与 `preview` 两个脚本的 `--port`（每应用两处）；
+2. 宿主 `fulgurjs.config.ts` 里 `remotes` 的 dev 地址（`vue-host` 指向 react-remote 的 5333；`react-host` 指向 vue-remote 的 5335）；
+3. 根 `scripts/dev.config.json` 里该应用的 `port`（**必改**：启动器预检/探活都读它）。
+
+生产部署地址（各应用 `prod`）是站点路径，与 dev 端口无关，改端口不要动它。改完自查：`grep -rn "533" --include="*.json" --include="*.ts" .` 不应再出现旧端口。

package/examples/templates/showcase/pnpm-lock.yaml

@@ -11,8 +11,8 @@ importers:
   react-host:
     dependencies:
       '@fulgurjs/federation':
-        specifier: 5.9.0
-        version: 5.9.0(react-dom@19.3.0(react@19.3.0))(react-router-dom@7.18.4(react-dom@19.3.0(react@19.3.0))(react@19.3.0))(react@19.3.0)(vite@6.4.3)(vue-router@4.6.4(vue@3.5.43(typescript@5.9.3)))(vue@3.5.43(typescript@5.9.3))
+        specifier: 5.9.1
+        version: 5.9.1(react-dom@19.3.0(react@19.3.0))(react-router-dom@7.18.4(react-dom@19.3.0(react@19.3.0))(react@19.3.0))(react@19.3.0)(vite@6.4.3)(vue-router@4.6.4(vue@3.5.43(typescript@5.9.3)))(vue@3.5.43(typescript@5.9.3))
       react:
         specifier: ^19.1.0
         version: 19.3.0
@@ -45,8 +45,8 @@ importers:
   react-remote:
     dependencies:
       '@fulgurjs/federation':
-        specifier: 5.9.0
-        version: 5.9.0(react-dom@19.3.0(react@19.3.0))(react-router-dom@7.18.4(react-dom@19.3.0(react@19.3.0))(react@19.3.0))(react@19.3.0)(vite@6.4.3)(vue-router@4.6.4(vue@3.5.43(typescript@5.9.3)))(vue@3.5.43(typescript@5.9.3))
+        specifier: 5.9.1
+        version: 5.9.1(react-dom@19.3.0(react@19.3.0))(react-router-dom@7.18.4(react-dom@19.3.0(react@19.3.0))(react@19.3.0))(react@19.3.0)(vite@6.4.3)(vue-router@4.6.4(vue@3.5.43(typescript@5.9.3)))(vue@3.5.43(typescript@5.9.3))
       react:
         specifier: ^19.1.0
         version: 19.3.0
@@ -76,8 +76,8 @@ importers:
   vue-host:
     dependencies:
       '@fulgurjs/federation':
-        specifier: 5.9.0
-        version: 5.9.0(react-dom@19.3.0(react@19.3.0))(react-router-dom@7.18.4(react-dom@19.3.0(react@19.3.0))(react@19.3.0))(react@19.3.0)(vite@6.4.3)(vue-router@4.6.4(vue@3.5.43(typescript@5.9.3)))(vue@3.5.43(typescript@5.9.3))
+        specifier: 5.9.1
+        version: 5.9.1(react-dom@19.3.0(react@19.3.0))(react-router-dom@7.18.4(react-dom@19.3.0(react@19.3.0))(react@19.3.0))(react@19.3.0)(vite@6.4.3)(vue-router@4.6.4(vue@3.5.43(typescript@5.9.3)))(vue@3.5.43(typescript@5.9.3))
       react:
         specifier: ^19.1.0
         version: 19.3.0
@@ -107,8 +107,8 @@ importers:
   vue-remote:
     dependencies:
       '@fulgurjs/federation':
-        specifier: 5.9.0
-        version: 5.9.0(react-dom@19.3.0(react@19.3.0))(react-router-dom@7.18.4(react-dom@19.3.0(react@19.3.0))(react@19.3.0))(react@19.3.0)(vite@6.4.3)(vue-router@4.6.4(vue@3.5.43(typescript@5.9.3)))(vue@3.5.43(typescript@5.9.3))
+        specifier: 5.9.1
+        version: 5.9.1(react-dom@19.3.0(react@19.3.0))(react-router-dom@7.18.4(react-dom@19.3.0(react@19.3.0))(react@19.3.0))(react@19.3.0)(vite@6.4.3)(vue-router@4.6.4(vue@3.5.43(typescript@5.9.3)))(vue@3.5.43(typescript@5.9.3))
       vue:
         specifier: ^3.5.13
         version: 3.5.43(typescript@5.9.3)
@@ -526,8 +526,8 @@ packages:
     cpu: [x64]
     os: [win32]
 
-  '@fulgurjs/federation@5.9.0':
-    resolution: {integrity: sha512-9dNKsdR8KwGCWLhMRHIYQ8oslI6MiOVqKIyYjhbhYmT7FGBwlPu4tV6v3SQPOEak4m65yqsnWeiqM6zsO55kZQ==}
+  '@fulgurjs/federation@5.9.1':
+    resolution: {integrity: sha512-c6/fTaIG08IRA6KJ+F05YnNh2PtVDPV7+frA1WGgAOHuR1uw5ijwaZjsIOSDENuS37ISiTeznv0fl+Yh9WDhQQ==}
     engines: {node: '>=18'}
     hasBin: true
     peerDependencies:
@@ -1348,7 +1348,7 @@ snapshots:
   '@esbuild/win32-x64@0.27.7':
     optional: true
 
-  '@fulgurjs/federation@5.9.0(react-dom@19.3.0(react@19.3.0))(react-router-dom@7.18.4(react-dom@19.3.0(react@19.3.0))(react@19.3.0))(react@19.3.0)(vite@6.4.3)(vue-router@4.6.4(vue@3.5.43(typescript@5.9.3)))(vue@3.5.43(typescript@5.9.3))':
+  '@fulgurjs/federation@5.9.1(react-dom@19.3.0(react@19.3.0))(react-router-dom@7.18.4(react-dom@19.3.0(react@19.3.0))(react@19.3.0))(react@19.3.0)(vite@6.4.3)(vue-router@4.6.4(vue@3.5.43(typescript@5.9.3)))(vue@3.5.43(typescript@5.9.3))':
     dependencies:
       es-module-lexer: 1.7.0
       esbuild: 0.27.7

package/examples/templates/showcase/pnpm-workspace.yaml

@@ -4,7 +4,7 @@ packages:
   - react-host
   - react-remote
 minimumReleaseAgeExclude:
-  - '@fulgurjs/federation@5.7.1 || 5.8.0 || 5.9.0'
+  - '@fulgurjs/federation@5.7.1 || 5.8.0 || 5.9.0 || 5.9.1'
 # pnpm >=12 构建脚本批准（12 起弃用 onlyBuiltDependencies；pnpm 9-11 忽略本键：
 # esbuild >=0.16 二进制经 optionalDependencies 平台包分发，postinstall 仅校验，不阻塞安装）
 allowBuilds:

package/examples/templates/showcase/react-host/index.html

@@ -4,7 +4,7 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <link rel="icon" href="data:," />
-    <title>react-host（桥接 URL 同步宿主 × Vue 子应用，5336）</title>
+    <title>react-host（桥接 URL 同步宿主 × Vue 子应用，默认端口 5336）</title>
   </head>
   <body>
     <div id="root"></div>

package/examples/templates/showcase/react-host/package.json

@@ -10,7 +10,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@fulgurjs/federation": "5.9.0",
+    "@fulgurjs/federation": "5.9.1",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
     "react-router-dom": "^7.1.0",

package/examples/templates/showcase/react-remote/package.json

@@ -10,7 +10,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@fulgurjs/federation": "5.9.0",
+    "@fulgurjs/federation": "5.9.1",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
     "react-router-dom": "^7.1.0"

package/examples/templates/showcase/scripts/dev.mjs

@@ -9,8 +9,12 @@
  * 行为契约（与模板 README 一致）：
  * - 启动前预检全部端口：任何端口被占用则拒绝启动并指认处理方法（绝不按端口杀别人的进程）；
  * - 按 dev.config.json 顺序（远程在前宿主在后）启动各应用，逐个探活；
- * - 任一应用启动失败/超时/中途退出：整组停止（只杀本次启动的子进程），非零退出并打印该应用日志尾部；
+ * - 每个进程从 spawn 起就进入全生命周期监督（启动前/探活中/部分就绪/全组就绪/关闭中）：
+ *   任一应用在任何阶段异常退出 → 整组停止（只杀本次启动的子进程），非零退出并打印该应用日志尾部；
+ *   不存在「探活通过后、全组就绪前」的监督空窗；
  * - Ctrl+C / SIGTERM：清理本次启动的全部子进程后退出；不依赖 PID 文件；
+ * - 停止采用 POSIX 进程组信号：即使包管理器父进程已退出，同组的孙进程（dev server）也会被终止，
+ *   不留下仍监听端口的孤儿；Windows 走 taskkill /T /F 兜底路径（父进程已退出时无法追溯孙进程，见 README）；
  * - 全部就绪后打印访问入口；探活 = 端口可连接（dev server 已监听），页面可用以浏览器验收为准。
  *
  * 平台：macOS/Linux 实测；Windows 走 taskkill 兜底路径，未经验证（见模板 README）。
@@ -71,7 +75,8 @@ async function preflight() {
     const win = `netstat -ano | findstr :${app.port}`
     console.error(
       `  ${app.name} → 端口 ${app.port} 已监听。查看占用：${process.platform === 'win32' ? win : posix}；` +
-        `结束占用进程，或同步修改 ${app.dir}/package.json 的 dev/preview 端口与宿主 fulgurjs.config.ts 的 remotes dev 地址后重试`,
+        `结束占用进程，或同步修改以下整组配置后重试：${app.dir}/package.json 的 dev/preview --port、` +
+        `宿主 fulgurjs.config.ts 的 remotes dev 地址、scripts/dev.config.json 里该应用的 port`,
     )
   }
   console.error('[dev] 本启动器只清理自己启动的进程，不会替你结束端口上的既有服务。')
@@ -89,6 +94,18 @@ function spawnApp(app) {
   children.set(app.name, child)
   child.stdout.on('data', (c) => { recordOutput(app.name, c); String(c).split('\n').filter(Boolean).forEach((l) => printAppLine(app.name, l)) })
   child.stderr.on('data', (c) => { recordOutput(app.name, c); String(c).split('\n').filter(Boolean).forEach((l) => printAppLine(app.name, l)) })
+  // spawn 起即全生命周期监督：探活中、部分就绪、全组就绪、关闭中任何阶段退出都不漏
+  child.once('exit', (code, signal) => {
+    if (!shuttingDown) {
+      void failStartup(
+        app.name,
+        `意外退出（退出码 ${code ?? 'null'}${signal ? `，信号 ${signal}` : ''}）——整组停止；若是启动命令失败，看下方日志尾部`,
+      )
+    }
+  })
+  child.once('error', (e) => {
+    if (!shuttingDown) void failStartup(app.name, `进程无法启动：${e.message}（检查 pnpm 是否可用：pnpm -v）`)
+  })
   return child
 }
 
@@ -109,33 +126,79 @@ async function waitReady(app, child) {
   return { ok: false, reason: `${Math.round(readyTimeoutMs / 1000)}s 内端口 ${app.port} 未就绪（dev server 未监听）` }
 }
 
+/**
+ * 整组终止：向进程组发信号（detached 子进程是组长；组长已退出时组内孙进程仍在，组信号依然送达）。
+ * 不检查直接子进程是否已退出——那会跳过组信号、留下仍监听端口的孙进程。
+ * Windows 用 taskkill /T /F 树杀；父进程已退出时 taskkill 无法追溯，属平台兜底限制。
+ */
 function killTree(appName) {
   const child = children.get(appName)
-  if (!child || child.exitCode !== null || child.signalCode !== null) return Promise.resolve()
-  return new Promise((resolve) => {
-    const force = setTimeout(() => {
-      try { process.kill(process.platform === 'win32' ? child.pid : -child.pid, 'SIGKILL') } catch { /* 已退出 */ }
-    }, 3000).unref()
-    child.once('exit', () => { clearTimeout(force); resolve() })
+  if (!child) return Promise.resolve()
+  const pid = child.pid
+  const isWin = process.platform === 'win32'
+  const directDead = child.exitCode !== null || child.signalCode !== null
+  const signalGroup = (hard) => {
     try {
-      if (process.platform === 'win32') spawn('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore' })
-      else process.kill(-child.pid, 'SIGTERM')
-    } catch { clearTimeout(force); resolve() }
+      if (isWin) {
+        if (!directDead) spawn('taskkill', ['/pid', String(pid), '/T', '/F'], { stdio: 'ignore' })
+      } else {
+        process.kill(-pid, hard ? 'SIGKILL' : 'SIGTERM')
+      }
+    } catch {
+      /* ESRCH：组内已无进程 */
+    }
+  }
+  return new Promise((resolve) => {
+    let done = false
+    const finish = () => {
+      if (done) return
+      done = true
+      clearTimeout(forceTimer)
+      resolve()
+    }
+    // 这些定时器必须是 ref 的：直接子进程已退出时它们是事件循环里唯一的句柄，
+    // unref 会让循环提前 drain（进程以退出码 13 结束），shutdown 的收尾就永远走不完
+    const forceTimer = setTimeout(() => {
+      signalGroup(true)
+      setTimeout(finish, 500)
+    }, 3000)
+    if (!directDead) child.once('exit', finish)
+    signalGroup(false)
+    if (directDead || isWin) {
+      // 直接子进程已退出（或 Windows 树杀无法等 exit 事件）：给组信号固定传播宽限
+      setTimeout(finish, 500)
+    }
   })
 }
 
+/** 统一失败通道：任何阶段的失败都从这里走（shuttingDown 幂等，多事件并发不冲突） */
+async function failStartup(name, reason) {
+  if (shuttingDown) return
+  console.error(color('31', `\n[dev] 启动失败：${name} —— ${reason}`))
+  const tail = tailOf.get(name) ?? []
+  if (tail.length) {
+    console.error(color('31', `[dev] ${name} 日志尾部（最后 ${tail.length} 行）：`))
+    for (const line of tail) console.error(`  [${name}] ${line}`)
+  }
+  await shutdown(EXIT.startupFailed, `[dev] 正在停止本次启动的其余应用…`)
+}
+
 async function shutdown(exitCode, reason) {
   if (shuttingDown) return
   shuttingDown = true
   if (reason) console.log(`[dev] ${reason}`)
   console.log(`[dev] 正在停止本次启动的 ${children.size} 个应用…`)
+  // 看门狗：清理最多等 15s，绝不因单个 killTree 挂起而无法退出
+  const watchdog = setTimeout(() => process.exit(exitCode), 15000)
+  watchdog.unref()
   await Promise.all([...children.keys()].map(killTree))
+  clearTimeout(watchdog)
   console.log('[dev] 已全部停止。')
   process.exit(exitCode)
 }
 
-process.on('SIGINT', () => void shutdown(EXIT.signal, '[dev] 收到 Ctrl+C'))
-process.on('SIGTERM', () => void shutdown(143, '[dev] 收到 SIGTERM'))
+process.on('SIGINT', () => void shutdown(EXIT.signal, '收到 Ctrl+C'))
+process.on('SIGTERM', () => void shutdown(143, '收到 SIGTERM'))
 
 await preflight()
 
@@ -145,29 +208,19 @@ for (const app of apps) {
   const child = spawnApp(app)
   const ready = await waitReady(app, child)
   if (!ready.ok) {
-    console.error(color('31', `\n[dev] 启动失败：${app.name} —— ${ready.reason}`))
-    const tail = tailOf.get(app.name) ?? []
-    if (tail.length) {
-      console.error(color('31', `[dev] ${app.name} 日志尾部（最后 ${tail.length} 行）：`))
-      for (const line of tail) console.error(`  [${app.name}] ${line}`)
-    }
-    await Promise.all([...children.keys()].map(killTree))
-    console.error(`[dev] 已停止本次启动的全部进程（${children.size} 个）。修复上面的问题后重新运行 pnpm dev。`)
-    process.exit(EXIT.startupFailed)
+    await failStartup(app.name, ready.reason)
+  }
+  if (shuttingDown) {
+    // 失败通道已接管（含并发事件抢先置位的情况）：停在这里等 shutdown 退出，绝不宣布就绪
+    await new Promise(() => {})
   }
   printAppLine(app.name, `就绪 → http://localhost:${app.port}/`)
 }
 
-console.log(color('32', '\n[dev] 全部应用已就绪：'))
+console.log(color('32', '\n[dev] 全部应用已就绪（持续监督中，任一应用退出会整组停止）：'))
 for (const app of [...apps].reverse()) {
   console.log(`  http://localhost:${app.port}/    ${app.name}`)
 }
 console.log('[dev] Ctrl+C 停止全部应用（只清理本次启动的进程）。dev server 已监听 ≠ 页面必然可用，验收请以浏览器实际加载为准。\n')
 
-// 运行期任何子应用退出（崩溃/被外部杀掉）→ 整组停止，不让半残组合冒充正常运行
-for (const [name, child] of children) {
-  child.once('exit', (code) => {
-    if (!shuttingDown) void shutdown(EXIT.startupFailed, `[dev] ${name} 意外退出（退出码 ${code}）——停止其余应用`)
-  })
-}
 await new Promise(() => {})

package/examples/templates/showcase/vue-host/package.json

@@ -10,7 +10,7 @@
     "typecheck": "vue-tsc --noEmit"
   },
   "dependencies": {
-    "@fulgurjs/federation": "5.9.0",
+    "@fulgurjs/federation": "5.9.1",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
     "vue": "^3.5.13",

package/examples/templates/showcase/vue-remote/index.html

@@ -4,7 +4,7 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <link rel="icon" href="data:," />
-    <title>vue-remote（桥接 URL 同步子应用，5335）</title>
+    <title>vue-remote（桥接 URL 同步子应用，默认端口 5335）</title>
   </head>
   <body>
     <div id="app"></div>

package/examples/templates/showcase/vue-remote/package.json

@@ -10,7 +10,7 @@
     "typecheck": "vue-tsc --noEmit"
   },
   "dependencies": {
-    "@fulgurjs/federation": "5.9.0",
+    "@fulgurjs/federation": "5.9.1",
     "vue": "^3.5.13",
     "vue-router": "^4.5.0"
   },

package/examples/templates/showcase/vue-remote/src/main.ts

@@ -7,10 +7,10 @@ import { createApp, h } from 'vue'
 createApp({
   render: () =>
     h('div', { style: "font-family: 'PingFang SC', 'Microsoft YaHei', sans-serif; padding: 24px" }, [
-      h('h1', null, 'vue-remote（联邦子应用，5335）'),
+      h('h1', null, 'vue-remote（联邦子应用，默认端口 5335，改端口见 README「改端口」清单）'),
       h('p', null, '本应用通过 expose ./bridge（defineBridgeApp + routing 协议）被宿主加载。'),
       h('p', null, [
-        h('a', { href: 'http://localhost:5336/br-vue/orders' }, '打开 React 宿主桥接页（5336）'),
+        h('a', { href: 'http://localhost:5336/br-vue/orders' }, '打开 React 宿主桥接页（默认 5336）'),
       ]),
     ]),
 }).mount('#app')

package/examples/templates/vue-host-react-remote/README.md

@@ -16,3 +16,9 @@ pnpm dev
 - 无 JS 沙箱或自动 CSS 隔离，子应用全局样式和 body 副作用需要自行管理。
 
 环境要求见[模板指南](../README.md)。所有依赖来自 registry，不需要本仓库源码或其他模板。
+
+## 改端口（四处必须同步，漏一处启动器会被旧端口卡住）
+
+- 改react-remote（默认 5303）：① `react-remote/package.json` 的 `dev` 与 `preview` 两个脚本的 `--port 5303`；② `vue-host/fulgurjs.config.ts` 里 `remotes['bridge-react-remote'].dev` 的 `http://localhost:5303`；③ 根 `scripts/dev.config.json` 里 react-remote 的 `port`（**必改**：启动器预检/探活都读它）；④ 本 README 顶部端口表。
+- 改vue-host（默认 5314）：① `vue-host/package.json` 的 `dev`/`preview` `--port 5314`；② `scripts/dev.config.json`；③ 本 README 端口表。
+- 生产部署地址（`prod`，如 `/react-remote`）是站点路径，与 dev 端口无关，改端口不要动它。改名（容器名）不建议：还需同步 spec 前缀与页面表。

package/examples/templates/vue-host-react-remote/pnpm-lock.yaml

@@ -11,8 +11,8 @@ importers:
   react-remote:
     dependencies:
       '@fulgurjs/federation':
-        specifier: 5.9.0
-        version: 5.9.0(react-dom@19.3.0(react@19.3.0))(react-router-dom@7.18.4(react-dom@19.3.0(react@19.3.0))(react@19.3.0))(react@19.3.0)(vite@6.4.3)(vue@3.5.43(typescript@5.9.3))
+        specifier: 5.9.1
+        version: 5.9.1(react-dom@19.3.0(react@19.3.0))(react-router-dom@7.18.4(react-dom@19.3.0(react@19.3.0))(react@19.3.0))(react@19.3.0)(vite@6.4.3)(vue@3.5.43(typescript@5.9.3))
       react:
         specifier: ^19.1.0
         version: 19.3.0
@@ -42,8 +42,8 @@ importers:
   vue-host:
     dependencies:
       '@fulgurjs/federation':
-        specifier: 5.9.0
-        version: 5.9.0(react-dom@19.3.0(react@19.3.0))(react-router-dom@7.18.4(react-dom@19.3.0(react@19.3.0))(react@19.3.0))(react@19.3.0)(vite@6.4.3)(vue@3.5.43(typescript@5.9.3))
+        specifier: 5.9.1
+        version: 5.9.1(react-dom@19.3.0(react@19.3.0))(react-router-dom@7.18.4(react-dom@19.3.0(react@19.3.0))(react@19.3.0))(react@19.3.0)(vite@6.4.3)(vue@3.5.43(typescript@5.9.3))
       react:
         specifier: ^19.1.0
         version: 19.3.0
@@ -467,8 +467,8 @@ packages:
     cpu: [x64]
     os: [win32]
 
-  '@fulgurjs/federation@5.9.0':
-    resolution: {integrity: sha512-9dNKsdR8KwGCWLhMRHIYQ8oslI6MiOVqKIyYjhbhYmT7FGBwlPu4tV6v3SQPOEak4m65yqsnWeiqM6zsO55kZQ==}
+  '@fulgurjs/federation@5.9.1':
+    resolution: {integrity: sha512-c6/fTaIG08IRA6KJ+F05YnNh2PtVDPV7+frA1WGgAOHuR1uw5ijwaZjsIOSDENuS37ISiTeznv0fl+Yh9WDhQQ==}
     engines: {node: '>=18'}
     hasBin: true
     peerDependencies:
@@ -1221,7 +1221,7 @@ snapshots:
   '@esbuild/win32-x64@0.27.7':
     optional: true
 
-  '@fulgurjs/federation@5.9.0(react-dom@19.3.0(react@19.3.0))(react-router-dom@7.18.4(react-dom@19.3.0(react@19.3.0))(react@19.3.0))(react@19.3.0)(vite@6.4.3)(vue@3.5.43(typescript@5.9.3))':
+  '@fulgurjs/federation@5.9.1(react-dom@19.3.0(react@19.3.0))(react-router-dom@7.18.4(react-dom@19.3.0(react@19.3.0))(react@19.3.0))(react@19.3.0)(vite@6.4.3)(vue@3.5.43(typescript@5.9.3))':
     dependencies:
       es-module-lexer: 1.7.0
       esbuild: 0.27.7

package/examples/templates/vue-host-react-remote/pnpm-workspace.yaml

@@ -2,7 +2,7 @@ packages:
   - vue-host
   - react-remote
 minimumReleaseAgeExclude:
-  - '@fulgurjs/federation@5.7.1 || 5.8.0 || 5.9.0'
+  - '@fulgurjs/federation@5.7.1 || 5.8.0 || 5.9.0 || 5.9.1'
 # pnpm >=12 构建脚本批准（12 起弃用 onlyBuiltDependencies；pnpm 9-11 忽略本键：
 # esbuild >=0.16 二进制经 optionalDependencies 平台包分发，postinstall 仅校验，不阻塞安装）
 allowBuilds: