Umi.js路由基础路径终极指南：3种方案完美解决部署难题

Umi.js路由基础路径终极指南：3种方案完美解决部署难题

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

在单页应用开发中，路由基础路径（Basename）是确保应用在子路径下正常运行的关键配置。当你的Umi.js应用需要部署在https://example.com/admin这样的子路径时，basename必须设置为/admin，否则所有路由都会404。本文将系统讲解3种获取basename的实战方案，让你的应用在任何部署环境下都能准确定位路由基础路径。

什么是Basename（路由基础路径）？

Basename定义了应用部署的根路径位置。在Umi.js框架中，通过配置base属性来设置路由基础路径，这会影响所有路由生成、Link组件和路由跳转API的行为。

静态配置法：基础设置方案

适用场景：固定部署路径的生产环境

在项目配置文件config.ts中直接设置base属性，这是Umi.js推荐的基础用法：

// config.ts export default defineConfig({ base: '/admin', // 设置路由基础路径 routes: [ { path: '/', component: '@/pages/index' } ] });

该配置会直接影响构建输出，确保所有路由都基于/admin路径。这种方案在ssr-basename示例项目中得到了充分应用，特别适合部署路径固定的场景。

API动态获取：代码级解决方案

适用场景：需要在组件中动态使用basename的场景

通过Umi提供的运行时API可以在组件中获取当前basename，实现更灵活的路径处理：

方法1：使用useModel hooks

// src/components/Navigation.tsx import { useModel } from 'umi'; function Navigation() { const { base } = useModel('@@router'); return ( <div> 当前应用部署在: {base} <Link to="/dashboard">跳转到仪表板</Link> </div> ); }

方法2：访问路由实例

// 在组件中获取basename const basename = window.g_app?._router?.history?.base || '';

在qiankun-slave示例的basename页面中，展示了如何在微前端场景下正确处理basename。

环境变量注入：多环境适配方案

适用场景：开发/测试/生产环境需要不同basename的场景

通过环境变量动态注入basename，配合.env文件实现多环境配置：

1. 创建环境配置文件：

// .env.production REACT_APP_BASE=/admin // .env.development REACT_APP_BASE=/dev

2. 在配置文件中引用环境变量：

// config.ts export default defineConfig({ base: process.env.REACT_APP_BASE || '/', });

三种方案对比分析

方案	优点	缺点	适用场景
静态配置法	简单直接，Umi原生支持	无法动态修改	固定部署路径
API动态获取	组件内灵活使用	需运行时支持	动态展示路径
环境变量注入	多环境适配	配置较复杂	多环境部署

部署注意事项

1. 服务器配置支持basename路由，如Nginx需配置：

location /admin { try_files $uri $uri/ /admin/index.html; }

2. 开发环境测试时，可通过UMI_BASE环境变量临时修改：

UMI_BASE=/test umi dev

3. 生产构建前务必检查base配置，避免打包后无法修改。

通过本文介绍的三种方案，可以覆盖从简单到复杂的各类basename使用场景。建议优先采用"静态配置+API获取"的组合方案，既保证基础配置的稳定性，又满足组件内动态使用的需求。更多实战技巧可参考Umi官方示例库中的相关项目。

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