SpringBoot 静态资源访问（图片/JS/CSS）配置详解

在 SpringBoot 项目开发中静态资源访问是前端页面、图片上传、富文本、后台管理系统必备的功能。很多同学经常遇到图片上传成功但访问 404、JS/CSS 加载失败、自定义目录不生效、线上环境无法访问等问题。今天就来讲讲 SpringBoot 静态资源的默认规则、自定义配置、本地映射、外部路径、权限放行、打包部署。一、什么是静态资源• 图片jpg、png、gif、webp• 样式css、less、scss• 脚本js、ts• 静态页面html、ico、font• 上传文件Excel、PDF、视频SpringBoot 对这些资源提供自动映射也支持高度自定义。二、SpringBoot 默认静态资源规则自动生效默认 5 个静态资源路径优先级从高到低1.META-INF/resources2.resources/3.static/最常用4.public/5.webapp/默认访问规则直接访问资源名即可不需要加目录前缀。示例src/main/resources/static/images/logo.png访问地址http://localhost:8080/images/logo.png三、最常用场景自定义静态资源映射实际项目中我们会把用户上传的图片/文件存放在服务器外部路径避免项目重新打包文件丢失。这时候必须用SpringMVC 资源映射1. 编写配置类package com.demo.config; import org.springframework.context.annotation.Configuration; import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry; import org.springframework.web.servlet.config.annotation.WebMvcConfigurer; /** * 静态资源配置 */ Configuration public class WebMvcConfig implements WebMvcConfigurer { /** * 静态资源映射 * 访问路径 /uploads/xxx.jpg → 映射到本地 D:/uploads/xxx.jpg */ Override public void addResourceHandlers(ResourceHandlerRegistry registry) { // 1. 访问 URL 规则 registry.addResourceHandler(/uploads/**) // 2. 本地真实路径末尾必须加 / .addResourceLocations(file:D:/uploads/); // 2. 也可以配置相对路径 registry.addResourceHandler(/static/**) .addResourceLocations(classpath:/static/); } }2. 访问示例本地文件D:/uploads/avatar.jpg访问地址http://localhost:8080/uploads/avatar.jpg四、application.yml 配置静态资源如果你不想写配置类可以直接在 yml 中配置spring: web: resources: # 自定义静态资源路径 static-locations: classpath:/static/,classpath:/public/,file:./uploads/⚠️ 注意配置后会覆盖默认路径不是追加所以要把需要的路径都写上。五、静态资源放行解决 Shiro/Security 拦截 404如果项目集成了Shiro/Spring Security静态资源会被登录拦截必须手动放行1. Shiro 放行配置filterMap.put(/static/**, anon); filterMap.put(/uploads/**, anon); filterMap.put(/**.js, anon); filterMap.put(/**.css, anon); filterMap.put(/**.png, anon); filterMap.put(/**.jpg, anon); filterMap.put(/**.ico, anon);2. Security 放行配置http.authorizeRequests() .antMatchers(/static/**,/uploads/**,/**.js,/**.css).permitAll() .anyRequest().authenticated();六、自定义 favicon.ico网站图标只需要把favicon.ico放到resources/static/favicon.icoSpringBoot 自动加载无需任何配置。七、SpringBoot 静态资源缓存生产优化registry.addResourceHandler(/static/**) .addResourceLocations(classpath:/static/) // 浏览器缓存 10 天 .setCachePeriod(864000);八、图片上传 回显完整实战1. 上传接口PostMapping(/upload) public Result upload(MultipartFile file) throws IOException { // 上传目录 String path D:/uploads/; File dir new File(path); if (!dir.exists()) dir.mkdirs(); // 文件名 String fileName UUID.randomUUID() file.getOriginalFilename().substring(file.getOriginalFilename().lastIndexOf(.)); file.transferTo(new File(path fileName)); // 返回可访问的 URL String url http://localhost:8080/uploads/ fileName; return Result.success(url); }2. 配置映射registry.addResourceHandler(/uploads/**) .addResourceLocations(file:D:/uploads/);九、Linux 服务器部署路径写法registry.addResourceHandler(/uploads/**) .addResourceLocations(file:/usr/local/uploads/);十、静态资源 404 常见原因1.路径末尾缺少 /错误/uploads正确/uploads/**2.本地路径末尾缺少 /错误file:D:/uploads正确file:D:/uploads/3.被拦截器/权限框架拦截需要放行静态资源4.Windows 与 Linux 路径格式不一致WindowsD:/uploads/Linux/usr/local/uploads/5.目录权限不足Linux 需要给目录读写权限十一、SpringBoot 静态资源核心总结1. 默认路径static文件夹直接访问2. 外部文件用addResourceHandler映射3. 图片上传必须用外部路径避免打包丢失4. 权限拦截一定要放行静态资源5. 路径格式末尾必须加/6. 生产环境配置缓存提升性能掌握这些所有静态资源问题全部解决结尾互动大家在开发中有没有遇到过静态资源 404、图片无法访问的问题都是怎么解决的欢迎评论区留言交流