Umi.js项目中非根目录部署的Hash路由配置问题解析

问题背景

在使用Umi.js框架进行项目开发时，当我们需要将应用部署到非根目录下（如/dashboard子目录），同时使用Hash路由模式时，可能会遇到两个典型问题：

1. React Router报错提示：" is not able to match the URL "/" because it does not start with the basename"
2. 生成的HTML文件中资源引用路径不正确，仍然指向根目录而非配置的子目录

问题原因分析

这种现象的根本原因在于Umi.js项目中非根目录部署时的配置不完整。当我们在配置中设置了base参数为"/dashboard"时，虽然指定了应用部署的基础路径，但还需要配合其他相关配置才能完整支持非根目录部署。

解决方案

要解决这个问题，我们需要同时配置两个关键参数：

1. base：指定应用部署的基础路径
2. publicPath：指定静态资源的基础路径

在Umi.js的配置文件中（通常是.umirc.ts或config/config.ts），应该进行如下配置：

export default {
  base: '/dashboard',
  publicPath: '/dashboard/',
  history: {
    type: 'hash'
  }
}

配置详解

1. base配置：这个配置会传递给React Router，告知应用所有路由都应该基于/dashboard路径。这解决了路由匹配的问题。

2. publicPath配置：这个配置告诉Umi.js构建工具，所有静态资源（如JavaScript、CSS文件）都应该从/dashboard/路径加载。这解决了资源引用路径不正确的问题。

3. history.type配置：明确指定使用hash路由模式，确保路由模式与部署环境匹配。

注意事项

1. publicPath的值应该以斜杠结尾，如'/dashboard/'而非'/dashboard'，这可以避免潜在的路径解析问题。

2. 在开发环境下，Umi.js默认会正确处理这些路径，但在生产环境构建时需要确保这些配置正确。

3. 如果使用CDN部署静态资源，publicPath应该指向CDN的完整URL路径。

总结

在Umi.js项目中实现非根目录部署时，特别是使用Hash路由模式的情况下，必须同时配置base和publicPath两个参数。这种配置方式确保了路由匹配和资源加载都能正确处理，避免了常见的部署问题。通过正确理解和使用这些配置项，开发者可以轻松地将Umi.js应用部署到任意子路径下。