# 子应用开发
本文介绍如何基于平台子应用框架开发前端子应用。子应用以 iframe 方式嵌入平台页面,并通过父应用提供的共享上下文、组件代理和样式同步能力,与平台保持一致的登录态、权限、主题和交互体验。
# 适用场景
当业务功能需要以前端子应用的形式接入平台,且希望复用平台已有的 React Context、Redux Store、Ant Design 全局配置、通用组件、工具函数和样式主题时,可以使用该子应用开发框架。
开发前请先获取子应用工程代码,并在子应用工程目录下执行后续命令。
# 技术栈
子应用当前主要使用以下技术:
| 类型 | 技术 |
|---|---|
| 构建工具 | Vite、Node.js |
| 前端框架 | React、React Router、Redux |
| UI 组件 | Ant Design、Less |
| 开发语言 | JavaScript、TypeScript |
# 架构说明
子应用不独立打包 react、react-dom、react-redux 等核心运行时依赖,而是在运行时从父应用获取共享实例。这样可以避免 iframe 隔离导致的上下文丢失问题,保证子应用与父应用使用同一套 React 上下文和全局状态。
# React 实例共享
子应用通过 Vite 插件处理 React 相关导入,在运行时从父应用获取共享实例。父应用需要提供对应的共享上下文入口,子应用再基于该入口使用统一的 React、Redux 和全局配置。
# Portal 挂载
当子应用检测到处于父应用 iframe 环境时,不会自行执行独立渲染,而是将应用节点交给父应用,由父应用通过 Portal 方式挂载到 iframe 内部。
# 父应用模块代理
子应用通过 src/parent/ 下的代理文件使用父应用能力,包括组件、Hooks、Selectors 和工具函数。代理文件由脚本生成,开发者通常不需要手工维护。
src/parent/
├── components/index.ts
├── hooks/index.ts
├── selectors/index.ts
└── utils/index.ts
# 样式同步
子应用运行时会同步父应用的样式资源和 CSS Variables,使页面主题、字体、颜色和组件样式与平台保持一致。

# 目录结构
子应用仓库的核心目录如下:
frontend_embedded/
├── scripts/
│ ├── dev.mjs
│ └── generate-parent-bridge.mjs
├── src/
│ ├── parent/
│ ├── pages/
│ ├── routes/
│ ├── App.jsx
│ └── main.jsx
├── package.json
└── vite.config.js
| 路径 | 说明 |
|---|---|
scripts/dev.mjs | 联合开发启动脚本 |
scripts/generate-parent-bridge.mjs | 父应用桥接代理文件生成脚本 |
src/parent/ | 自动生成的父应用模块代理 |
src/pages/ | 子应用页面目录 |
src/routes/ | 子应用路由封装 |
src/App.jsx | 子应用根组件 |
src/main.jsx | 子应用入口,负责判断独立模式或父应用挂载模式 |
vite.config.js | Vite 构建配置 |
# 开发环境准备
首次开发前,需要先完成平台 npm 源配置和登录。npm 制品库的配置、认证和使用方式请参考制品库快速入门及制品库使用说明。
npm install --legacy-peer-deps
# 本地启动
在子应用仓库目录下执行:
npm start
该命令会启动联合开发环境,用于同时调试子应用和父应用。

如需指定代理路径和目标服务,可以通过环境变量配置:
CUSTOM_PROXY_PATH=/v1/test CUSTOM_PROXY_TARGET=http://127.0.0.1:8788 npm start -- --proxyHost https://平台访问地址
# 生产构建
执行以下命令生成生产环境构建产物:
npm run build
# 使用父应用能力
开发子应用时,应优先复用父应用已经提供的组件、工具函数、Hooks 和 Selectors,避免在子应用中重复实现平台通用能力。
import { Button } from '@/parent/components';
import { readableDuration } from '@/parent/utils';
import { getUserInfo } from '@/parent/selectors';
父应用组件代理支持 ref 透传,工具函数、Hooks 和 Selectors 通过代理对象在运行时调用父应用注册的能力。
# 新增页面
新增页面时,建议按照以下步骤处理:
- 在
src/pages/下新增页面目录。 - 在页面目录中维护页面组件、样式和接口请求逻辑。
- 在路由配置中注册页面路由。
- 优先从
@/parent/引入平台通用组件和能力。 - 启动本地开发环境,在父应用嵌入场景下验证页面表现。
# 更新父应用桥接代理
当 @ezone/subapp-toolkit 更新,或父应用暴露的组件、Hooks、Selectors、工具函数发生变化时,需要重新生成桥接代理文件。
node scripts/generate-parent-bridge.mjs
生成完成后,检查 src/parent/ 下的文件变化,并在子应用中按需引用新的能力。
# 开发注意事项
- 不要在子应用中重复安装或打包父应用已经共享的 React 核心依赖。
- 不要手工修改
src/parent/下的自动生成文件,确需更新时应重新执行生成脚本。 - 需要复用平台能力时,优先从
@/parent/引入。 - 页面样式应遵循平台现有规范,避免引入与平台主题冲突的全局样式。
- 接口请求、登录态、权限和跳转逻辑需要在父应用嵌入环境中验证。
- 独立模式可以用于基础调试,但最终效果应以父应用挂载场景为准。
# 常见问题
# 子应用是否可以独立运行?
可以用于基础调试,但完整的登录态、上下文、全局状态、样式和父应用能力需要在平台嵌入场景下验证。
# 父应用新增了组件,子应用为什么无法直接引用?
需要确认父应用是否已经暴露该组件,并在子应用中重新执行桥接代理生成脚本。
# 页面样式与平台不一致怎么办?
优先确认父应用样式是否已同步到子应用,再检查页面是否引入了覆盖平台主题的全局样式。
← 系统API MarkDown语法 →