在 SpringBoot 項(xiàng)目開(kāi)發(fā)中，靜態(tài)資源訪問(wèn)是前端頁(yè)面、圖片上傳、富文本、后臺(tái)管理系統(tǒng)必備的功能。
很多同學(xué)經(jīng)常遇到：圖片上傳成功但訪問(wèn) 404、JS/CSS 加載失敗、自定義目錄不生效、線上環(huán)境無(wú)法訪問(wèn)等問(wèn)題。

今天就來(lái)講講 SpringBoot 靜態(tài)資源的默認(rèn)規(guī)則、自定義配置、本地映射、外部路徑、權(quán)限放行、打包部署。

一、什么是靜態(tài)資源？

• • 圖片：jpg、png、gif、webp
• • 樣式：css、less、scss
• • 腳本：js、ts
• • 靜態(tài)頁(yè)面：html、ico、font
• • 上傳文件：Excel、PDF、視頻

SpringBoot 對(duì)這些資源提供自動(dòng)映射，也支持高度自定義。

二、SpringBoot 默認(rèn)靜態(tài)資源規(guī)則（自動(dòng)生效）

默認(rèn) 5 個(gè)靜態(tài)資源路徑（優(yōu)先級(jí)從高到低）：

• 1. META-INF/resources
• 2. resources/
• 3. static/（最常用）
• 4. public/
• 5. webapp/

默認(rèn)訪問(wèn)規(guī)則：
直接訪問(wèn)資源名即可，不需要加目錄前綴。

示例：

src/main/resources/static/images/logo.png

訪問(wèn)地址：

http://localhost:8080/images/logo.png

三、最常用場(chǎng)景：自定義靜態(tài)資源映射

實(shí)際項(xiàng)目中，我們會(huì)把用戶(hù)上傳的圖片/文件存放在服務(wù)器外部路徑，避免項(xiàng)目重新打包文件丟失。

這時(shí)候必須用：SpringMVC 資源映射

1. 編寫(xiě)配置類(lèi)

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;
/**
 * 靜態(tài)資源配置
 */
@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
    /**
     * 靜態(tài)資源映射
     * 訪問(wèn)路徑 /uploads/xxx.jpg  →  映射到本地 D:/uploads/xxx.jpg
     */
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 1. 訪問(wèn) URL 規(guī)則
        registry.addResourceHandler("/uploads/**")
                // 2. 本地真實(shí)路徑（末尾必須加 /）
                .addResourceLocations("file:D:/uploads/");
        // 2. 也可以配置相對(duì)路徑
        registry.addResourceHandler("/static/**")
                .addResourceLocations("classpath:/static/");
    }
}

2. 訪問(wèn)示例

本地文件：

D:/uploads/avatar.jpg

訪問(wèn)地址：

http://localhost:8080/uploads/avatar.jpg

四、application.yml 配置靜態(tài)資源

如果你不想寫(xiě)配置類(lèi)，可以直接在 yml 中配置：

spring:
  web:
    resources:
      # 自定義靜態(tài)資源路徑
      static-locations: classpath:/static/,classpath:/public/,file:./uploads/

?? 注意：
配置后會(huì)覆蓋默認(rèn)路徑，不是追加，所以要把需要的路徑都寫(xiě)上。

五、靜態(tài)資源放行（解決 Shiro/Security 攔截 404）

如果項(xiàng)目集成了 Shiro/Spring Security，靜態(tài)資源會(huì)被登錄攔截，必須手動(dòng)放行：

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（網(wǎng)站圖標(biāo)）

只需要把 favicon.ico 放到：

resources/static/favicon.ico

SpringBoot 自動(dòng)加載，無(wú)需任何配置。

七、SpringBoot 靜態(tài)資源緩存（生產(chǎn)優(yōu)化）

registry.addResourceHandler("/static/**")
        .addResourceLocations("classpath:/static/")
        // 瀏覽器緩存 10 天
        .setCachePeriod(864000);

八、圖片上傳 + 回顯完整實(shí)戰(zhàn)

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));
    // 返回可訪問(wèn)的 URL
    String url = "http://localhost:8080/uploads/" + fileName;
    return Result.success(url);
}

2. 配置映射

registry.addResourceHandler("/uploads/**")
        .addResourceLocations("file:D:/uploads/");

九、Linux 服務(wù)器部署路徑寫(xiě)法

registry.addResourceHandler("/uploads/**")
        .addResourceLocations("file:/usr/local/uploads/");

十、靜態(tài)資源 404 常見(jiàn)原因

• 1. 路徑末尾缺少 /
  • 錯(cuò)誤：/uploads
  • 正確：/uploads/**
• 2. 本地路徑末尾缺少 /
  • 錯(cuò)誤：file:D:/uploads
  • 正確：file:D:/uploads/
• 3. 被攔截器/權(quán)限框架攔截
  • 需要放行靜態(tài)資源
• 4. Windows 與 Linux 路徑格式不一致
  • Windows：D:/uploads/
  • Linux：/usr/local/uploads/
• 5. 目錄權(quán)限不足
  • Linux 需要給目錄讀寫(xiě)權(quán)限

十一、SpringBoot 靜態(tài)資源核心總結(jié)

• 1. 默認(rèn)路徑：static 文件夾直接訪問(wèn)
• 2. 外部文件：用 addResourceHandler 映射
• 3. 圖片上傳：必須用外部路徑，避免打包丟失
• 4. 權(quán)限攔截：一定要放行靜態(tài)資源
• 5. 路徑格式：末尾必須加 /
• 6. 生產(chǎn)環(huán)境：配置緩存提升性能

掌握這些，所有靜態(tài)資源問(wèn)題全部解決！

 總結(jié)與建議

• 簡(jiǎn)單項(xiàng)目：直接使用默認(rèn)的 src/main/resources/static 目錄存放所有靜態(tài)資源即可，無(wú)需任何配置。
• 需要區(qū)分請(qǐng)求：在 application.yml 中設(shè)置 spring.mvc.static-path-pattern： /resources/**，為靜態(tài)資源請(qǐng)求統(tǒng)一加上前綴。
• 處理上傳文件：不要使用 static-locations，而是創(chuàng)建一個(gè)配置類(lèi)，通過(guò) addResourceHandlers 方法將特定 URL 映射到磁盤(pán)絕對(duì)路徑。

到此這篇關(guān)于SpringBoot 靜態(tài)資源訪問(wèn)(圖片/JS/CSS)配置詳解(最新推薦)的文章就介紹到這了,更多相關(guān)SpringBoot 靜態(tài)資源訪問(wèn)配置內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

最新評(píng)論