[特殊字符] 微前端部署实战：Nginx 配置 HTTPS 与 CORS 跨域解决方案（示例版）

🌐 微前端部署实战：Nginx 配置 HTTPS 与 CORS 跨域解决方案（示例版）

作者：运维/前端开发

日期：2025 年 10 月 28 日

场景：基于 qiankun 的微前端架构，主应用与子应用分别部署在不同端口

🔍 一、问题背景

在一次微前端项目部署中，主应用运行在 https://app.example.com:8600，子应用 subapp-demo 运行在 https://app.example.com:8602。使用 qiankun 框架加载子应用时，页面始终无法加载，浏览器控制台报错：

text 复制代码

Access to fetch at 'https://app.example.com:8602/' from origin 'https://app.example.com:8600' 
has been blocked by CORS policy: 
The 'Access-Control-Allow-Origin' header has a value 'https://app.example.com:8602' 
that is not equal to the supplied origin.

经过排查，发现是 CORS 配置错误导致子应用拒绝了主应用的访问请求。本文将详细记录问题排查过程，并系统介绍 Nginx 配置 HTTPS 与 CORS 的最佳实践。

✅ 二、问题根源分析

❌ 错误配置片段

nginx 复制代码

add_header 'Access-Control-Allow-Origin' 'https://app.example.com:8602' always;

📌 错误点解析

Access-Control-Allow-Origin 表示"允许谁访问我"。
子应用运行在 8602 端口，它应该允许主应用 https://app.example.com:8600 访问。
但上述配置错误地将"允许来源"设置为自己，即 8602，导致浏览器拒绝跨域请求。

✅ 正确做法：子应用应允许主应用的域名（含端口）访问。

🛠 三、Nginx 配置 HTTPS 与 CORS 的完整步骤

第一步：准备 SSL 证书

HTTPS 需要 SSL 证书加密通信。你可以使用：

自签名证书（开发/测试环境）
Let's Encrypt 免费证书（生产环境）
商业 CA 证书（如 DigiCert、阿里云等）

生成自签名证书（示例）

bash 复制代码

openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
    -keyout app.example.com.key \
    -out app.example.com.pem \
    -subj "/CN=app.example.com"

将生成的 .pem 和 .key 文件放置在 Nginx 可访问路径，如 /etc/nginx/ssl/。

第二步：配置 Nginx HTTPS 服务（子应用）

nginx 复制代码

# 业务子应用（8602端口）
server {
    listen 8602 ssl;                          # 开启 HTTPS 监听 8602 端口
    server_name app.example.com;              # 服务器域名

    # SSL 证书配置
    ssl_certificate /etc/nginx/ssl/app.example.com.pem;
    ssl_certificate_key /etc/nginx/ssl/app.example.com.key;
    ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:HIGH:!aNULL:!MD5:!RC4:!DHE;
    ssl_protocols TLSv1.2 TLSv1.3;            # 支持的 TLS 协议版本
    ssl_prefer_server_ciphers off;            # 不优先使用服务器加密套件

    client_max_body_size 150M;                # 允许最大上传文件大小
    add_header X-Frame-Options SAMEORIGIN;    # 防止点击劫持，允许同源嵌套

    # ✅ 正确的 CORS 配置：允许主应用访问
    add_header 'Access-Control-Allow-Origin' 'https://app.example.com:8600' always;
    add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS' always;
    add_header 'Access-Control-Allow-Headers' 'DNT,User-Agent,Cache-Control,Content-Type,Sec-Fetch-Mode,If-Modified-Since,Range,Authorization' always;
    add_header 'Access-Control-Expose-Headers' 'Content-Length,Content-Range' always;

    location / {
        root   /var/www/subapp-demo/dist;
        index  index.html;
        try_files $uri $uri/ /index.html;      # 支持前端路由 history 模式
    }

    # 处理预检请求（OPTIONS）
    if ($request_method = 'OPTIONS') {
        add_header 'Access-Control-Allow-Origin' 'https://app.example.com:8600' always;
        add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS' always;
        add_header 'Access-Control-Allow-Headers' 'DNT,User-Agent,Cache-Control,Content-Type,Sec-Fetch-Mode,If-Modified-Since,Range,Authorization' always;
        add_header 'Access-Control-Max-Age' 86400;     # 预检结果缓存 24 小时
        add_header 'Content-Length' 0;
        return 204;                                   # 返回空响应
    }
}

第三步：参数详解

参数	含义	建议值
`listen 8602 ssl`	监听 8602 端口并启用 SSL	生产环境建议使用 443
`ssl_certificate`	SSL 证书路径	`.pem` 或 `.crt` 文件
`ssl_certificate_key`	SSL 私钥路径	`.key` 文件
`ssl_protocols`	支持的 TLS 版本	`TLSv1.2 TLSv1.3`
`ssl_ciphers`	加密套件	推荐使用前向安全（ECDHE）
`client_max_body_size`	最大请求体大小	根据业务调整（如文件上传）
`add_header X-Frame-Options SAMEORIGIN`	防止 iframe 劫持	安全必备
`Access-Control-Allow-Origin`	允许跨域访问的来源	必须是主应用地址
`Access-Control-Allow-Methods`	允许的 HTTP 方法	至少包含 `GET, OPTIONS`
`Access-Control-Allow-Headers`	允许的请求头	包含常用头，如 `Authorization`
`Access-Control-Max-Age`	预检请求缓存时间	`86400`（24 小时）

第四步：重启 Nginx

bash 复制代码

# 测试配置是否正确
sudo nginx -t

# 重新加载配置（无需重启服务）
sudo nginx -s reload

✅ 四、验证是否成功

访问主应用：https://app.example.com:8600
打开浏览器开发者工具 → Network 标签
查看对 https://app.example.com:8602/ 的请求：
- ✅ 状态码：200
- ✅ 响应头包含：
  复制代码
```
Access-Control-Allow-Origin: https://app.example.com:8600
```
- ✅ 控制台无 CORS 错误
- ✅ 子应用正常渲染

📝 五、常见错误总结

错误现象	原因	解决方案
`ERR_CONNECTION_TIMED_OUT`	域名/IP 或端口错误	检查主应用中 `entry` 配置
`ERR_FAILED 200 (OK)`	CORS 被拦截	检查 `Access-Control-Allow-Origin` 是否正确
`Access-Control-Allow-Origin` 值错误	写成了自己	必须写成调用方（主应用）地址
OPTIONS 请求失败	未处理预检	添加 `if ($request_method = 'OPTIONS')` 块
混合内容（Mixed Content）	HTTP 资源在 HTTPS 页面加载	确保所有资源使用 HTTPS

💡 六、最佳实践建议

使用域名代替 IP ：如 app.yourcompany.com，便于管理和证书申请。
统一 CORS 管理：建议由 Nginx 统一处理，避免前端代码注入错误头。
**生产环境避免 ***：Access-Control-Allow-Origin: * 不能与 withCredentials 共用，建议白名单。
使用 Let's Encrypt 自动续期 ：配合 certbot 实现证书自动更新。
日志监控：开启 Nginx access_log 和 error_log，便于排查问题。

🎯 结语

微前端架构中，跨域问题是最常见的部署障碍之一。通过正确配置 Nginx 的 HTTPS 与 CORS，不仅可以解决加载问题，还能提升系统安全性和稳定性。

本文通过一个真实案例，系统梳理了从问题发现、分析到解决的全过程，并提供了可复用的 Nginx 配置模板。希望对正在搭建微前端架构的你有所帮助！

📢 关键口诀 ：
"CORS 的 Allow-Origin 是写给'调用方'看的，不是写给'自己'看的！"

📌 附：主应用 qiankun 注册代码示例

js 复制代码

registerMicroApps([
  {
    name: 'subapp-demo',
    entry: 'https://app.example.com:8602',
    container: '#subapp-viewport',
    activeRule: '/subapp-demo',
  },
]);

如需本文的 Markdown 源码或 Nginx 配置模板，欢迎联系作者获取。

✅ 说明：本文中所有 IP 地址、域名、应用名称均为示例，实际部署时请替换为真实环境信息。

这篇文章现在可以安全地分享给团队、发布到知识库或作为新人培训材料使用。如果你还需要 PDF 或 Word 版本，我也可以帮你生成。