@fulgurjs/federation 0.4.2

package/docs//346/262/231/347/256/261/350/276/271/347/225/214/345/256/241/350/256/241.md

@@ -0,0 +1,45 @@
+# 沙箱边界审计（CSS / 全局变量 / 公共依赖）
+
+> 日期 2026-09-16 ｜ 实测脚本 `e2e/sandbox-audit.mjs`、`e2e/sandbox-audit2.mjs` ｜ 环境 dev（admin+bpm+lowcode 三应用联邦）
+
+## 结论
+
+**联邦没有沙箱，也不需要沙箱**——这是与 qiankun 的根本架构差异。qiankun 用 JS Proxy 假 window + 样式隔离做「隔离共存」；@fulgurjs/federation（与 webpack MF 一致）做「**同 realm 共存 + 依赖级隔离**」：所有联邦模块与宿主跑在同一个 window/同一个 CSSOM 里，靠**共享依赖单例协商**防止最大的互扰源（双 Vue 运行时），而不是靠沙箱隔开。
+
+## 实测数据（admin 宿主 + bpm + lowcode 联邦加载前后对比）
+
+### 1. 全局变量（window）
+
+- 联邦加载前后 window 新增键**仅 17 个**，且全部可解释：
+  - `mainAppProps`/`mainRouter`：宿主→子应用的桥接对象（对齐乾坤 mainAppProps 语义，by design）
+  - `__VUE_I18N_*`/`__INTLIFY_*` 5 个：vue-i18n 的编译期 feature flags（库本身行为）
+  - `Prism`/`Sortable`：lowcode 设计器引入的第三方库全局
+  - `exports`/`fs`/`stream`/`util`/`chokidar` 等：lowcode 某设计器依赖把 Node 风格 CJS 包装漏到 window（**原版乾坤下同样存在**，属子应用依赖自身的脏行为，与联邦无关）
+- 联邦运行时唯一注册面：`window.__FULGUR_SCOPE__`（值 `['default']`）与 `__FULGUR_INFO__`——无全局散落
+- **未发现子应用覆盖宿主关键全局**
+
+### 2. CSS
+
+- 样式表数量：登录后基线 249 → 联邦加载后 470（+221，子应用页面样式按需注入，**expose chunk 的 CSS 自动加载**，fixtures B-17 用例覆盖）
+- `:root --el-color-primary` 基线与加载后均为 `#409eff`——admin(element-plus 2.14.3)/bpm(2.9.1)/lowcode(2.10.2) **三版本 element-plus CSS 共存**，主色变量未被破坏
+- 风格主战场：Vue SFC scoped 样式（data-v hash）天然隔离；组件库 CSS 类名前缀（.el-/.avue-/.vxe-）天然分区
+- **已知理论边界**：多版本组件库 CSS 同挂 `:root` 变量，后加载覆盖先加载——当前三版本变量值一致故无实际影响；若未来某版本改了变量默认值，以「最后加载为准」，这是同 realm CSSOM 的固有权衡（webpack MF 同样如此）
+
+### 3. 公共方法/依赖实例
+
+| 类别 | 机制 | 实测证据 |
+|------|------|---------|
+| **shared 键**（vue/pinia/vue-router） | loadShare 协商单例，"已加载优先" | 联邦页面组件与宿主同为一份 Vue（双 Vue 曾致 'ce' 崩溃，修复后全站 0 报错即为单例实证）；pinia/vue-router singleton 冲突警告显示协商发生且取宿主实例 |
+| **非 shared 依赖**（lodash-es、axios、avue…） | 各子应用自带副本，模块作用域隔离 | 互不干扰；缺点是体积冗余（联邦的固有权衡） |
+| **子应用全局注册**（全局组件/指令/字典） | federatedBoot **显式**注册进宿主 app 实例，失败显式报错（H3） | lowcode 组件数 335→686 的注册面清晰可见 |
+
+## 三、给你的心智模型
+
+| 维度 | qiankun | @fulgurjs/federation |
+|------|---------|--------------------|
+| JS 运行环境 | Proxy 假 window 沙箱 | **同一 window，无沙箱** |
+| CSS | 可选严格隔离/重写 scoped | **同一 CSSOM，无隔离**（靠 scoped 样式+类名前缀+依赖版本对齐） |
+| 公共依赖 | 子应用各自打包（或 externals） | **shared 单例协商**（更强：运行时版本协商+双版本共存） |
+| 适用代价 | 隔离带来适配成本（全局桥、样式穿透、性能损耗） | 无沙箱要求依赖收敛（本案例已全量验证） |
+
+**一句话**：联邦不做"防你犯错的隔离"，做"让你们共享一切的编排"。全局变量要按团队约定加前缀；全局样式要 scoped 或带业务前缀；这三条纪律在 testbed 真实工程里已全部落实并实测无互扰。

package/docs//350/277/201/347/247/273/346/214/207/345/215/227.md

@@ -0,0 +1,80 @@
+# 迁移指南：qiankun 微前端 → @fulgurjs/federation
+
+> 本指南以 testbed/mes-zc（admin 宿主 + bpm/lowcode 子应用，21+6 页，真实工程）为案例。
+
+## 一、概念映射
+
+| qiankun | @fulgurjs/federation |
+|---------|--------------------|
+| 主应用 registerMicroApps | 宿主 `federation({ remotes })` |
+| 子应用 entry（HTML） | remote entry（dev: `@fulgur-entry.js` 中间件 / prod: `fulgur-remoteEntry.js`） |
+| 子应用生命周期 mount/unmount | 页面级 exposes（组件即入口，无生命周期样板） |
+| 主子应用 window 隔离/沙箱 | 无沙箱：同 realm 直渲染（`window.xxx` 全局桥自然可用） |
+| props 传递（qiankun 传参） | 组件 props（路由通道 = params+query 合并；弹窗通道 = 显式 v-bind） |
+| 公共依赖 externals/主应用共享 | `shared`（singleton 协商，"已加载优先"） |
+| `qiankun` 运行时 + single-spa | `virtual:fulgur-runtime`（15KB 级，无 single-spa） |
+
+## 二、迁移步骤（真实案例顺序）
+
+1. **子应用装插件 + exposes**：把原菜单路由表逐页映射为 `exposes`（`./pages/bpm/task/todo` 对应路由 `bpm/task/todo`）。
+2. **shared 声明**：vue/pinia/vue-router 设 singleton；**不要**把业务库（element-plus/avue/dayjs 等）放 shared——插件会在预构建与构建期自动处理其内部对 shared 键的引用（UMD/CJS-only 依赖支持）。
+3. **宿主装插件 + remotes**：菜单 URL 通道由 `resolveFulgurPageFromPath` 按路由表解析 spec（见 `admin/src/qiankun/fulgurPages.ts`）。
+4. **全局环境迁移**：子应用依赖宿主的全局（用户/字典 store、i18n、全局组件）→ 写 `federatedBoot.ts` expose，宿主加载页面前 `bootRemoteOnce` 执行；失败必须显式报错（H3）。
+5. **路由参数**：页面组件用 `defineProps` 声明参数（id/taskId 等）；宿主路由通道把 params+query 作为 props 传入。
+6. **跨应用弹窗**：原 iframe 嵌子应用页 → `fulgurPageComponent(spec)` 直渲染 + props（见 FormDetailsModal）；真外链（数据驱动 URL、AMIS 站点）保留 iframe。
+7. **公共依赖坑**：
+   - 子应用 axios 的响应解包形状要和后端一致（jeecg `{success,result}` vs yudao `{code,data}`）
+   - 子应用全局注册（指令/组件）失败必须显式报错，禁止"忽略继续"
+   - 修改态表单禁用逻辑、页面门控（currentStep 等）保持原版语义
+
+## 三、验收清单（从本案例提炼）
+
+- [ ] 21+ 页双环境（dev 双 server / prod NGINX）路由级渲染一致
+- [ ] 每页写操作闭环（新增/编辑/删除/发布/导出导入/审批）与原版逐项一致
+- [ ] 控制台零报错（21 页 × 2 环境）
+- [ ] 零 iframe（跨应用页面与弹窗；PDF/外链/数据驱动 URL 除外）
+- [ ] 零兜底：联邦不可用显式报错（杀 remote 故障注入）
+- [ ] 装后可用：npm pack → 干净项目 dev+prod（e2e/h7-install-test.sh）
+
+## 三B、首次使用避坑清单（真实迁移踩坑实录，全文见仓库 README「避坑指南」节）
+
+| # | 坑 | 症状 | 解法 |
+|---|-----|------|------|
+| 1 | 插件升级后未清 `.vite` | 页面渲染回旧逻辑 / 门面签名漂移 404 | `rm -rf node_modules/.vite` + 重启 dev + 换浏览器 profile |
+| 2 | pnpm 装 tarball 软链断链 | `Cannot find module '@fulgurjs/federation'` | 重新 `pnpm add -D <tgz>` 并验证目录可达 |
+| 3 | UMD/CJS 依赖被移出预构建 | dev 裸 CJS 白屏、`Cannot destructure property 'node'` | 放回 `optimizeDeps.include`（插件自动外部化 shared 键） |
+| 4 | 给 shared 依赖加 ESM 别名 | 构建期 `xxx.default.extend is not a function` | **build 必删**（prod rollup 双重 interop，2026-09-16 二次定案）；dev 侧若该依赖已移出预构建（如 element-plus），其 CJS 子路径需 dev 专用别名兜住（`command==='serve'` 才注入） |
+| 5 | env 同步脚本回写 | 手改的 `.env.*` 被「还原」 | 改同步脚本的源头（如 `.env.backend`） |
+| 6 | 项目构建自身 env 缺键 | `Cannot read properties of undefined (reading 'split')`（如 VITE_BUILD_COMPRESS） | 按项目构建要求补齐 env 键 |
+| 7 | 登录异步链未完成就断言 | e2e 偶发被弹回登录页 | 等「登录表单消失」而非固定秒数；后台慢链 ≥15s |
+| 8 | 多版本组件库 CSS | 后加载覆盖 `:root` 变量 | 主流版本变量一致则无感；升级时留意 |
+| 9 | 后端缺端点 | 404/401 资源报错 | 代理/NGINX 层加诚实空响应垫片（不伪造业务数据） |
+| 10 | 远程页面（exposes 目标文件）静态导入 `virtual:fulgur-runtime` | 宿主跨源加载后渲染上下文破坏：resolveComponent / withDirectives / "Missing ref owner" 告警、内容区静默空白 | 改走宿主单例（见下节）；插件 dev 下已对此显式报错拦截 |
+
+### 三B-1、远程页面如何取宿主运行时（跨源单例契约）
+
+exposes 目标文件（被宿主跨源加载的远程页面/组件）**禁止静态 `import 'virtual:fulgur-runtime'`**——
+该导入会改由远程 dev server 求值，在远程模块图内实例化第二份运行时副本，破坏渲染上下文
+（插件 dev 下已对此显式报错，错误信息即指向本节）。
+
+正确写法（二选一，取到的是同一份页面级单例）：
+
+```ts
+// ① 直接读全局单例（bpm detail 页先例）
+const runtime = (globalThis as any).__FULGUR_RUNTIME__
+const mod = await runtime.loadRemote('host-app/UserProfile')
+
+// ② 经独立产物 getRuntime()（最小宿主/无构建场景，见 manual §5.1）
+import { getRuntime, version } from '/fulgur-runtime.js'
+const mod = await getRuntime().loadRemote('mes-bpm/./TaskCard')
+```
+
+运行时单例带 `version` 字段（与插件包版本同源）用于跨源副本一致性诊断；
+宿主页面（非 exposes 目标）不受此限，可正常静态导入虚拟模块。
+
+## 四、乾坤下线顺序
+
+1. 联邦模式全量验收（本清单）
+2. `QIANKUN_OPEN=false` 固化，保留一个版本周期回滚能力
+3. 删除 qiankun 注册层（admin/src/qiankun/apps.ts 等）与 single-spa 依赖
+4. 子应用可独立部署 ⇄ 宿主消费双形态长期保留

package/examples/fulgur.config.example.ts

@@ -0,0 +1,41 @@
+/**
+ * 通用起步样例：一个宿主 + 一个远程（应用名/路径均为虚构）。
+ * 用法：npx fulgur init --config examples/fulgur.config.example.ts
+ * 完整字段说明见 `fulgur init` 生成的起步模板（fulgur init --template fulgur.config.ts）。
+ */
+import { defineFulgurConfig } from '@fulgurjs/federation/config'
+
+export default defineFulgurConfig({
+  root: process.cwd(),
+  apps: [
+    {
+      path: 'apps/host',
+      name: 'host-app',
+      port: 5173,
+      base: '/',
+      host: {
+        remotePrefixes: { '/remote-a/': 'remote-a' },
+        remotes: {
+          'remote-a': { dev: 'http://localhost:5174/remote-a', prod: '/remote-a' },
+        },
+        pages: [
+          { route: '/remote-a/home', name: 'RemoteAHome', title: '首页' },
+          { route: '/remote-a/detail/:id', name: 'RemoteADetail', spec: 'pages/remote-a/detail', title: '详情' },
+        ],
+      },
+    },
+    {
+      path: 'apps/remote-a',
+      name: 'remote-a',
+      port: 5174,
+      base: '/remote-a',
+      remote: {
+        exposes: {
+          './pages/remote-a/home': './src/views/Home.vue',
+          './pages/remote-a/detail': './src/views/Detail.vue',
+        },
+      },
+    },
+  ],
+  deploy: { webRoot: '/var/www/your-site', listen: 8080 },
+})

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "@fulgurjs/federation",
+  "version": "0.4.2",
+  "type": "module",
+  "description": "Vite Module Federation with full Webpack MF parity. Dev & production, no compromise.",
+  "license": "MIT",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./pages": {
+      "types": "./dist/pages.d.ts",
+      "import": "./dist/pages.js",
+      "require": "./dist/pages.cjs"
+    },
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "import": "./dist/config.js",
+      "require": "./dist/config.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "DESIGN.md",
+    "examples",
+    "docs/manual.html",
+    "docs/迁移指南.md",
+    "docs/webpack-mf-对照与缺口.md",
+    "docs/沙箱边界审计.md",
+    "docs/P5-vite7-8兼容矩阵.md",
+    "docs/vite-upstream-issue-irregexp.md"
+  ],
+  "scripts": {
+    "build": "cp ../../README.md README.md && mkdir -p docs && cp ../../docs/manual.html ../../docs/迁移指南.md ../../docs/webpack-mf-对照与缺口.md ../../docs/沙箱边界审计.md ../../docs/P5-vite7-8兼容矩阵.md ../../docs/vite-upstream-issue-irregexp.md docs/ && cp ../../CHANGELOG.md CHANGELOG.md && cp ../../DESIGN.md DESIGN.md && rm -rf examples && cp -r ../../examples examples && esbuild src/runtime/index.ts --bundle --format=esm --target=es2022 --minify --outfile=dist/runtime.js && node scripts/gen-runtime.mjs && tsup src/index.ts src/pages.ts src/config.ts --format esm,cjs --dts --external vite --target node18 --clean && esbuild src/cli.ts --bundle --format=esm --target=node18 --platform=node --outfile=dist/cli.js && esbuild src/runtime/index.ts --bundle --format=esm --target=es2022 --minify --outfile=dist/runtime.js",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "es-module-lexer": "^1.6.0",
+    "magic-string": "^0.30.17"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.1.0"
+  },
+  "peerDependencies": {
+    "vite": ">=5.0.0"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chenmingye/fulgur-federation.git",
+    "directory": "packages/plugin"
+  },
+  "homepage": "https://github.com/chenmingye/fulgur-federation#readme",
+  "author": "chenmingye (Jason)",
+  "bugs": {
+    "url": "https://github.com/chenmingye/fulgur-federation/issues"
+  },
+  "keywords": [
+    "vite",
+    "module-federation",
+    "federation",
+    "micro-frontend",
+    "vite-plugin",
+    "webpack-federation"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "fulgur": "./dist/cli.js"
+  }
+}