Spring Boot中HTML静态资源链接失效问题咨询与修复

1. 为何初始无需额外配置即可正常加载样式与脚本？ #

• 你在MvcConfig中已经配置了/styles/css/**到classpath:/static/css/的映射，刚好匹配页面里样式文件的请求路径/styles/css/host_page.css，所以样式能被正确解析。
• 本地运行时，要么是因为页面/host_page处于permitAll白名单，浏览器发起的资源请求会话未被JWT过滤器拦截；要么是Spring Boot的默认静态资源规则（即便加了@EnableWebMvc，部分根路径资源仍能从static/目录读取）帮你兜底了其他资源的加载。

2. 提交至GitHub后资源链接失效的原因 #

• 环境上下文路径差异：本地开发时Spring Boot默认上下文路径为/，但部署到GitHub相关环境（如Codespaces、GitHub Actions部署的服务器）时，可能自动添加了项目名作为上下文路径，导致页面中写的绝对路径/styles/css/...无法匹配后端映射。
• 安全拦截触发：本地运行时可能因过滤器顺序、会话状态的隐性差异，静态资源请求未被JWT过滤器拦截；但部署后安全规则严格执行，原WebSecurityConfig未明确放行/styles/**、/images/**等路径，导致资源请求被拦截返回401/403。
• 资源映射不完整：原MvcConfig只配置了样式路径，其他资源（如背景图）依赖Spring Boot默认规则加载，部署后环境的默认配置被@EnableWebMvc完全覆盖，导致根路径资源（如/background.jpg）找不到。

3. 修复方案 #

步骤1：完善静态资源映射 #

在MvcConfig中补全所有静态资源的路径映射，确保前端请求路径和后端资源目录一一对应：

@Configuration
@EnableWebMvc
public class MvcConfig implements WebMvcConfigurer {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 样式文件映射
        registry
                .addResourceHandler("/styles/css/**")
                .addResourceLocations("classpath:/static/css/");
        // 图片资源映射
        registry
                .addResourceHandler("/images/**")
                .addResourceLocations("classpath:/static/images/");
        // 脚本文件映射
        registry
                .addResourceHandler("/js/**")
                .addResourceLocations("classpath:/static/js/");
        // 单独映射根路径的背景图（如果需要）
        registry
                .addResourceHandler("/background.jpg")
                .addResourceLocations("classpath:/static/images/");
    }
}

步骤2：彻底放行静态资源 #

在WebSecurityConfig中添加WebSecurityCustomizer，直接忽略静态资源的安全拦截，避免JWT过滤器干扰：

@Configuration
@RequiredArgsConstructor
@EnableWebSecurity
@Slf4j
public class WebSecurityConfig {
    private final JWTTokenConfig jwtTokenConfig;

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        // 原有安全配置不变
        http.csrf().disable()
                .cors().disable()
                .authorizeRequests(authorize -> authorize
                        .antMatchers("/register","/host_page", "/login", "/music_files").permitAll()
                        .antMatchers("/swagger-ui/**", "/swagger-resources/*", "/v3/api-docs/**", "/swagger-ui.html").permitAll()
                        .antMatchers("/personal_office/**").authenticated()
                        .antMatchers(HttpMethod.GET, "/main").permitAll()
                        .antMatchers("/free_subscription").hasAnyRole("FREE", "OPTIMAL", "MAXIMUM", "ADMIN")
                        .antMatchers("/optimal_subscription").hasAnyRole("MAXIMUM", "OPTIMAL", "ADMIN")
                        .antMatchers("/maximum_subscription").hasAnyRole("MAXIMUM", "ADMIN")
                        .antMatchers("/admin_office/**").hasRole("ADMIN")
                        .anyRequest().authenticated()
                )
                .sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS)
                .and()
                .addFilterBefore((Filter) jwtTokenConfig, UsernamePasswordAuthenticationFilter.class);
        return http.build();
    }

    // 新增：忽略静态资源的安全检查
    @Bean
    public WebSecurityCustomizer webSecurityCustomizer() {
        return (web) -> web.ignoring().antMatchers("/styles/**", "/images/**", "/js/**", "/background.jpg");
    }
}

步骤3：统一前端资源路径 #

确保前端页面中的资源路径和后端映射一致，比如背景图使用/images/background.jpg：

body {
  background-image: url("/images/background.jpg");
  background-size: cover;
  background-position: center -100px;
  background-repeat: no-repeat;
  background-attachment: fixed;
}

步骤4：处理上下文路径（可选） #

如果部署环境有自定义上下文路径，在application.properties中配置：

server.servlet.context-path=/your-project-name

如果使用模板引擎（如Thymeleaf），建议用动态路径生成资源链接，避免绝对路径问题：

<link rel="stylesheet" th:href="@{/styles/css/host_page.css}" type="text/css" />

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