ReactJS配置package.json homepage部署Tomcat后路由失效、图片丢失
部署路径错位导致的路由与资源加载异常 解决方案
两个异常的本质都是实际部署的应用上下文路径,与构建产物生成、代码内硬编码的资源/路由基准路径不匹配,对应两个问题的修复步骤可以直接按以下操作执行:
一、路由失效的排查与修复
- 首先核对
package.json内的homepage配置值,必须和Tomcat实际部署的应用上下文路径完全一致。比如你将构建产物放在webapps/demo-app目录下,homepage必须配置为"./demo-app",不能直接写根路径"/"或无关联的线上全路径。 - 同步检查
react-router的basename配置:- 使用
react-router-dom v6版本时,basename需要与实际部署的上下文路径严格对齐,比如部署在/demo-app路径下,basename就配置为"/demo-app",斜杠数量、路径段完全一致,不能出现和homepage不匹配的割裂配置。 - 偷懒不易错的写法:直接将
basename的值设为process.env.PUBLIC_URL,构建时会自动替换为和homepage一致的路径值,避免手动拼写出现字符、斜杠数量的低级错误。
- 使用
- 必须补全SPA应用的Tomcat路由重定向规则,否则直接刷新非根路由的页面时,Tomcat会直接返回404,表现出路由失效的假象。具体操作是在你存放build产物的应用根目录下,新建
WEB-INF/web.xml文件,配置404错误指向入口文件:核心配置参考
<error-page> <error-code>404</error-code> <location>/index.html</location> </error-page>
二、图片加载失败的排查与修复
这个问题的触发逻辑和你的判断完全一致:之前没有配置homepage时,默认基准路径是应用根路径/,你写src='/images/图片名称.png'的请求路径和实际资源位置是匹配的;但在配置了非根路径的homepage之后,构建工具不会自动给这类硬编码的绝对路径拼接homepage对应的前缀,实际运行时浏览器会请求Tomcat根目录下的/images/xxx.png,而不是你应用上下文路径下的对应资源,自然会出现加载失败。
对应修复方式二选一即可:
- 最简便的改法:将所有引用public目录图片的硬编码绝对路径,去掉开头的斜杠,改成相对路径写法,即把
src="/images/图片名称.png"改成src="images/图片名称.png"。这种写法在构建时会自动匹配配置的基准publicPath,不会出现路径错位。 - 兼容性更强的改法:用React内置的环境变量拼接资源路径,写成
src={${process.env.PUBLIC_URL}/images/图片名称.png}。这种写法不管应用后续部署到哪个上下文路径下,构建时都会自动把process.env.PUBLIC_URL替换为package.json里配置的homepage对应路径,不会出现路径偏移。 - 避坑提醒:在配置了非根路径的homepage场景下,不要继续用开头带斜杠的绝对路径引用public目录下的静态资源,构建工具不会处理这类硬编码路径,必然触发404资源加载失败。
三、部署后的快速校验方法
部署完成后直接打开浏览器开发者工具的网络面板,刷新页面即可快速定位残留问题:
- 如果图片请求的URL缺少应用上下文的前缀,说明图片路径引用的写法没有调整到位,回到上一节的图片修复步骤调整即可。
- 如果路由跳转的URL没有带上配置的basename前缀,回去核对homepage和basename的路径是否完全一致。
- 如果刷新非根路由页面时直接显示Tomcat的原生404页面,检查web.xml的404重定向规则是否配置正确。
内容的提问来源于stack exchange,提问作者Dheeraj
相关产品推荐
相关产品推荐

