多环境下HTML引用CSS/JS等资源路径加载异常问题

核心原因 #

所有加载异常本质是不同运行环境的服务根目录、应用上下文路径配置不统一，没有对齐Java Web项目的标准运行逻辑：

• VS Code自带/第三方Live Preview类扩展，默认以当前打开的工作区最外层（仓库根目录）作为静态服务根，直接写/js/darkmode.js时，服务会去仓库根目录下找js文件夹，自然无法命中文件；只有写全从仓库根开始的完整路径src/main/webapp/js/darkmode.js才能找到对应资源。
  
• IntelliJ集成Tomcat运行Maven/Gradle Java Web项目时，默认将src/main/webapp目录映射为Web应用的静态资源根，根路径/直接对应webapp文件夹，因此写/js/darkmode.js即可正常加载资源。
• Heroku部署时的REST接口404问题，是因为本地Tomcat默认将应用部署在根路径/下，而Heroku环境如果没有显式配置，要么会将WAR包名作为上下文路径前缀，要么反向代理转发规则和本地不一致，硬编码的固定路径自然无法命中接口。

可落地修复方案 #

1. 对齐本地开发环境的服务根配置 #

不要直接用默认配置启动VS Code的Live Preview，修改扩展配置让服务根和Tomcat运行规则对齐：

• 打开VS Code设置，找到Live Preview扩展的Root配置项，填入值src/main/webapp，保存后重启预览服务，此时根路径/就直接对应webapp目录，和IntelliJ运行环境完全一致，直接写/js/xxx.js、/css/xxx.css即可正常加载，不需要再写从仓库根开始的长相对路径。
• 如果需要完全消除本地和部署环境的差异，直接在VS Code中安装Tomcat集成插件，将项目部署到本地独立Tomcat实例运行，和IntelliJ的运行逻辑完全一致，从根源避免路径适配问题。

2. 静态资源引用不要硬编码绝对路径 #

不管是JSP还是其他模板引擎编写页面，都不要直接硬写/js/xxx.js这类固定路径，用模板内置的上下文路径变量拼接资源地址，以JSP为例：

<!-- 自动适配任意上下文路径，无需随部署环境修改 -->
<script src="${pageContext.request.contextPath}/js/darkmode.js" type="text/javascript"></script>
<link rel="stylesheet" href="${pageContext.request.contextPath}/css/style.css">

这种写法会自动根据应用部署的上下文路径拼接前缀，不管应用部署在根目录还是子路径下，都能正确定位到资源，不需要针对不同环境改引用代码。

3. Heroku平台路径适配 #

• 显式配置Heroku上的Web应用上下文路径为根路径/：如果是Spring Boot项目，在配置文件中添加server.servlet.context-path=/；如果是原生Servlet项目部署，将部署到Heroku的WAR包命名为ROOT.war，Tomcat会自动将其映射到根路径，和本地Tomcat运行规则对齐。
• 前端发起REST请求时，同样拼接上下文路径前缀，不要硬编码固定绝对路径，和静态资源的处理逻辑保持一致，即可解决本地可访问、部署后404的问题。

内容的提问来源于stack exchange，提问作者Ryan Reddy