#server.historyApiFallback

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

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

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

#示例

将 server.historyApiFallback 设置为 true 时，所有未匹配到实际资源的 HTML GET 请求都会返回 index.html，从而保证单页应用的路由能够正常工作。

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

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

• 请求方式为 GET 或 HEAD
• 请求头包含 text/html
• 请求路径中不包含 .，即不是直接的文件请求
• 请求路径未匹配到 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 发生时，自定义请求路径与页面文件之间的映射。

仅当请求未命中任何静态资源（即进入 fallback 阶段）时，这些规则才会被应用。所有规则会按照数组中的顺序依次匹配并执行。

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', '*/*']

用于覆盖匹配 HTML 内容请求时默认查询的 Accepts: 请求头。

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

#disableDotRule

• 类型： boolean
• 默认值： false

默认情况下，路径中包含点（.）的请求会被视为直接的文件请求，不会被重定向。

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

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