攻克Umi.js路由难题：3种方案完美获取basename

你是否在部署Umi.js应用到子路径时遭遇过路由404？配置了base却无法动态获取路径？本文将系统讲解3种获取basename的实战方案，配合官方示例代码与配置技巧，让你的应用在任何部署环境下都能准确定位路由基础路径。

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

在单页应用中，Basename用于指定应用部署的子路径。例如将应用部署在https://example.com/admin时，basename应设置为/admin，确保所有路由都基于此路径构建。Umi.js通过配置base属性实现这一功能，相关配置可参考Umi配置文档。

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

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

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

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

该配置会影响所有路由生成，包括Link组件和路由跳转API。典型应用可见ssr-basename示例项目，特别适合部署路径固定的场景。

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

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

通过Umi提供的运行时API可以在组件中获取当前basename，两种常用方式如下：

方法1：使用useModel hooks

// src/components/Navbar.tsx
import { useModel } from 'umi';

function Navbar() {
  const { base } = useModel('@@router');
  return (
    <div>当前基础路径: {base}</div>
  );
}

方法2：访问window全局变量

// 适合非React组件环境
const basename = window.g_app?._router?.history?.base || '';
console.log('当前basename:', basename);

这两种方法在with-react-query示例的导航组件中均有应用，推荐优先使用useModel hooks以获得更好的类型支持。

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

适用场景：开发/测试/生产环境需要不同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 || '/',
});

这种方案特别适合持续集成流程，可参考config-proxy示例中的环境配置方式，实现不同环境的无缝切换。

三种方案对比分析

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

部署注意事项

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

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

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

UMI_BASE=/test umi dev

3. 生产构建前务必检查base配置，避免打包后无法修改。相关构建流程可参考package.json中的scripts配置。

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