Umi.js 4.x base 配置排坑：3 处路径 404 一次修完

Umi.js 4.x base 配置排坑3 处路径 404 一次修完【免费下载链接】umiA framework in react community ✨项目地址: https://gitcode.com/GitHub_Trending/um/umi第一次把 Umi.js 项目部署到域名的子路径下config.ts 里加了一行base配置页面是能打开——但点一下跳转路径 404 立刻找上门来。走我给你捋一下这事。它其实就出在三个地方路由、静态资源、API 请求一层一层修二十分钟能搞定。先做自检3 个现象说明你踩了 base 的坑修之前先对号入座。如果下面三条你中了哪怕两条基本就是同一个坑地址栏和部署路径对不上应用明明部署在/admin下点完跳转地址栏却变成了/dashboard再一刷新直接 404。静态资源一片红页面主体还能渲染打开 DevTools 一看JS、CSS、图片的请求全是从根路径/发出的整排 404。接口地址少了前缀Network 面板里接口请求的路径没带子路径前缀网关不认识直接打回 404。中了就说明问题不在业务代码而在配置和使用方式。⚠️ 先别急着往业务里找往下看。一个类比讲清 base 和 publicPath 的分工把项目想象成一栋公寓。base是房间号你部署在/admin那房间号就是/admin所有人页面路由进出都得先报这个号。publicPath是这间房的快递柜构建出来的 JS、CSS、图片全从publicPath指向的位置发货。房间号和快递柜是两回事但必须指向同一间房。最常见的事故就是你给 base 改了号快递柜还停在旧房间人进得来包裹全丢了。所以这两个值要同步改// config.ts export default { base: /admin, // 路由前缀地址栏里的路径要带它 publicPath: /admin/, // 资源前缀JS/CSS 的 URL 要带它 routes: [ { path: /, component: ./index }, { path: /dashboard, component: ./dashboard }, // 路由表不用写 base ], };注意两个细节routes里的路径不要手动拼 base框架会自己处理另外 Umi 的配置校验会强制publicPath必须以/结尾或写auto漏掉斜杠会直接被拦下。逐层修复路由层、资源层、API 层路由层手写 href 换成 Link前缀自动带上这是最典型的一处。原生a href/dashboard是裸奔跳转——浏览器直接请求/dashboard可你的服务端只认/admin/dashboard于是 404。// ❌ 手写 href浏览器直接请求 /dashboard服务端没有这个路径 a href/dashboard仪表盘/a // ✅ Link 会自动拼上 base 前缀实际跳到 /admin/dashboard import { Link } from umi; Link to/dashboard仪表盘/LinkUmi 官方的 basename 示例页就是这么写的to/about不带任何前缀但浏览器地址栏里出现的是带 base 前缀的完整路径可以翻 examples/ssr-basename/src/pages/index.tsx 对照看——这个示例专门验证 SSR 场景下a标签必须带正确 base 前缀是最直观的参考。那 Link 凭什么能自动拼前缀Umi 的 Link 是对 react-router Link 的封装额外挂了路由预取能力而 react-router 在生成真实 href 时会把路由器的 basename 统一前置。想看这套封装长什么样packages/renderer-react/src/link.tsx 里的LinkWithPrefetch就是全部实现值得花两分钟过一遍。如果不用 Link编程式跳转也一样省事history API 走的是同一套机制import { history } from umi; const goToDashboard () { history.push(/dashboard); // 框架自动处理前缀写裸路径即可 };静态资源层绝对路径是子路径部署的头号敌人路由修完再看资源。资源 URL 是从publicPath拼出来的所以任何硬编码的根路径都会绕过 publicPath直接打到服务器根目录。// ❌ 写死根路径浏览器去请求 /logo.png文件实际在 /admin/logo.png img src/logo.png altlogo / // ✅ 交给构建工具处理资源地址会自动带上 publicPath 前缀 import logo from /assets/logo.png; img src{logo} altlogo /原则一句话src 目录里的资源一律importpublic 目录里的公共资源也尽量走相对路径或构建注入别手打/xxx。样式文件里同理less/scss 中的 url 绝对路径不会被构建工具改写会原样发到根路径去/* ❌ 绝对路径不经过构建处理照样请求根目录 */ .bg { background: url(/images/bg.png); } /* ✅ 相对路径按 less 文件所在位置解析最终自动带上 publicPath */ .bg { background: url(./images/bg.png); }API 请求层给请求加上和 base 一样的前缀最后一层。如果你的后端网关也挂在/admin子路径下裸路径的请求自然全部落空。正确做法是建请求实例时把前缀补上import { request } from umi; // ❌ 没配前缀请求直接打到 /user/list子路径网关找不到 request(/user/list); // ✅ 后端同样部署在 /admin 下baseURL 补上 base const apiRequest request.extend({ baseURL: /admin, // 与 base 保持一致 prefix: /api, // 接口统一前缀 }); apiRequest(/user/list); // 最终请求 /admin/api/user/list⚠️ 注意baseURL的值要跟base对齐别一个/admin一个/admin-panel那种错位是最难查的。上线前 30 秒检查base和publicPath指向同一个子路径且 publicPath 以/结尾全局搜一遍a href/确认路由跳转都换成了 Link 或 history API搜代码和样式里的url(/、src/确认没有漏网的硬编码根路径接口实例的baseURL与base一致后端挂在子路径下时Network 面板里逐个看一遍页面、JS、CSS、接口URL 前缀应该完全一致现在打开你项目的 config.ts把base和publicPath对齐成同一个子路径然后umi dev跑起来手动访问/admin下的路由点两下跳转——DevTools 的 Network 面板里所有资源请求的 URL 前缀应该和地址栏一模一样。到这一步这个坑就算填完了。【免费下载链接】umiA framework in react community ✨项目地址: https://gitcode.com/GitHub_Trending/um/umi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考