Umi.js 中配置 Hash 路由导致页面空白的解决方案

问题现象

在使用 Umi.js 4.0.76 版本开发项目时，当在配置文件 .umirc.ts 中设置了 history: { type: 'hash' } 并同时配置了 base: './' 后，本地运行 dev 命令会出现页面空白的问题。控制台会显示如下错误信息：

<Router basename="/."> is not able to match the URL "/" because it does not start with the basename, so the <Router> won't render anything.

问题分析

这个问题的根本原因在于路由配置的冲突。让我们深入分析几个关键配置项：

1. base 配置：base: './' 设置了应用的基础路径为当前目录
2. publicPath 配置：process.env.NODE_ENV === 'production' ? './' : '/' 设置了生产环境下静态资源路径为相对路径
3. history 配置：type: 'hash' 启用了哈希路由模式

当这些配置组合在一起时，Umi.js 内部的路由器（Router）会尝试匹配带有基础路径的 URL。由于我们设置了 base: './'，路由器期望所有路径都以 /. 开头，但实际上访问的路径是 /，导致匹配失败，从而不渲染任何内容。

解决方案

根据 Umi.js 官方成员的回复，最简单的解决方案是移除 base 配置项。这是因为：

1. 在哈希路由模式下，base 配置通常不是必需的
2. 哈希路由的 URL 格式为 /#/path，不受基础路径影响
3. 移除后，路由器会直接匹配 /#/ 路径，与路由配置中的 path: "/" 能够正确匹配

配置建议

对于使用哈希路由的项目，推荐采用以下配置方式：

// .umirc.ts
export default {
  publicPath: process.env.NODE_ENV === 'production' ? './' : '/',
  history: {
    type: 'hash',
  },
  routes: [
    { path: "/", component: "index" },
    // 其他路由配置...
  ],
}

深入理解

哈希路由的特点

哈希路由（Hash Router）通过 URL 的哈希部分（# 后面的内容）来实现前端路由，具有以下特点：

1. 兼容性好，能在所有浏览器中工作
2. 不需要服务器端特殊配置
3. URL 变化不会导致页面刷新
4. 适合静态文件部署的场景

基础路径(base)的作用

base 配置项主要用于：

1. 设置应用的根路径
2. 当应用不是部署在域名根目录下时使用
3. 影响路由匹配和静态资源路径

但在哈希路由模式下，这些功能大多由 publicPath 和哈希路由自身机制处理，因此通常不需要额外配置 base。

总结

在 Umi.js 项目中配置哈希路由时，需要注意路由配置的简洁性。当遇到页面空白问题时，首先检查路由配置是否冲突，特别是 base 和 history.type 的组合。对于大多数哈希路由场景，移除 base 配置即可解决问题，同时保持路由功能的完整性。