尧图网站建设 
Umi 4 base 配置3 类路径 404 症状的快速修复与终极排查指南【免费下载链接】umiA framework in react community ✨项目地址: https://gitcode.com/GitHub_Trending/um/umi在 UmiReact 前端框架项目里把base从/改成/admin之后一个高频现场是首页能打开点击页内链接跳到/dashboard直接 404刷新某个子页面又提示 chunk 加载失败。这三个症状通常不是三个问题而是base、publicPath和服务端 HTML 三处没对齐导致的连锁反应。先把配置改对最小可用写法先照这段改跑通后再往下看。以部署在/admin子目录为例// .umirc.ts export default { base: /admin, // 路由前缀改完必须重新构建才生效 publicPath: /admin/, // 静态资源前缀与 base 保持同一子目录 routes: [ { path: /index, component: index }, { path: /dashboard, component: dashboard }, ], };publicPath末尾的/不能省否则 chunk 文件名会和前缀粘在一起。仓库里有一个现成的对照写法注释直接点明了部署要求// 仓库内真实示例 base: /base/, publicPath: /base/, // 布署时需要布署在 base 文件夹下见 examples/ssg-basename/.umirc.ts。原理三分钟一个值三处消费base只声明一次但会被三处消费客户端路由匹配决定Link/history生成的地址、webpack 的publicPath决定 chunk 和静态资源的 URL 前缀、以及 SSR/SSG 时服务端渲染 HTML 时StaticRouter拿到的basename。三者不一致时症状就分别落在跳转 404资源 404服务端 HTML 链接错上。最短对照// 错误写法只改 base资源前缀仍是默认 / { base: /admin } // 正确写法路由与资源前缀同步 { base: /admin, publicPath: /admin/ }base的语义和限制见 docs/docs/docs/api/config.md 的base与publicPath小节。分步落地四个症状逐个修症状一页内点击跳转丢前缀症状地址栏里Link生成的链接是/dashboard不带/admin。根因手写a href/dashboard或window.location.href绕开了路由层router 没有机会拼接 basename。改法import { Link, useNavigate } from umi; // 统一走路由前缀由框架自动拼 Link to/dashboard看板/Link验证点右键复制链接地址应包含/admin前缀。官方 SSR 示例的页面就是这样写的examples/ssr-basename/src/pages/index.tsx前缀拼接发生在 packages/renderer-react/src/browser.tsxbasename opts.basename || /。症状二子路由刷新白屏、chunk 404症状首页正常F5 刷新/admin/dashboard后白屏Network 里 JS 请求 404。根因publicPath还是默认/构建产物里的 chunk URL 是/dashboard.chunk.js服务器在/admin/dashboard/下根本没有这个文件。改法按上一节最小可用写法同步publicPath并确认部署目录与之一致。验证点DevTools 里检查script src是否以/admin/开头。这个 fixture 就是为验证 publicPath 行为准备的packages/bundler-webpack/src/fixtures/runtime-public-path/bg.jpg。症状三SSR/SSG 吐出的 HTML 里链接全错症状curl服务端返回的 HTML里面所有a标签都是无前缀的绝对路径点过去全 404。根因服务端渲染时传给StaticRouter的location未包含 basename框架源码里有明确注释说明这一点。改法不要自己拼 URL交给base配置构建一次即可SSR 场景参考 examples/ssr-basename/.umirc.ts其中ssr: {}与base: /base/同时开启。验证点curl -s url后 grepa确认 href 带前缀。相关实现见 packages/renderer-react/src/server.tsx。症状四改了 base 却不生效症状换了环境的 base 值行为完全没变。根因base在构建时被内联进客户端 bundle运行时改配置无效这是官方文档的明确警告。改法每个部署环境单独umi buildbase 通过环境变量注入而非运行时判断。验证点在dist产物里搜旧的 base 字符串应已消失。该警告原文在 docs/docs/docs/api/config.md 的base一节。排错速查现象原因处置深链刷新 404首页正常publicPath 未随 base 调整两者指向同一子目录并重新构建SSR 页面 href 无前缀服务端 location 未带 basename启用 base 配置重建勿手工拼 URL切换环境后 base 无变化base 已内联进 bundle分环境单独umi buildMPA 自定义 APP_ROOT 路径错模板与静态资源根未对齐对照 examples/mpa-with-app-root-and-alias/静态导出部署后全 404产物没放到 base 子目录下部署目录与 base 值保持一致防复发建议把base与publicPath写成派生关系const appBase /admin; export default { base: appBase, publicPath:${appBase}/}杜绝两处手填不一致。代码评审时盯两条新增跳转必须用Link/useNavigateCSS/HTML 里不得出现硬编码的绝对路径前缀。每个部署环境走独立构建流水线不在运行时判断 base上线前用curl抽查一次服务端 HTML 的 href 前缀。回归验证直接跑仓库内的基准示例examples/ssr-basename/SSR base与 examples/ssg-basename/SSG base publicPath两者覆盖了本文全部四类症状的官方写法。【免费下载链接】umiA framework in react community ✨项目地址: https://gitcode.com/GitHub_Trending/um/umi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Umi 4 base 配置：3 类路径 404 症状的快速修复与终极排查指南
Umi 4 base 配置3 类路径 404 症状的快速修复与终极排查指南【免费下载链接】umiA framework in react community ✨项目地址: https://gitcode.com/GitHub_Trending/um/umi在 UmiReact 前端框架项目里把base从/改成/admin之后一个高频现场是首页能打开点击页内链接跳到/dashboard直接 404刷新某个子页面又提示 chunk 加载失败。这三个症状通常不是三个问题而是base、publicPath和服务端 HTML 三处没对齐导致的连锁反应。先把配置改对最小可用写法先照这段改跑通后再往下看。以部署在/admin子目录为例// .umirc.ts export default { base: /admin, // 路由前缀改完必须重新构建才生效 publicPath: /admin/, // 静态资源前缀与 base 保持同一子目录 routes: [ { path: /index, component: index }, { path: /dashboard, component: dashboard }, ], };publicPath末尾的/不能省否则 chunk 文件名会和前缀粘在一起。仓库里有一个现成的对照写法注释直接点明了部署要求// 仓库内真实示例 base: /base/, publicPath: /base/, // 布署时需要布署在 base 文件夹下见 examples/ssg-basename/.umirc.ts。原理三分钟一个值三处消费base只声明一次但会被三处消费客户端路由匹配决定Link/history生成的地址、webpack 的publicPath决定 chunk 和静态资源的 URL 前缀、以及 SSR/SSG 时服务端渲染 HTML 时StaticRouter拿到的basename。三者不一致时症状就分别落在跳转 404资源 404服务端 HTML 链接错上。最短对照// 错误写法只改 base资源前缀仍是默认 / { base: /admin } // 正确写法路由与资源前缀同步 { base: /admin, publicPath: /admin/ }base的语义和限制见 docs/docs/docs/api/config.md 的base与publicPath小节。分步落地四个症状逐个修症状一页内点击跳转丢前缀症状地址栏里Link生成的链接是/dashboard不带/admin。根因手写a href/dashboard或window.location.href绕开了路由层router 没有机会拼接 basename。改法import { Link, useNavigate } from umi; // 统一走路由前缀由框架自动拼 Link to/dashboard看板/Link验证点右键复制链接地址应包含/admin前缀。官方 SSR 示例的页面就是这样写的examples/ssr-basename/src/pages/index.tsx前缀拼接发生在 packages/renderer-react/src/browser.tsxbasename opts.basename || /。症状二子路由刷新白屏、chunk 404症状首页正常F5 刷新/admin/dashboard后白屏Network 里 JS 请求 404。根因publicPath还是默认/构建产物里的 chunk URL 是/dashboard.chunk.js服务器在/admin/dashboard/下根本没有这个文件。改法按上一节最小可用写法同步publicPath并确认部署目录与之一致。验证点DevTools 里检查script src是否以/admin/开头。这个 fixture 就是为验证 publicPath 行为准备的packages/bundler-webpack/src/fixtures/runtime-public-path/bg.jpg。症状三SSR/SSG 吐出的 HTML 里链接全错症状curl服务端返回的 HTML里面所有a标签都是无前缀的绝对路径点过去全 404。根因服务端渲染时传给StaticRouter的location未包含 basename框架源码里有明确注释说明这一点。改法不要自己拼 URL交给base配置构建一次即可SSR 场景参考 examples/ssr-basename/.umirc.ts其中ssr: {}与base: /base/同时开启。验证点curl -s url后 grepa确认 href 带前缀。相关实现见 packages/renderer-react/src/server.tsx。症状四改了 base 却不生效症状换了环境的 base 值行为完全没变。根因base在构建时被内联进客户端 bundle运行时改配置无效这是官方文档的明确警告。改法每个部署环境单独umi buildbase 通过环境变量注入而非运行时判断。验证点在dist产物里搜旧的 base 字符串应已消失。该警告原文在 docs/docs/docs/api/config.md 的base一节。排错速查现象原因处置深链刷新 404首页正常publicPath 未随 base 调整两者指向同一子目录并重新构建SSR 页面 href 无前缀服务端 location 未带 basename启用 base 配置重建勿手工拼 URL切换环境后 base 无变化base 已内联进 bundle分环境单独umi buildMPA 自定义 APP_ROOT 路径错模板与静态资源根未对齐对照 examples/mpa-with-app-root-and-alias/静态导出部署后全 404产物没放到 base 子目录下部署目录与 base 值保持一致防复发建议把base与publicPath写成派生关系const appBase /admin; export default { base: appBase, publicPath:${appBase}/}杜绝两处手填不一致。代码评审时盯两条新增跳转必须用Link/useNavigateCSS/HTML 里不得出现硬编码的绝对路径前缀。每个部署环境走独立构建流水线不在运行时判断 base上线前用curl抽查一次服务端 HTML 的 href 前缀。回归验证直接跑仓库内的基准示例examples/ssr-basename/SSR base与 examples/ssg-basename/SSG base publicPath两者覆盖了本文全部四类症状的官方写法。【免费下载链接】umiA framework in react community ✨项目地址: https://gitcode.com/GitHub_Trending/um/umi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考