把工程名从myapp-old改成myapp-new本来只是想让代码仓库看起来更规范一点。结果在 IDEA 里点完 Rename Project再重新启动浏览器打开页面直接白屏。控制台没报错后端日志正常前端接口也通就是页面空白。这种“修改项目名后浏览器中前端部分无法展示”的问题我在实际项目里踩过不止一次。尤其在 IDEA 里改项目名影响的远不止目录名开发工具本身会留下一堆旧名字的配置Artifact 名称、Run Configuration、Application context、前端打包的 publicPath、路由 base任何一个没跟着改前端就会“幽灵式”失效。它不是报错不是崩溃而是页面加载不出来或者加载了但样式和 JS 全部 404。这篇文章就把我排查这类问题的思路和步骤完整写出来。无论你是用 Spring Boot Vue、外部 Tomcat 传统 Web、还是纯静态前端工程只要遇到改完名后前端无法展示按这套流程走一遍基本能定位。我也会把常见坑和实际处理方案整理成表格方便你直接对照着改。1. 先搞清楚“改项目名”到底动了哪些东西1.1 从一次典型翻车现场说起先说一个我经历过的典型场景。某次我维护一个单体项目后端是 Spring Boot前端是 Vue 3前端构建产物直接输出到后端src/main/resources/static目录里最终打成一个 jar 跑。项目原本叫demo-admin因为交付文档里的名称规范要求我把整个 IDEA 工程名改成了demo-manage。我当时以为改名就是右键 Refactor - Rename选上 Rename project、Rename module等 IDEA 重新索引完就完事了。结果启动后浏览器访问原来的http://localhost:8080/demo-admin/直接显示 404。我换到http://localhost:8080/demo-manage/页面能打开但 CSS 全没了JS 也报Uncaught SyntaxError。再仔细看 NetworkHTML 文档返回 200但里面引用的/demo-admin/css/app.css、/demo-admin/js/chunk-vendors.js全部 404。问题根因非常明显IDEA 只改了工程名但前端打包配置里写死了旧的绝对路径。项目名一变静态资源的公共前缀没有变浏览器仍然请求旧路径后端当然找不到。这个案例说明改项目名不是一个“重命名文件夹”的动作。它会沿着工程配置链条往下传递项目名 - Artifact 名 - 部署上下文路径 - 前端资源基础路径 - 路由 base。任何一环没同步前端展示就会出问题。1.2 改项目名会波及的 5 个配置点我把这轮排查总结下来真正会被“改名”影响的配置点主要有 5 个配置点典型位置影响表现Artifact 名称与输出目录IDEA File - Project Structure - Artifacts运行配置找不到旧 Artifact启动报错或启动的是旧构建产物Run Configuration 的 Application contextIDEA Run/Debug Configuration - Deployment访问 URL 还是旧的新地址打不开后端服务的 context-pathapplication.yml/server.xml/ Tomcat 配置前后端路径前缀不一致静态资源 404前端构建的 base/publicPathvite.config.js/vue.config.js/ webpack打包后资源路径仍带旧项目名浏览器请求旧路径前端路由 baseVue Router / React Router页面白屏刷新后 404路由无法匹配这里我特别想说一个很多人忽略的点IDEA 的 Rename Project 并不会帮你查清楚所有引用。它更多是帮你重命名工程目录、模块名、同步 IDE 项目结构但构建配置、部署描述符、前端配置这些“文本内容”里的字符串IDEA 很难智能判断哪些该改、哪些不该改。所以改名之后必须手动把上面这些点全部过一遍。2. 前端无法展示的核心原因排查清单2.1 访问地址没跟上新上下文路径最常见也最容易被发现的一类项目名改了之后部署在 Tomcat 上的上下文路径还是旧的。如果你用的是 IDEA 自带的外部 Tomcat 启动方式那么在 Run/Debug Configurations 里会有一个 Deployment 标签页。这里选中的是 Artifact同时下面有个 Application context 输入框。IDEA 新建 Tomcat 运行配置时Application context 默认会用 Artifact 名比如/demo-admin_war_exploded或者/demo-admin。当项目名改成demo-manage之后IDEA 可能会自动帮你创建新名字的 Artifact但旧运行配置仍然停留在旧名字的 Artifact 上。此时如果直接启动控制台大概率会报错Error running Tomcat 9.0.xx: Artifact demo-admin:war exploded not found这种情况下后端根本没起来前端自然无法展示。解决办法是去 Run - Edit Configurations找到对应的 Tomcat 配置Deployment 标签页里把 Artifact 换成新名字同时把 Application context 改成新上下文路径。还有一种情况是旧 Artifact 还在IDEA 不会报错但实际跑的是旧的构建产物。你改了前端代码、改了后端代码页面却始终是旧样子。这比直接报错更迷惑人。2.2 部署包名与运行配置不一致在 IDEA 里Project Structure 的 Artifacts 页面中Artifact 输出目录默认长这样out/artifacts/demo_admin_war_exploded旧项目名中的-通常会被转成_因为目录名不允许某些特殊字符。当你改名后生成新 Artifact输出目录可能变成out/artifacts/demo_manage_war_exploded此时两个 Artifact 并存。如果你记不清运行配置里究竟指向哪一个很容易出现“我明明改了代码为什么浏览器里还是老页面”的情况。我的检查方法是先在 Project Structure - Artifacts 里删掉旧的 Artifact只保留新名字的 Artifact然后到 Run Configuration 里重新引用一遍。这样能强制避免旧产物干扰。另外如果是 Maven 工程pom.xml里的artifactId不会因为 IDEA 工程名改动而自动更新。比如artifactIddemo-admin/artifactId这里如果不改成demo-manage最终打出来的 jar/war 文件名还是旧的。部署到服务器后浏览器访问的路径可能就要带旧名或者产生和代码不一致的情况。改项目名时pom.xml和build.gradle里的模块标识都需要同步改。2.3 静态资源相对路径失效除了部署层前端自身的资源路径也是重灾区。很多人在写 HTML 或前端模板时喜欢用绝对路径引用静态资源。比如link relstylesheet href/demo-admin/css/app.css script src/demo-admin/js/app.js/script这种写法在项目名不变时没有任何问题。但一旦你把部署上下文路径改成/demo-manage浏览器仍然按照旧路径去请求/demo-admin/css/app.css后端自然返回 404。如果后端配置过 SPA fallback比如把所有未知路径都导向index.html那 CSS/JS 请求还会拿到 HTML 文档浏览器解析时报错更诡异页面会彻底白屏。解决思路有两个方向。一种是所有静态资源引用改成相对路径但 SPA 模式下相对路径在深层路由里容易出问题不算最稳妥。另一种是保持绝对路径但把里面写死的项目名前缀去掉改成使用带 context path 的模板语法。例如 Spring Boot Thymeleaflink relstylesheet th:href{/css/app.css}这样 context path 改了之后模板会自动拼上新的上下文不会写死。2.4 前端路由历史模式的坑如果你用的是 Vue Router 的createWebHistory()或者 React Router 的BrowserRouter项目名改了之后还有一个隐形问题路由 base。比如原来部署在/demo-admin/下路由配置可能是const router createRouter({ history: createWebHistory(/demo-admin/), routes })改成/demo-manage/之后如果这里还写旧值浏览器访问/demo-manage/home时Vue Router 会认为当前路径是/home但实际生效的组件和路径是从/demo-admin/开始匹配的。结果就是首页默认路由匹配不上页面空白。这个坑之所以隐蔽是因为它不会请求后端资源也不报 404你在 Network 里能看到index.html正常返回只是页面内容为空。必须打开浏览器控制台看有没有路由警告或者直接改路由 base 才能发现。如果你的路由是createWebHashHistory()影响会小一些因为 hash 后面的路径不会发给服务器但 base 如果写死旧名同样可能造成资源加载异常。所以只要项目名变了前端路由配置里的 base 必须跟着变。2.5 构建产物路径与 publicPath 的连锁反应现代前端工程打包时base或publicPath是用来给所有静态资源加公共路径的。Vite 对应baseVue CLI 对应publicPathwebpack 直接配置output.publicPath。实际中我见过这样的 Vite 配置export default defineConfig({ base: /demo-admin/, build: { outDir: ../src/main/resources/static/admin } })项目名改成demo-manage后如果只改了构建输出目录忘了改base那么打包出来的index.html里仍然写的是script typemodule src/demo-admin/assets/index.js/script浏览器访问新路径/demo-manage/时拿到 HTML 却去请求/demo-admin/assets/index.js结果自然是 404。这种情况的典型特征是后端能启动、页面能打开 HTML但所有资源全部加载失败页面样式全丢交互完全失效。你可以理解为“房子门开了但门牌号写的是别人家的地址”浏览器自然找不到正确的资源。3. 我从实际排障中总结的修复步骤3.1 三步定位法先看日志再查端口最后验静态资源遇到前端无法展示不要先改代码先花几分钟定位问题到底出在哪一层。我惯用的流程是三个步骤第一步看后端日志和浏览器控制台。如果 IDE 启动日志里有Artifact not found、Deployment error多半是运行配置没指向新项目。如果后端日志正常但浏览器 Console 里有404、UNCAUGHT SyntaxError那问题更可能在静态资源路径或部署上下文。第二步直接验证后端是否起来、资源是否可访问。可以用命令快速探测curl -I http://localhost:8080/demo-manage/ curl -I http://localhost:8080/demo-manage/assets/index.js curl -I http://localhost:8080/demo-admin/assets/index.js如果第一条返回 200、第二条 200、第三条 404那说明你静态资源路径里的前缀还是旧项目名。如果第一条都 404说明 context path 配置不对后端没有把/demo-manage/映射到应用。第三步用浏览器 Network 面板精确定位。打开 F12 - Network刷新页面先看文档请求本身是 200 还是 404再看 CSS/JS 资源的请求 URL。很多时候问题一眼就能看出来HTML 里引用的资源地址前缀和当前访问地址前缀不一致。3.2 完整操作流程IDEA 常见前后端项目以我项目里最常见的 Spring Boot Vite 前端为例完整的修复流程大概是这样的。第一步确认 IDEA 里工程名、模块名已经改完。右键项目 - Refactor - Rename分别选择 Rename project 和 Rename module等 IDEA 完成索引重建。第二步修改 Maven 或 Gradle 的模块标识。在pom.xml中artifactIddemo-manage/artifactId如果之前版本号、包名也有项目名相关的内容一并检查。Java 的包名如果本身不包含旧项目名可以不改但模块 artifactId 必须和新项目名保持一致。第三步删除旧的 Artifact重新生成。进入 File - Project Structure - Artifacts把和旧项目名相关的 Artifact 删除再添加新项目名对应类型的 Artifact。这一步很多人会漏掉导致 IDEA 里残留一个“僵尸 Artifact”。第四步重新配置 Run/Debug Configuration。在 Deployment 标签页里选择新 Artifact并把 Application context 填成/demo-manage。同时检查 Server 标签页里的 URL把打开地址改成http://localhost:8080/demo-manage/第五步改后端 context-path。如果你用的是 Spring Boot 内嵌 Tomcat在application.yml里加一行server: servlet: context-path: /demo-manage如果用的是外部 Tomcat 部署 WarApplication context 就足够不需要在配置里写死但要注意 Server.xml 里不能有冲突的Context配置。第六步改前端构建配置。以 Vite 为例export default defineConfig({ base: /demo-manage/, build: { outDir: ../src/main/resources/static/demo-manage, emptyOutDir: true } })同时检查 Vue Routerconst router createRouter({ history: createWebHistory(/demo-manage/), routes })第七步重新构建。先mvn clean再 Rebuild Project然后再重新打包前端。注意顺序如果前端产物输出到后端src/main/resources/static一定要先重新构建前端再重新构建后端否则后端打包时间早于前端产物更新又会把旧的前端文件打进 jar。第八步清理缓存后启动。IDEA 里执行 Build - Rebuild Project如果用的外部 Tomcat删掉 Tomcat 的work目录和temp目录再重新启动。浏览器建议用无痕窗口打开或者强制刷新CtrlShiftR避免旧缓存干扰。3.3 不同场景的配置修改对照很多读者可能用了完全不同的部署方式我把常见场景整理成一个对照表方便你按自己的组合查缺补漏。部署场景必须修改的位置额外注意Spring Boot 内嵌容器 前端静态文件application.yml的 context-path、前端base/publicPath构建顺序先前端后后端外部 Tomcat War 包IDEA Run Configuration 的 Artifact 和 Application context清理 Tomcat work 目录后端渲染模板Thymeleaf/JSP Vue模板里的 th:href 或 c:url 路径避免在 HTML 中写死/旧名/纯前端部署到 Nginx 子目录Nginxlocation /demo-manage/、前端base还需改路由 base否则刷新 404前后端分离前端单独打包前端base/publicPath、打包后的index.html资源前缀后端接口 CORS 和跨域路径一般不受影响关键思路是所有配置里出现的“项目名”必须在同一组值上对齐。不要后端 context-path 用demo-manage前端 base 还是demo-admin那样肯定会有一环断掉。4. 常见问题与避坑经验实录4.1 浏览器空白但接口正常这种情况很典型Network 里接口都能调通后端数据也返回 200但页面就是空白连 HTML 渲染都没有。我遇到过真实案例原因出在 Vue Router 的 base。后端 context-path 已经改成/demo-manage接口请求也确实打到了/demo-manage/api/...但路由配置里还写着一个旧的/demo-admin/。页面加载后Router 去匹配/demo-manage/发现和自己的 base 不一致最终没有任何路由命中router-view什么都没渲染出来。处理方式是先打开控制台看有没有类似[Vue Router warn]: No match found for location with path /demo-manage/的提示。如果有基本就是 base 没改或者路由没有配置默认跳转。还有一种可能是index.html里的入口脚本加载失败但因为脚本是模块加载报错可能比较隐晦。可以用无痕窗口打开页面Network 里看模块请求是否 200。4.2 HTML能打开但CSS/JS 404遇到这种问题先别怀疑后端十有八九是静态资源前缀没同步。打开浏览器查看页面源码或者直接看 Network 里 CSS/JS 的资源 URL。如果请求地址写的是/demo-admin/xxx而你当前访问的新路径是/demo-manage/xxx那就说明有三个地方要去检查前端构建的base/publicPath、后端context-path、模板里写死的前缀。我在实际操作中最快的验证方法是手动在浏览器地址栏把资源 URL 里的旧项目名改成新项目名如果能正常加载基本就锁定问题了。尤其要注意 Vite 的base配置。它决定打包后index.html中所有/assets/...引用的基础路径。很多人改了outDir以为输出目录对了就行实际上base才是控制资源前缀的关键。4.3 改了项目名之后编译报错还有一种情况是改名后 IDE 编译直接报错前端还没到运行阶段就挂了。这类问题通常出在 Maven/Gradle 工程里模块名改了但pom.xml或settings.gradle里的模块声明依然指向旧名字。IDEA 重新加载项目时发现路径和模块名对不上就会产生大量编译错误。例如IDEA 的模块名和磁盘目录名不一致时Project Structure - Modules 里的 Sources 路径可能会变成红色。此时右键模块 - Open Module Settings把源码目录重新关联到新路径再执行 Maven 同步。如果是 Java 包名里包含了旧项目名还要考虑是否做全局替换。比如包名com.example.demo_admin改成com.example.demo_manage。这里要谨慎单独改项目名不应该大范围改包名否则会把 git 历史和已有引用搞得一团糟。除非是刚启动的新项目否则不建议包名跟着项目名一起动。4.4 关于清理缓存很多人只做了表面功夫修改项目名后浏览器页面一直不更新很多人会怀疑 IDEA 的缓存于是 File - Invalidate Caches - Restart重启完还是老样子。这其实是没抓到重点。IDEA 缓存失效更多影响的是代码提示、索引和工程结构显示。前端页面不更新主要原因是浏览器缓存了旧 JS/CSS 文件后端target/classes或out/artifacts下仍有旧构建产物外部 Tomcat 的work目录缓存了解析后的 JSP 或静态文件。我自己的清理习惯是先执行 Maven 的clean再删掉 IDEA 的out目录然后删外部 Tomcat 的work/Catalina目录最后用无痕窗口访问页面。这套下来基本没有“改了配置但不生效”的情况。如果用了 Spring Boot DevTools还要注意热重启可能没有完整更新前端资源。建议在改完项目名后先停掉 DevTools做一次干净的重启再继续开发。4.5 我的几点强迫症习惯经历了这么多次改名翻车我后来给自己定了一些规矩可以有效减少同类问题。第一改项目名前先列一份“命名影响清单”。把pom.xml的 artifactId、application.yml的 context-path、IDEA 的 Artifact 名、Run Configuration、前端vite.config.jsbase、Vue Router base、Nginx location 全部列出来统一改成同一个新名字。这份清单可能只有几行字但它能避免漏改任何一环。第二前端资源路径尽量别写死项目名。能用相对路径、能用模板语法、能用构建工具的 base 变量就不要手工硬编码。写死一时爽改名火葬场。尤其是团队多人协作时写死路径会让别人改起来非常痛苦。第三静态资源带 hash 的版本号一定要保留。比如app.8f3k2d.js这样改名后即使路径前缀变了只要文件名不变浏览器也会因为 URL 不同而立刻请求新资源不会受旧缓存干扰。第四所有改动完成后做一次“从零启动”验证。不要只试 IDEA 里的快捷启动还要试着直接mvn clean package打一个包放到干净环境里运行。因为 IDEA 的 Run Configuration 可能会掩盖很多部署差异而真实发布环境不会帮你自动适配旧路径。最后再分享一个小技巧如果改完项目名后前端始终有问题你可以在浏览器地址栏手动访问http://localhost:8080/demo-manage/index.html再访问http://localhost:8080/demo-manage/assets/app.js。直接用资源 URL 测试比刷新整个页面更容易看出是哪一层出了问题。这种“拆开请求逐层验证”的方法我每次排查都靠它也推荐你用起来。
