# @fulgurjs/federation 中文文档

规范地址：https://npmcn.com/package/%40fulgurjs/federation/

版本：6\.16\.22
npm 元数据更新时间：2026-11-14T12:11:24.620Z
中文译文更新时间：2026-11-15T16:29:22.006Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40fulgurjs/federation
原文对照：https://npmcn.com/package/%40fulgurjs/federation/?lang=original
项目主页：https://github.com/chenmingye/fulgurjs-federation#readme
源码仓库：https://github.com/chenmingye/fulgurjs-federation

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：3 MB，294 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：3 个
- peer 依赖：vue \>=3\.2\.0，vite \>=5\.1\.0，react \>=18\.0\.0 \<20，react-dom \>=18\.0\.0 \<20，vue-router \>=4\.1\.0 \<6，react-router-dom \>=6\.11\.0 \<8
- 首次发布：2026-09-19T11:41:29.549Z
- 最新版本发布：2026-11-14T12:11:24.215Z
- 近 30 天下载量：12708（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：191（近 12 个月 191 个）

## 中文简介

Vue和React的Vite模块联合会:远程模块,共享依赖和app桥.

## 安装

```sh
npm install @fulgurjs/federation
```

也可以使用：`pnpm add @fulgurjs/federation`、`yarn add @fulgurjs/federation`、`bun add @fulgurjs/federation`

## README

# @fulgurjs/federation

**让一个 Vite 应用使用另一个应用提供的组件、页面、函数或完整子应用。**

例如：主系统加载独立部署的审批页面，Vue 页面中嵌入 React 子应用，多个应用共享同一套依赖版本。提供方与使用方可以分仓库开发、独立构建部署。支持 Vue 3 与 React 18/19，Vite 5.1–8。

[English](https://github.com/chenmingye/fulgurjs-federation/blob/master/README.en.md) ｜ **[完整文档中心](https://github.com/chenmingye/fulgurjs-federation/blob/master/docs/README.md)**（中文 [docs/zh](https://github.com/chenmingye/fulgurjs-federation/blob/master/docs/zh/README.md) · English [docs/en](https://github.com/chenmingye/fulgurjs-federation/blob/master/docs/en/README.md)）

第一次接入完整应用，从[一条完整接入流程](https://github.com/chenmingye/fulgurjs-federation/blob/master/docs/zh/guide/first-integration.md)开始；保留原启动、复用初始化与预检参考[已有应用接入](https://github.com/chenmingye/fulgurjs-federation/blob/master/docs/zh/guide/existing-apps.md)。

**已有组件直接 expose 原文件；完整应用保留原业务入口并复用初始化，不默认搬 main、重复注册 UI 库或新建 Provider 包装。**

已有工程可先用 `fulgurjs init --plan` 预览接线，审查后再用 `--write`；复杂业务装配会明确列出人工待办。统一 `/vue`、`/react` 入口支持按使用裁剪，不需要改用内部路径。

## 快速开始

**新建工程**（推荐）：用 CLI 从完整模板创建可独立运行的联邦工程：

```bash
npx @fulgurjs/federation create vue-vue --dir my-federation
cd my-federation
pnpm dev
```

**已有工程接入**：安装后在 `vite.config.ts` 注册插件，应用代码按框架从统一入口导入：

```bash
npm add @fulgurjs/federation
```

```ts
// vite.config.ts —— 构建配置用包根
import federation from '@fulgurjs/federation'

export default {
  plugins: [
    // Keep the existing framework plugins.
    federation({
      name: 'host',
      remotes: { 'remote-a': { dev: 'http://localhost:5174', prod: '/remote-a' } },
      shared: { vue: { singleton: true } },
    }),
  ],
}
```

```ts
// Vue 应用代码统一入口 @fulgurjs/federation/vue
import { loadRemote, remoteComponent } from '@fulgurjs/federation/vue'
const RemoteButton = remoteComponent('remote-a/Button')
const math = await loadRemote('remote-a/math')
```

```tsx
// React 应用代码统一入口 @fulgurjs/federation/react
import { remoteComponent, useLoadRemote, RemoteErrorBoundary } from '@fulgurjs/federation/react'
```

```ts
// 框架无关的浏览器模块 @fulgurjs/federation/runtime（零 Vue/React 依赖）
import { loadRemote, loadShare } from '@fulgurjs/federation/runtime'
```

上面配置是已有 Vue 消费方的接线示意，保留原 Vite/Vue 插件和业务配置；remote-a 必须真实暴露 ./Button、./math，并在开发地址启动或生产路径部署。地址按实际 base 替换。React 消费方使用自己的框架 shared 配置与 /react API；跨框架 UI 使用完整应用桥接，不把另一框架组件直接交给 remoteComponent。需要整套可运行工程时直接使用上方 create。

## 导入入口

| 使用位置 | 入口 |
| --- | --- |
| Vite 配置、`FederationOptions` 类型 | `@fulgurjs/federation` |
| Vue 应用代码（组件/页面/桥接/路由同步） | `@fulgurjs/federation/vue` |
| React 应用代码（组件/页面/桥接/路由同步） | `@fulgurjs/federation/react` |
| 框架无关浏览器模块 | `@fulgurjs/federation/runtime` |

记忆口诀：应用跑什么框架，就从哪个框架入口导入；两者都要用的纯 TS 模块从 `/runtime`；Vite 配置从包根。

## 能力地图

-   **组件与模块**：`remoteComponent`（Vue/React）、`useLoadRemote`、`RemoteErrorBoundary`、`loadRemote` —— 失败显式错误态可重试，不静默兜底。
-   **逐页接入**：`definePages` + `createHostPages`（宿主页面路由表 → 远程页面），CLI `check-pages` 启动期契约核对。
-   **完整子应用桥接**：`defineApplication`（独立/嵌入共用装配；自定义契约可用 `defineBridgeApp`）+ `createVueBridgeApp` / `createReactBridgeApp`（宿主）；挂载/卸载、会话代次、卸载失败封锁。
-   **URL 同步**：`createVueBridgeNavigation` / `createReactBridgeNavigation`（宿主）+ Vue 工厂返回 `{ app, router }` / `createReactBridgeRouter`（子应用）；深链刷新、守卫取消、query/hash 保留。
-   **共享依赖**：singleton / requiredVersion / strictVersion / shareScope / eager，同步与异步裁决，React 18/19 多版本隔离。
-   **远程类型**：提供方随构建产出可分发声明（SFC 真实 props/泛型/重载），宿主 dev 自动同步——普通 import 与 `loadRemote`/`remoteComponent`/桥接工厂共用一套类型，拼错入口编译期报错；CLI `types` 供 CI 在 typecheck 前同步校验。 开发期默认只在公开合同边界内生成，不能安全提取或超预算时明确停止，不自动完整扫描；`dts.devCheck: "implementation"` 可启用完整静态实现检查；生产构建和 CLI 始终检查真实源码，类型就绪不代表业务实现检查通过。
-   **CLI**：`create` / `init` / `explain` / `types` / `check-pages` / `doctor` / `port`。

## 文档

| 需求 | 入口 |
| --- | --- |
| 系统架构 / 执行顺序 | [系统架构图](https://github.com/chenmingye/fulgurjs-federation/blob/master/docs/zh/guide/architecture.md) |
| 新建工程 / 已有项目接入 | [快速开始](https://github.com/chenmingye/fulgurjs-federation/blob/master/docs/zh/guide/getting-started.md) |
| Vue/React 组件与普通模块 | [组件与模块](https://github.com/chenmingye/fulgurjs-federation/blob/master/docs/zh/guide/components-and-modules.md) |
| 完整子应用 / 跨框架嵌套 | [子应用桥接](https://github.com/chenmingye/fulgurjs-federation/blob/master/docs/zh/guide/app-bridge.md) |
| 路由同步 / 刷新深链 | [URL 同步](https://github.com/chenmingye/fulgurjs-federation/blob/master/docs/zh/guide/url-sync.md) |
| 全部配置项与默认值 | [配置参考](https://github.com/chenmingye/fulgurjs-federation/blob/master/docs/zh/reference/configuration.md) |
| 全部 API 签名与语义 | [API 参考](https://github.com/chenmingye/fulgurjs-federation/blob/master/docs/zh/reference/api.md) |
| CLI 命令与退出码 | [CLI 参考](https://github.com/chenmingye/fulgurjs-federation/blob/master/docs/zh/reference/cli.md) |
| 错误码（现象/原因/修法） | [错误码总表](https://github.com/chenmingye/fulgurjs-federation/blob/master/docs/zh/reference/errors.md) |
| 按症状排错 / 兼容范围 | [排错](https://github.com/chenmingye/fulgurjs-federation/blob/master/docs/zh/troubleshooting/README.md) |
| 模板与示例运行 | [示例总览](https://github.com/chenmingye/fulgurjs-federation/blob/master/examples/README.md) |

## 示例

五个完整模板（`vue-vue` / `react-react` / `vue-host-react-remote` / `react-host-vue-remote` / `showcase`）与功能 Demo 统一维护在 [examples/](https://github.com/chenmingye/fulgurjs-federation/blob/master/examples/README.md)，均可整目录复制后独立安装运行。

## 贡献与安全

-   贡献流程见 [CONTRIBUTING.md](https://github.com/chenmingye/fulgurjs-federation/blob/master/CONTRIBUTING.md)；架构与发布见 [docs/maintainers/](https://github.com/chenmingye/fulgurjs-federation/blob/master/docs/maintainers/README.md)。
-   安全问题请按 [SECURITY.md](https://github.com/chenmingye/fulgurjs-federation/blob/master/SECURITY.md) 的渠道私下报告。

## License

[MIT](https://github.com/chenmingye/fulgurjs-federation/blob/master/LICENSE)

## 常见问题

### @fulgurjs/federation 是什么？

Vue和React的Vite模块联合会:远程模块,共享依赖和app桥\.

### 如何安装 @fulgurjs/federation？

在项目目录运行 npm install @fulgurjs/federation，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：vite（\>=5\.1\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 fulgurjs，可以用 npx fulgurjs 直接运行。

### @fulgurjs/federation 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @fulgurjs/federation 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @fulgurjs/federation 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @fulgurjs/federation 可以商用吗？

@fulgurjs/federation 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @fulgurjs/federation 的下载量有多少？

根据 npm 官方下载统计，@fulgurjs/federation 在 2026/10/16 – 2026/11/14 这 30 天内被下载 12,708 次，日均约 424 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @fulgurjs/federation 还在维护吗？

最新版本 6\.16\.22 发布于 2026/11/14（1 天前）；至今共发布 191 个版本，其中过去 12 个月发布了 191 个；首次发布于 2026/09/19。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。