micro-app 微前端项目部署指南

部署指南

本文档介绍如何将 micro-app 微前端项目部署到生产环境。

目录

• 部署方式
• 同域部署
• 跨域部署
• [Nginx 配置](#Nginx 配置 "#nginx-%E9%85%8D%E7%BD%AE")
• 环境变量配置
• 构建和部署步骤
• 常见问题

---

部署方式

micro-app 微前端项目支持两种部署方式：

1. 同域部署：主应用和所有子应用部署在同一域名下

   • 优点：无需配置 CORS，部署简单
   • 缺点：所有应用必须部署在同一服务器

2. 跨域部署：主应用和子应用部署在不同域名

   • 优点：可以独立部署和扩展
   • 缺点：需要配置 CORS，配置相对复杂

---

同域部署

目录结构

/usr/share/nginx/html/
├── main-app/
│   └── dist/          # 主应用构建产物
├── sub-app-1/
│   └── dist/          # 子应用 1 构建产物
├── sub-app-2/
│   └── dist/          # 子应用 2 构建产物
└── sub-app-3/
    └── dist/          # 子应用 3 构建产物

URL 映射

https://example.com/              → 主应用
https://example.com/sub-app-1/    → 子应用 1
https://example.com/sub-app-2/    → 子应用 2
https://example.com/sub-app-3/    → 子应用 3

Nginx 配置

使用 nginx/main-app.conf 配置文件：

# 复制配置文件
sudo cp nginx/main-app.conf /etc/nginx/sites-available/micro-app

# 创建符号链接
sudo ln -s /etc/nginx/sites-available/micro-app /etc/nginx/sites-enabled/

# 修改配置中的路径和域名
sudo nano /etc/nginx/sites-available/micro-app

# 测试配置
sudo nginx -t

# 重载配置
sudo nginx -s reload

环境变量配置

主应用 .env.production:

# 同域部署不需要配置，自动使用 window.location.origin
# VITE_DEPLOY_MODE=same-origin  # 默认值，可省略

---

跨域部署

目录结构

# 主应用服务器
/usr/share/nginx/html/main-app/dist/

# 子应用 1 服务器
/usr/share/nginx/html/sub-app-1/dist/

# 子应用 2 服务器
/usr/share/nginx/html/sub-app-2/dist/

# 子应用 3 服务器
/usr/share/nginx/html/sub-app-3/dist/

URL 映射

https://main.example.com/        → 主应用
https://sub1.example.com/         → 子应用 1
https://sub2.example.com/         → 子应用 2
https://sub3.example.com/         → 子应用 3

Nginx 配置

主应用服务器 ：使用 nginx/main-app.conf（仅配置主应用部分）

子应用服务器 ：每个子应用使用 nginx/sub-app.conf：

# 为每个子应用复制配置文件
sudo cp nginx/sub-app.conf /etc/nginx/sites-available/sub-app-1
sudo cp nginx/sub-app.conf /etc/nginx/sites-available/sub-app-2
sudo cp nginx/sub-app.conf /etc/nginx/sites-available/sub-app-3

# 创建符号链接
sudo ln -s /etc/nginx/sites-available/sub-app-1 /etc/nginx/sites-enabled/
sudo ln -s /etc/nginx/sites-available/sub-app-2 /etc/nginx/sites-enabled/
sudo ln -s /etc/nginx/sites-available/sub-app-3 /etc/nginx/sites-enabled/

# 修改每个配置文件中的 server_name 和路径
sudo nano /etc/nginx/sites-available/sub-app-1
sudo nano /etc/nginx/sites-available/sub-app-2
sudo nano /etc/nginx/sites-available/sub-app-3

# 测试配置
sudo nginx -t

# 重载配置
sudo nginx -s reload

重要：子应用必须配置 CORS 头，否则 micro-app 无法加载。

环境变量配置

主应用 .env.production:

# 跨域部署模式
VITE_DEPLOY_MODE=cross-origin

# 子应用入口地址
VITE_SUB_APP_1_ENTRY=https://sub1.example.com
VITE_SUB_APP_2_ENTRY=https://sub2.example.com
VITE_SUB_APP_3_ENTRY=https://sub3.example.com

---

Nginx 配置

主应用配置

参考 nginx/main-app.conf，主要配置：

1. 根路径 ：主应用部署在根路径 /
2. 子应用路径 ：每个子应用部署在 /sub-app-X/ 路径下
3. 路由回退 ：使用 try_files 确保 SPA 路由正常工作
4. 静态资源缓存：配置长期缓存策略

子应用配置

参考 nginx/sub-app.conf，主要配置：

1. CORS 头：必须配置，micro-app 需要跨域支持
2. OPTIONS 预检：处理跨域预检请求
3. 路由回退 ：使用 try_files 确保 SPA 路由正常工作
4. 静态资源缓存：配置长期缓存策略

关键配置说明

CORS 配置（子应用必须）:

add_header Access-Control-Allow-Origin * always;
add_header Access-Control-Allow-Methods 'GET, POST, OPTIONS, PUT, DELETE' always;
add_header Access-Control-Allow-Headers 'Content-Type, Authorization, X-Requested-With' always;

路由回退（SPA 必需）:

location / {
    try_files $uri $uri/ /index.html;
}

静态资源缓存:

location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
}

---

环境变量配置

开发环境

主应用 .env.development:

# 通常不需要修改，使用默认的 localhost 地址

子应用 .env.development:

# 根据实际需求配置
# VITE_API_BASE_URL=http://localhost:8080/api

生产环境

同域部署:

主应用 .env.production:

# 不需要配置，自动使用 window.location.origin

跨域部署:

主应用 .env.production:

VITE_DEPLOY_MODE=cross-origin
VITE_SUB_APP_1_ENTRY=https://sub1.example.com
VITE_SUB_APP_2_ENTRY=https://sub2.example.com
VITE_SUB_APP_3_ENTRY=https://sub3.example.com

子应用 .env.production:

# 根据实际需求配置
# VITE_API_BASE_URL=https://api.example.com

---

构建和部署步骤

1. 构建所有应用

# 在项目根目录执行
pnpm run build

构建产物会生成在：

• main-app/dist/
• sub-app-1/dist/
• sub-app-2/dist/
• sub-app-3/dist/

2. 配置环境变量

根据部署方式配置 .env.production 文件（见上文）。

3. 上传构建产物

同域部署:

# 上传所有构建产物到同一服务器
scp -r main-app/dist/* user@server:/usr/share/nginx/html/main-app/dist/
scp -r sub-app-1/dist/* user@server:/usr/share/nginx/html/sub-app-1/dist/
scp -r sub-app-2/dist/* user@server:/usr/share/nginx/html/sub-app-2/dist/
scp -r sub-app-3/dist/* user@server:/usr/share/nginx/html/sub-app-3/dist/

跨域部署:

# 主应用
scp -r main-app/dist/* user@main-server:/usr/share/nginx/html/main-app/dist/

# 子应用 1
scp -r sub-app-1/dist/* user@sub1-server:/usr/share/nginx/html/sub-app-1/dist/

# 子应用 2
scp -r sub-app-2/dist/* user@sub2-server:/usr/share/nginx/html/sub-app-2/dist/

# 子应用 3
scp -r sub-app-3/dist/* user@sub3-server:/usr/share/nginx/html/sub-app-3/dist/

4. 配置 Nginx

参考 [Nginx 配置](#Nginx 配置 "#nginx-%E9%85%8D%E7%BD%AE") 部分。

5. 测试部署

1. 访问主应用：https://example.com
2. 检查子应用加载是否正常
3. 检查路由跳转是否正常
4. 检查数据通信是否正常
5. 检查浏览器控制台是否有错误

---

常见问题

Q1: 子应用加载失败，显示 CORS 错误？

A: 检查子应用的 Nginx 配置是否包含 CORS 头：

add_header Access-Control-Allow-Origin * always;
add_header Access-Control-Allow-Methods 'GET, POST, OPTIONS' always;

Q2: 路由跳转后显示 404？

A: 检查 Nginx 配置是否包含路由回退：

location / {
    try_files $uri $uri/ /index.html;
}

Q3: 静态资源加载失败？

A: 检查：

1. 资源路径是否正确
2. Nginx 配置中的 alias 路径是否正确
3. 文件权限是否正确

Q4: 生产环境子应用地址不正确？

A : 检查主应用的 .env.production 配置：

# 跨域部署
VITE_DEPLOY_MODE=cross-origin
VITE_SUB_APP_1_ENTRY=https://sub1.example.com

Q5: 如何启用 HTTPS？

A: 参考 Nginx 配置文件中的 HTTPS 配置示例：

1. 获取 SSL 证书
2. 配置证书路径
3. 启用 HTTPS server 块
4. 配置 HTTP 重定向到 HTTPS

Q6: 如何配置 CDN？

A: 修改环境变量中的入口地址为 CDN 地址：

VITE_SUB_APP_1_ENTRY=https://cdn.example.com/sub-app-1