qiankun 微前端子应用静态资源 404 问题解析：entry、Nginx 与 publicPath 的“三角关系”

qiankun 微前端子应用静态资源 404 问题解析：entry、Nginx 与 publicPath 的“三角关系”

在基于 qiankun 的微前端架构中，我们经常需要将子应用部署在独立的后端服务上，并通过主应用的 Nginx 反向代理来访问。一个典型的配置如下：

• Nginx 配置：

  location ^~/app1 {
      proxy_pass http://backend-server/subapp;
  }
  

• qiankun 注册：

  registerMicroApps([
    {
      name: 'subApp',
      entry: '/app1',
      container: '#container',
      activeRule: '/subapp',
    }
  ]);
  

主应用路由匹配 /subapp 时激活子应用，并通过 entry: '/app1' 加载子应用的 HTML。然而，经常会遇到子应用 HTML 能正常加载，但静态资源（JS、CSS）返回 404 的情况。本文将深入分析这一问题的根源，并提供可靠的解决方案。

问题现象

• 浏览器访问主应用的 /subapp 路径，子应用容器中渲染出了 HTML 内容，但页面样式全无，控制台报错：

  GET http://主域名/static/js/main.js net::ERR_ABORTED 404 (Not Found)
  

• 查看 Network 面板，发现所有静态资源请求的 URL 都没有带上预期的 /app1 前缀。
• 如果手动将 entry 和 Nginx location 都改为 /subapp，则一切正常。

关键概念

要理解这个问题，需要先理清三个核心概念：

1. 子应用的 publicPath
   这是子应用构建时确定的静态资源基础路径。它决定了 HTML 中引用的 JS、CSS 等资源的 URL 前缀。

   • 若 publicPath = '/'，则资源引用为 <script src="/static/js/main.js">。
   • 若 publicPath = '/app1/'，则资源引用为 <script src="/app1/static/js/main.js">。
   • 若 publicPath = './'（相对路径），则资源引用为 <script src="./static/js/main.js">，浏览器会根据当前页面路径自动拼接。

2. qiankun 的 entry 配置
   entry 指定了子应用的 HTML 入口地址。它可以是完整的 URL，也可以是相对路径。当配置为相对路径（如 /app1）时，浏览器会基于当前主应用的域名拼接成 主域名/app1 来请求 HTML。

3. Nginx location 匹配规则
   Nginx 根据请求的 URI 将请求转发到指定的后端。例如 location ^~/app1 表示所有以 /app1 开头的请求都会被代理到后端。

问题根源分析

让我们一步步追踪请求流程：

1. 主应用激活子应用：当用户访问主应用的 /subapp 路由时，qiankun 根据 activeRule 匹配，并通过 entry: '/app1' 发起请求。
2. 获取子应用 HTML：浏览器请求 主域名/app1，Nginx 根据 location ^~/app1 将请求转发到 http://backend-server/subapp，后端返回子应用的 HTML 文件。这一步通常成功。
3. 解析 HTML 并加载静态资源：浏览器解析返回的 HTML，根据其中 <script>、<link> 等标签的 src/href 发起二次请求。
4. 静态资源请求的 URL 生成：这个 URL 由 publicPath 决定。
   • 如果子应用的 publicPath = '/'，那么资源标签的路径是绝对路径 /static/js/main.js。浏览器会直接请求 主域名/static/js/main.js，这个请求不包含 /app1 前缀，因此不会被 Nginx 的 location /app1 捕获，导致 404。
   • 如果子应用的 publicPath = './'（相对路径），资源标签的路径是 ./static/js/main.js。浏览器会基于当前页面路径 主域名/app1/ 拼接成 主域名/app1/static/js/main.js，这个请求能被 location /app1 捕获，从而正确代理到后端。
   • 如果子应用的 publicPath = '/app1/'，资源标签的路径是 /app1/static/js/main.js，同样能被 location /app1 捕获。

由此可见，问题的核心在于子应用的 publicPath 产生的资源请求 URL 是否包含能被 Nginx location 匹配的前缀。如果 publicPath 是绝对路径 /，则资源请求不会带上 /app1，自然无法进入正确的 location。

为什么改成 /subapp 就好了？

当我们将 entry 改为 /subapp，并将 Nginx location 也改为 /subapp 后，如果子应用的 publicPath 仍为 /，资源请求仍然是 /static/js/main.js，按理说应该还是 404。但实际情况却能工作，这说明子应用的 publicPath 很可能被设置为了 /subapp/（绝对路径），或者使用了相对路径 ./ 并基于新的页面路径拼接出了正确的 URL。这也验证了“一致”的重要性：entry 路径、Nginx location 和子应用 publicPath 产生的资源路径必须形成正确的映射关系。

解决方案

方案一：保持 entry 与 Nginx location 一致（推荐）

让 entry 路径与 Nginx 代理的前缀相同，并确保子应用的 publicPath 能够产生以该前缀开头的资源请求。

• Nginx 配置：

  location ^~/subapp {
      proxy_pass http://backend-server/subapp;
  }
  

• qiankun 注册：

  entry: '/subapp',
  activeRule: '/subapp'
  

• 子应用 publicPath：建议设置为相对路径 './'，这样资源路径会自动基于当前页面路径（即 /subapp/）生成，无需关心绝对路径。或者明确设置为 /subapp/。

优点：配置简单，无需额外维护复杂的重写规则。

方案二：保留对外路径为 /app1，修改子应用 publicPath

如果你希望对外暴露的路径是 /app1（例如出于 URL 美观或遗留原因），则必须让子应用的所有静态资源请求都以 /app1 开头。

• 修改子应用构建配置，将 publicPath 设置为 /app1/：
  • Vue CLI：vue.config.js 中 publicPath: '/app1/'
  • Create React App：package.json 中 "homepage": "/app1" 或 .env 中 PUBLIC_URL=/app1
  • 其他 Webpack 项目：直接修改 output.publicPath
• 重新打包并部署子应用。
• Nginx 配置保持不变（proxy_pass http://backend-server/subapp;），因为 Nginx 会自动将 /app1/xxx 替换为 /subapp/xxx 转发。

优点：符合微前端的路径设计原则，稳定性高。
缺点：需要修改子应用并重新构建。

方案三：在 Nginx 中强制重写静态资源路径（不推荐）

如果因某些原因无法修改子应用的 publicPath，且其资源路径为绝对路径 /static/...，可以尝试在 Nginx 中增加额外的重写规则，将 /static/... 的请求也映射到 /app1/static/...。

# 处理静态资源，将 /static/xxx 重写为 /app1/static/xxx 再代理
location /static/ {
    rewrite ^/static/(.*) /app1/static/$1 break;
    proxy_pass http://backend-server;
}
# 子应用入口和其他请求
location ^~/app1 {
    proxy_pass http://backend-server/subapp;
}

缺点：这种方法极易引起冲突（如果主应用也有 /static 路径），且难以维护，仅可作为临时应急手段。

最佳实践建议

1. 子应用优先使用相对路径 publicPath: './'。这样资源路径会自动基于当前页面路径，能够很好地适应不同的部署环境，减少配置耦合。
2. 保持 entry 与 Nginx location 前缀一致，避免引入不必要的路径重写逻辑。
3. 明确 activeRule 与 entry 的关系：activeRule 是主应用的路由匹配规则，可以与 entry 不同，但通常建议保持一致以降低复杂性。
4. 在开发和调试时，善用浏览器开发者工具，观察 Network 面板中静态资源的请求 URL，快速定位是哪个环节出了问题。

总结

qiankun 微前端中子应用静态资源 404 的问题，绝大多数是由于 publicPath、entry 和 Nginx 代理路径三者之间的不匹配造成的。理解浏览器请求的完整流程，明确 publicPath 的作用，是解决此类问题的关键。通过本文的分析和提供的几种解决方案，希望能帮助你快速定位并解决类似问题，让微前端的集成更加顺畅。

如果你在实践中遇到其他诡异的问题，欢迎留言交流！