#server.historyApiFallback

• 类型： boolean | HistoryApiFallbackOptions
• 默认值： false

historyApiFallback 用于支持基于 history API 的路由，当用户访问不存在的路径时，自动返回指定的 HTML 文件，避免出现 404 错误。

当 Rsbuild 默认的 页面路由 行为无法满足你的需求时，例如，希望在访问 / 时可以访问 main.html ，你可以通过 server.historyApiFallback 配置项来实现这个功能。

#示例

将 server.historyApiFallback 设置为 true 后，未匹配到资源且满足以下条件的请求会返回 index.html。

export default {
  server: {
    historyApiFallback: true,
  },
};

当满足以下条件时，Rsbuild 会将请求的路径重写为你指定的 index 文件：

• 请求方式为 GET 或 HEAD
• Accept 请求头包含 text/html 或 */*（默认接受的类型），且不以 application/json 开头
• 请求路径的最后一段不包含 .，除非启用了 disableDotRule
• 请求路径未匹配到 rewrites 中定义的任何模式

#选项

server.historyApiFallback 也支持传入一个对象来自定义行为。

#index

• 类型： string
• 默认值： '/index.html'

指定当启用 History API fallback 时返回的默认 HTML 文件。

例如，设置 historyApiFallback.index 为 /main.html 后，当用户访问未命中的路由时，服务器会自动返回 main.html 作为回退页面。

export default {
  source: {
    entry: {
      main: './src/index.ts',
    },
  },
  server: {
    historyApiFallback: {
      index: '/main.html',
    },
  },
};

#rewrites

• 类型：

type Rewrites = Array<{
  from: RegExp;
  to: string | ((context: HistoryApiFallbackContext) => string);
}>;

• 默认值： []

rewrites 用于在 History API fallback 发生时，自定义请求路径与页面文件之间的映射。

当请求未匹配到静态资源时，Rsbuild 会按顺序检查这些规则，并应用第一条匹配的规则。重写规则在点号规则之前执行，只修改服务器内部的 URL，不会发送 HTTP 重定向。

export default {
  server: {
    historyApiFallback: {
      rewrites: [
        // 为根路径返回 landing 页面
        { from: /^\/$/, to: '/views/landing.html' },
        // 当访问 /subpage 开头的路径时，返回 subpage.html
        { from: /^\/subpage/, to: '/views/subpage.html' },
        // 其他所有路径返回自定义的 404 页面
        { from: /./, to: '/views/404.html' },
      ],
    },
  },
};

#htmlAcceptHeaders

• 类型： string[]
• 默认值： ['text/html', '*/*']

指定用于匹配 Accept 请求头的值。如果 Accept 请求头以 application/json 开头，即使同时匹配此列表，也会跳过该请求。

export default {
  server: {
    historyApiFallback: {
      htmlAcceptHeaders: ['text/html', 'application/xhtml+xml'],
    },
  },
};

#disableDotRule

• 类型： boolean
• 默认值： false

默认情况下，未匹配到重写规则且路径最后一段包含点（.）的请求会被视为文件请求，不会被重写为 index。

将 disableDotRule 设置为 true 后，这一行为会被关闭，此类请求也会被重写为 index。

export default {
  server: {
    historyApiFallback: {
      disableDotRule: true,
    },
  },
};