解决 Umi.js 二级目录部署陷阱：让 clientLoader 重获新生

解决 Umi.js 二级目录部署陷阱：让 clientLoader 重获新生

【免费下载链接】umi A framework in react community ✨ 项目地址: https://gitcode.com/GitHub_Trending/um/umi

你是否曾在 Umi.js 项目部署到二级目录后，遭遇过 clientLoader 突然失效的棘手问题？本文将从问题根源出发，通过 3 个实战步骤带你彻底解决这一困扰众多开发者的技术难题，同时掌握 Umi.js 路由系统的底层工作机制。

问题场景还原

当我们将 Umi.js 项目部署在类似 https://example.com/admin 这样的二级目录时，常常会发现原本正常运行的 clientLoader 功能突然异常。具体表现为：

• 页面首次加载时数据无法正常获取
• 控制台出现 404 错误，指向错误的 API 路径
• 路由切换时 clientLoader 钩子函数不执行

这种问题在本地开发环境（通常使用根目录部署）中难以发现，只有在生产环境的二级目录部署时才会暴露，给项目上线带来意外阻碍。

问题根源解析

Umi.js 的 clientLoader 功能依赖于正确的路由路径解析，而二级目录部署会改变应用的基础路径（Base URL）。当基础路径配置不当，会导致 clientLoader 生成的请求路径与实际部署路径不匹配。

从项目源码分析，我们可以在 examples/client-loader/.umirc.ts 中看到默认配置：

export default {
  svgr: {},
  hash: true,
  routePrefetch: {},
  manifest: {},
  clientLoader: {},
};

这个默认配置没有设置 base 选项，因此在二级目录部署时会出现路径解析错误。

解决方案实施

步骤一：配置正确的基础路径

首先需要在配置文件中设置正确的 base 选项，指定你的二级目录路径。修改 .umirc.ts 或 config/config.ts 文件：

export default {
  // 其他配置...
  base: '/admin/', // 替换为你的二级目录路径
  clientLoader: {},
};

步骤二：调整 clientLoader 请求路径

在使用 clientLoader 时，确保所有 API 请求都使用相对路径或正确拼接基础路径。例如，在页面组件中：

export const clientLoader = async () => {
  // 使用相对路径，自动适应基础路径
  const res = await fetch('./api/data');
  return res.json();
};

步骤三：验证路由配置

最后，验证路由配置是否正确处理了基础路径。可以通过查看生成的路由配置来确认：

// 检查路由是否正确包含基础路径
console.log(useRoutes());

验证与测试

完成配置后，重新构建并部署项目：

npm run build
# 部署到二级目录

验证方法：

1. 访问二级目录下的应用，确认页面数据加载正常
2. 检查网络请求，确保所有 API 调用路径正确
3. 测试路由切换，验证 clientLoader 在不同路由间正常工作

总结与最佳实践

为避免二级目录部署问题，建议在项目初始化阶段就规划好部署路径，并在配置中明确设置 base 选项。同时，在编写 clientLoader 时，始终使用相对路径或通过 Umi.js 提供的 API 获取基础路径，确保代码的可移植性。

通过正确配置基础路径和调整 clientLoader 请求路径，我们可以确保 Umi.js 应用在各种部署环境下都能正常工作，为用户提供稳定可靠的体验。

更多关于 Umi.js 部署的最佳实践，可以参考官方文档 docs/ 和示例项目 examples/，其中包含了各种部署场景的配置示例。

【免费下载链接】umi A framework in react community ✨ 项目地址: https://gitcode.com/GitHub_Trending/um/umi