qiankun 主子应用部署教程（Nginx 小白版）

 🚀微前端架构（qiankun）已经成为前端工程化的主流方案之一。很多同学本地开发时都能跑起来，但是一到 线上部署，就会遇到 子应用跨域、Vue Router history 刷新 404、Nginx 配置疑惑 等一堆问题。

这篇文章就是给 小白开发者 准备的，从零开始带你搞清楚：

✅ 主应用 / 子应用的区别
✅ 本地开发和线上部署有什么不同
✅ Nginx 配置要点
✅ 跨域 (CORS) + Vue history 模式的完整解决方案

---

一、主子应用区别（必读）

在微前端架构中：

• 主应用 (基座)

  • 负责整体框架和路由调度（如 qiankun、iframe）。

  • 自身要能运行 Vue 应用。

  • 需要加载子应用的 HTML、JS、CSS。

• 子应用

  • 独立打包部署的 Vue 项目。

  • 必须支持 跨域 (CORS)，否则主应用无法访问它的资源。

  • 需要支持 Vue Router 的 history 模式刷新。

也就是说：

• 主应用：相当于门户，负责注册 / 加载子应用，一般不会被别人加载。

• 子应用：相当于插件，必须支持被主应用远程加载（需要 CORS）。

---

二、本地开发阶段

本地开发时，主子应用都是用 webpack-dev-server / vite dev 跑起来的，例如：

• 主应用 👉 http://localhost:8080

• 子应用 👉 http://localhost:8081

qiankun 的机制：主应用会请求子应用的入口 HTML，再去加载它的 JS / CSS。

💡 本地时一般不需要 Nginx，因为开发服务器默认会带上 CORS 头，主应用可以直接访问子应用。

但如果你遇到主应用加载子应用报跨域错误，则可以：

1️⃣ Vite (vite.config.ts)

在子应用里配置：

export default defineConfig({server: {port: 8081,cors: true, // 推荐用 cors 开启 CORSheaders: {'Access-Control-Allow-Origin': '*',},},
});

• key 是 server，不是 devServer

• Vite 官方文档明确指出：开发服务器配置要写在 server 下。

2️⃣ webpack-dev-server (webpack.config.js)

如果你用的是 webpack 的开发服务器，则配置是：

devServer: {port: 8081,headers: {'Access-Control-Allow-Origin': '*',},
}

• key 是 devServer

• 适用于 webpack 项目，而不是 Vite。

👉 本地不需要 Nginx，线上才需要 Nginx。

---

三、本地模拟线上环境（高级玩法）

有时候我们想提前模拟线上，主/子应用用不同的域名。

   我们可以在 hosts 里写：

127.0.0.1 main-app.localhost
127.0.0