# iframe-micro-front-end

**Repository Path**: echo-52hz/iframe-micro-front-end

## Basic Information

- **Project Name**: iframe-micro-front-end
- **Description**: 使用iframe的方式实现微前端
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-13
- **Last Updated**: 2026-01-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# iframe 微前端方案

基于 iframe 实现的微前端解决方案，将多个独立的子应用通过 iframe 嵌入到主应用中，实现类似单页应用（SPA）的用户体验。

## 目录

- [方案概述](#方案概述)
- [核心原理](#核心原理)
- [项目结构](#项目结构)
- [快速开始](#快速开始)
- [核心功能实现](#核心功能实现)
- [注意事项](#注意事项)
- [优缺点分析](#优缺点分析)
- [参考资料](#参考资料)

## 方案概述

### 什么是 iframe 微前端？

iframe 微前端是利用浏览器原生的 `<iframe>` 标签，将不同的子应用嵌入到主应用的内容区域中。每个子应用运行在独立的浏览器上下文中，拥有独立的 window、document 和 JavaScript 运行环境。

### 为什么选择 iframe？

| 特性           | 说明                                               |
| -------------- | -------------------------------------------------- |
| **天然隔离**   | JS、CSS 完全隔离，不会相互污染                     |
| **技术栈无关** | 子应用可以使用任意技术栈（Vue、React、Angular 等） |
| **实现简单**   | 无需复杂的构建配置和运行时框架                     |
| **独立部署**   | 子应用可以独立开发、测试、部署                     |

## 核心原理

### 架构图

```
┌─────────────────────────────────────────────────────────────┐
│                      主应用 (Main App)                        │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │                     导航菜单                              │ │
│  └─────────────────────────────────────────────────────────┘ │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │                                                         │ │
│  │    ┌─────────────────────────────────────────────┐     │ │
│  │    │              iframe 容器                      │     │ │
│  │    │    ┌───────────────────────────────────┐    │     │ │
│  │    │    │         子应用 (Sub App)           │    │     │ │
│  │    │    │   独立的 window/document 环境      │    │     │ │
│  │    │    └───────────────────────────────────┘    │     │ │
│  │    └─────────────────────────────────────────────┘     │ │
│  │                                                         │ │
│  └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```

### 核心问题与解决方案

#### 1. URL 同步问题

**问题**：iframe 内部的页面跳转不会反映到浏览器地址栏

**解决方案**：

- 子应用通过 `postMessage` 通知主应用 URL 变化
- 主应用使用 `history.replaceState` 更新地址栏
- 维护 URL 映射表，将子应用 URL 转换为美化的短地址

```javascript
// 子应用发送消息
window.parent.postMessage(
  {
    type: "afterHistoryChange",
    data: { url: window.location.href },
  },
  "*"
);

// 主应用接收并更新地址栏
window.addEventListener("message", (event) => {
  if (event.data.type === "afterHistoryChange") {
    const mainPath = getMainAppPath(event.data.data.url);
    history.replaceState(null, "", mainPath);
  }
});
```

#### 2. 跳转拦截问题

**问题**：子应用内的跳转需要透传参数（如 `hideLayout`），第三方页面不能在 iframe 内打开

**解决方案**：拦截所有跳转方式

| 跳转方式          | 拦截方法                            |
| ----------------- | ----------------------------------- |
| A 标签点击        | 事件委托监听 click 事件             |
| location.href     | 提供 location2 代理对象             |
| window.open       | 重写 window.open 方法               |
| history.pushState | 重写 history.pushState/replaceState |

```javascript
// 拦截 history.pushState
const _rawPushState = history.pushState;
history.pushState = function (state, title, url) {
  const processedUrl = beforeRedirect(url); // 处理参数透传
  sendBeforeHistoryChange(processedUrl); // 通知主应用
  _rawPushState.call(history, state, title, processedUrl);
  sendAfterHistoryChange(processedUrl); // 通知完成
};
```

#### 3. 布局隐藏问题

**问题**：子应用嵌入时需要隐藏自身的导航菜单，避免双重导航

**解决方案**：通过 URL 参数 `hideLayout=1` 控制

```javascript
// 子应用检测参数并隐藏布局
const hideLayout = computed(() => {
  return route.query.hideLayout === "1";
});
```

```html
<nav v-if="!hideLayout" class="nav-menu">...</nav>
```

#### 4. Loading 状态管理

**问题**：页面切换时用户看到空白，体验不好；加载太快时 loading 闪屏

**解决方案**：

- 跳转前显示 loading（收到 `beforeHistoryChange` 消息）
- 跳转后隐藏 loading（收到 `iframeDOMContentLoaded` 消息）
- iframe onload 作为兜底
- **设置最小显示时间（默认 500ms），避免闪屏**

```javascript
// 创建 Loading 管理器，配置最小显示时间
const loading = createLoadingManager({
  defaultTip: "加载中...",
  timeout: 10000,
  minDisplayTime: 500, // 最小显示 500ms，避免闪屏
});

// 状态转换逻辑
function loadingReducer(state, action) {
  switch (action) {
    case "beforeHistoryChange":
      return { visible: true };
    case "afterHistoryChange":
    case "iframeDOMContentLoaded":
      return { visible: false };
  }
}
```

## 项目结构

```
iframe/
├── main-app/                 # 主应用 (端口 5173)
│   ├── src/
│   │   ├── components/
│   │   │   ├── IframeContainer.vue  # iframe 容器组件
│   │   │   ├── MainLayout.vue       # 主布局
│   │   │   └── NavMenu.vue          # 导航菜单
│   │   ├── config/
│   │   │   └── subApps.js           # 子应用环境配置
│   │   ├── utils/
│   │   │   ├── url-mapper.js        # URL 映射器
│   │   │   ├── message-handler.js   # 消息处理器
│   │   │   └── loading-manager.js   # Loading 管理器
│   │   └── views/
│   ├── .env.example                 # 环境变量配置示例
│   └── package.json
│
├── sub-app/                  # 子应用1 - 基础应用 (端口 5174)
│   ├── src/
│   │   ├── utils/
│   │   │   ├── layout-controller.js     # 布局控制器
│   │   │   ├── message-sender.js        # 消息发送器
│   │   │   └── redirect-interceptor.js  # 跳转拦截器
│   │   └── views/
│   └── package.json
│
├── sub-app-2/                # 子应用2 - 产品管理 (端口 5175)
│   └── ...
│
└── sub-app-3/                # 子应用3 - 用户管理 (端口 5176)
    └── ...
```

## 快速开始

### 安装依赖

```bash
# 根目录安装（包含 concurrently 并发工具）
pnpm install

# 安装所有子应用依赖
pnpm install:all
```

### 启动应用

```bash
# 一键启动所有应用（推荐）
pnpm dev
```

这会同时启动 4 个开发服务器，日志按颜色区分：

| 应用      | 端口 | 日志颜色 |
| --------- | ---- | -------- |
| main-app  | 5173 | 🔵 蓝色  |
| sub-app   | 5174 | 🟢 绿色  |
| sub-app-2 | 5175 | 🟡 黄色  |
| sub-app-3 | 5176 | 🟣 紫色  |

也可以单独启动某个应用：

```bash
pnpm dev:main   # 主应用
pnpm dev:sub    # 子应用1
pnpm dev:sub2   # 子应用2
pnpm dev:sub3   # 子应用3
```

### 访问应用

打开浏览器访问 `http://localhost:5173`，即可看到主应用首页，点击导航菜单切换不同的子应用。

## 核心功能实现

### 环境感知的子应用配置

子应用入口地址支持环境感知的动态配置，自动根据开发/生产环境返回正确地址：

```javascript
// config/subApps.js
import { getEntry, getAllEntries } from "../config/subApps.js";

// 获取单个子应用地址
const app1Entry = getEntry("app1"); // 开发环境: http://localhost:5174

// 获取所有子应用地址
const entries = getAllEntries();
// { app1: "http://localhost:5174", app2: "http://localhost:5175", ... }
```

**配置优先级**：环境变量 > 代码配置 > 默认值

**部署模式**：

- `same-origin`：同域部署，自动使用 `window.location.origin`
- `cross-origin`：跨域部署，使用配置的生产地址

环境变量配置示例（`.env.example`）：

```bash
VITE_DEPLOY_MODE=same-origin
# VITE_SUB_APP_1_ENTRY=//sub1.example.com
```

### URL 映射器

```javascript
// url-mapper.js - 使用动态配置的子应用地址
import { getEntry, getAllEntries } from "../config/subApps.js";

const SUB_APP_BASES = getAllEntries();

export const entryMap = {
  "/iframe/app1/home.html": `${SUB_APP_BASES.app1}/?hideLayout=1`,
  "/iframe/app2/products.html": `${SUB_APP_BASES.app2}/?hideLayout=1`,
  "/iframe/app3/users.html": `${SUB_APP_BASES.app3}/?hideLayout=1`,
};

// 根据子应用 URL 获取主应用路径
export function getMainAppPath(subAppUrl) {
  // 在映射表中查找，找不到则使用 base 页面兜底
}
```

### 消息通信协议

主应用和子应用通过 `postMessage` 通信，消息格式：

```typescript
interface Message {
  type: "beforeHistoryChange" | "afterHistoryChange" | "iframeDOMContentLoaded";
  data: {
    url: string;
  };
}
```

### 跳转拦截器初始化

```javascript
// 子应用 main.js
import { initRedirectInterceptors } from "./utils/redirect-interceptor";

const { location2, cleanup } = initRedirectInterceptors();
window.location2 = location2; // 提供给业务代码使用
```

## 注意事项

### 1. 跨域配置

子应用需要配置 CORS 允许跨域访问：

```javascript
// vite.config.js
export default {
  server: {
    cors: true,
    headers: {
      "Access-Control-Allow-Origin": "*",
    },
  },
};
```

### 2. 第三方页面处理

支付页面、OAuth 授权页面等第三方页面不能在 iframe 内打开（X-Frame-Options 限制），需要特殊处理：

```javascript
const THIRD_PARTY_WHITELIST = [
  "alipay.com",
  "weixin.qq.com",
  // ...
];

// 检测到第三方页面时，在新标签页或父页面打开
if (isThirdPartyUrl(url)) {
  window.open(url, "_blank");
  return;
}
```

### 3. 参数透传

子应用内部跳转时，需要透传 `hideLayout` 等参数：

```javascript
// 跳转前处理
function beforeRedirect(targetUrl) {
  const params = getPassthroughParams(); // 获取当前 URL 的 hideLayout 参数
  return addParamsToUrl(targetUrl, params); // 添加到目标 URL
}
```

### 4. 避免双滚动条

iframe 需要占满内容区域，避免出现双滚动条：

```css
.iframe-container {
  width: 100%;
  height: 100%;
  overflow: hidden;
}

.iframe-content {
  width: 100%;
  height: 100%;
  border: none;
}
```

### 5. 浏览器前进后退

监听 `popstate` 事件，同步更新 iframe 内容：

```javascript
window.addEventListener("popstate", () => {
  const subAppUrl = getSubAppUrl(location.pathname);
  iframeRef.src = subAppUrl;
});
```

### 6. 性能考虑

- 每个 iframe 都是独立的浏览器上下文，内存占用较高
- 首次加载子应用需要完整加载所有资源
- 建议对子应用进行代码分割和懒加载优化

## 优缺点分析

### 优点

| 优点          | 说明                                |
| ------------- | ----------------------------------- |
| ✅ 完全隔离   | JS、CSS、DOM 完全隔离，不会相互影响 |
| ✅ 技术栈无关 | 子应用可以使用任意框架              |
| ✅ 实现简单   | 无需复杂的构建配置                  |
| ✅ 独立部署   | 子应用可以独立开发和部署            |
| ✅ 稳定可靠   | 基于浏览器原生能力，兼容性好        |

### 缺点

| 缺点          | 说明                               |
| ------------- | ---------------------------------- |
| ❌ 性能开销   | 每个 iframe 都是独立的浏览器上下文 |
| ❌ 通信复杂   | 只能通过 postMessage 通信          |
| ❌ URL 同步   | 需要额外处理地址栏同步             |
| ❌ SEO 不友好 | 搜索引擎难以抓取 iframe 内容       |
| ❌ 用户体验   | 弹窗、全局样式等受限于 iframe 边界 |

### 适用场景

- ✅ 需要集成遗留系统
- ✅ 子应用技术栈差异大
- ✅ 对隔离性要求高
- ✅ 快速实现微前端 POC
- ❌ 对性能要求极高的场景
- ❌ 需要频繁跨应用通信的场景

## 与其他微前端方案对比

| 方案              | 隔离性     | 性能       | 实现复杂度 | 通信便利性 |
| ----------------- | ---------- | ---------- | ---------- | ---------- |
| **iframe**        | ⭐⭐⭐⭐⭐ | ⭐⭐       | ⭐⭐⭐⭐⭐ | ⭐⭐       |
| qiankun           | ⭐⭐⭐⭐   | ⭐⭐⭐⭐   | ⭐⭐⭐     | ⭐⭐⭐⭐   |
| micro-app         | ⭐⭐⭐⭐   | ⭐⭐⭐⭐   | ⭐⭐⭐⭐   | ⭐⭐⭐⭐   |
| wujie             | ⭐⭐⭐⭐⭐ | ⭐⭐⭐     | ⭐⭐⭐⭐   | ⭐⭐⭐     |
| Module Federation | ⭐⭐       | ⭐⭐⭐⭐⭐ | ⭐⭐       | ⭐⭐⭐⭐⭐ |

## 运行测试

```bash
# 运行所有测试
pnpm test

# 单独运行某个应用的测试
pnpm test:main   # 主应用
pnpm test:sub    # 子应用1
```

## 参考资料

- [为 iframe 正名，你可能并不需要微前端](https://juejin.cn/post/7185070739064619068) - 本项目的核心思路来源，详细分析了 iframe 方案在微前端场景下的实际应用价值

## License

MIT