部署到S3桶后单页应用(SPA)路由失效问题求助

问题描述 #

我已经将Root应用和其他微前端(MFE)部署到了S3桶中，目前可以正常加载应用的首页("/")，但导航到其他页面时会抛出"Not Found"错误。

我使用了microfrontend-layout来定义single-spa-router，相关配置如下：

microfrontend-layout.html

<single-spa-router>
  <application name="@TEST/app1"></application>

  <main>
    <route path="/" exact>
      <application name="@TEST/app2"></application>
    </route>
    <route path="/contact">
      <application name="@TEST/app3"></application>
    </route>
    <route path="/angular">
      <application name="angular-app"></application>
    </route>
    <route path="/mfe1">
      <application name="@TEST/mfe1"></application>
    </route>
    <route path="/app4">
      <application name="@TEST/app4"></application>
    </route>
    <route default>
      <h1>404 Not Found</h1>
      <application name="@TEST/"></application>
    </route>
  </main>
</single-spa-router>

Route-config.js

import { registerApplication, start } from "single-spa";
import * as singleSpa from 'single-spa';
import {
  constructApplications,
  constructRoutes,
  constructLayoutEngine,
} from "single-spa-layout";
import microfrontendLayout from "./microfrontend-layout.html";

const routes = constructRoutes(microfrontendLayout);
const applications = constructApplications({
  routes,
  loadApp({ name }) {
    return System.import(name);
  },
});
const layoutEngine = constructLayoutEngine({ routes, applications });

applications.forEach(registerApplication);
layoutEngine.activate();
start();

我通过yarn run build生成dist文件夹，然后手动上传到S3桶（没有使用yml文件或流水线）。本地运行完全正常，但部署后路由就失效了，请问部署前还需要做什么配置吗？

问题分析与解决方案 #

这是单页应用(SPA)部署到S3这类静态存储服务时的典型问题，核心原因是：
S3是静态文件托管服务，它会将每个路由路径当作物理文件路径去查找对应的资源，但SPA的前端路由是由JavaScript在浏览器端处理的，这些路由并没有对应的实际文件存在，所以S3会返回404错误。

下面是具体的解决步骤：

1. 配置S3静态网站托管的错误文档

• 登录AWS控制台，打开你的S3桶，进入属性标签页
• 找到静态网站托管模块（若未开启，先勾选"启用静态网站托管"）
• 在错误文档输入框中填写index.html，点击保存。这样当S3找不到对应路径的文件时，会自动返回根目录的index.html，让前端路由接管请求处理。

2. 确认S3桶的权限配置

确保你的桶策略允许所有路径的请求都能访问到index.html，避免给特定路由路径设置访问限制。如果你的应用是公开访问的，要保证index.html和其他静态资源的权限是公开可读的。

3. 若使用CloudFront CDN（常见场景）

如果你的S3桶前面配置了CloudFront来加速访问，还需要额外配置错误页面重定向：

• 进入CloudFront控制台，找到对应的分发，切换到错误页面标签页
• 点击"创建自定义错误响应"：
  • 选择HTTP错误代码为404
  • 自定义响应页面路径填写/index.html
  • HTTP响应代码选择200（确保返回200状态码，避免影响用户体验和SEO）
• 保存配置后，等待CloudFront的分发更新生效（通常需要几分钟）。

4. 修正single-spa路由的小问题

观察你提供的microfrontend-layout.html，默认路由中的应用名写的是<application name="@TEST/"></application>，这明显是个笔误，应该填写具体的应用名称（比如@TEST/app4或者专门的404处理应用），否则会导致默认路由的应用加载失败，建议及时修正。

验证方法 #

完成上述配置后，尝试直接访问/contact、/angular这类路由，或者刷新页面，应该就能正常加载对应的微前端应用了。

备注：内容来源于stack exchange，提问作者R9102