Umi.js 项目中二级目录部署导致 clientLoader 失效问题解析

问题背景

在使用 Umi.js 4.1.1 版本开发项目时，当将项目部署到二级目录（如 http://127.0.0.1:8000/dist/）后，发现首页组件中的 clientLoader 方法在首次访问时不会执行。这个问题在生产环境中尤为关键，因为很多项目都需要部署在二级目录下。

现象分析

具体表现为：

1. 当访问二级目录根路径时（如 /dist/），clientLoader 方法不会触发
2. 手动添加 hash 路由（如 /dist/#/）后，clientLoader 方法可以正常执行
3. 与 Umi 3.x 版本不同，新版本不会自动跳转到 hash 地址

根本原因

这个问题的主要原因是路由配置不匹配。在 Umi.js 项目中，当需要部署到子路径时，必须正确配置 base 参数。如果没有正确设置 base 值，会导致路由匹配失败，进而影响 clientLoader 的执行。

解决方案

正确的配置方式是在 .umirc.ts 或 config/config.ts 中设置与部署路径一致的 base 值：

{
  // 其他配置...
  base: '/dist/', // 必须与部署路径一致
  publicPath: process.env.NODE_ENV === 'production' ? './' : '/',
  history: { type: 'hash' },
  clientLoader: {},
  // 其他配置...
}

配置要点

1. base 配置必须与实际的部署路径完全一致，包括前后的斜杠
2. 在开发环境和生产环境可能需要不同的 publicPath 设置
3. 使用 hash 路由时，确保 history.type 设置为 'hash'
4. 显式启用 clientLoader 功能

最佳实践

对于需要在不同环境部署的项目，建议采用动态配置：

const isProd = process.env.NODE_ENV === 'production';

export default {
  base: isProd ? '/dist/' : '/',
  publicPath: isProd ? './' : '/',
  // 其他配置...
}

总结

Umi.js 项目在二级目录部署时，正确配置 base 参数是确保路由和 clientLoader 正常工作的关键。开发者需要特别注意部署路径与配置的一致性，特别是在生产环境和开发环境可能有不同部署路径的情况下。通过合理的配置，可以避免这类路由匹配问题，确保应用的完整功能正常运行。