Spring MVC靜態資源映射失效排查指南：從控制器配置到資源處理器優先級

典型現象

配置 `` 後，靜態資源 (JS/CSS/圖片) 返回 404，但根路徑 `/` 正常，Controller 也無法訪問。

排查路徑：按優先級從高到低

1. 檢查 DispatcherServlet 映射路徑 (最高優先級)

<!-- web.xml -->
<servlet-mapping>
    <servlet-name>dispatcherServlet</servlet-name>
    <url-pattern>/</url-pattern> <!-- 必須是 /，不能是 /* -->
</servlet-mapping>

❌ `/*` 會攔截所有請求包括靜態資源、JSP、轉發，**導致靜態資源處理器無法生效**。
✅ `/` 只攔截未匹配到靜態資源的請求，**讓容器默認 Servlet 處理靜態資源**，或由 Spring `ResourceHttpRequestHandler` 處理。

2. 啟動 Debug 日志，確認 ResourceHandler 註冊

# logback.xml / log4j2.xml
<logger name="org.springframework.web.servlet.resource" level="DEBUG" />
<logger name="org.springframework.web.servlet.handler" level="DEBUG" />

啟動日志關鍵信息：

Mapped URL path [/static/**] onto handler of type [ResourceHttpRequestHandler]

若無此日志，說明 `` 未生效，檢查配置文件是否被掃描、`` 是否開啟。

3. 檢查 Controller 請求映射衝突

@Controller
@RequestMapping("/") // ❌ 根路徑通配，攔截所有含 /static/ 的請求
public class BadController { ... }

@Controller
@RequestMapping("/api") // ✅ 明確業務前綴
public class GoodController { ... }

**原則**：Controller 映射**盡量具體**，避免 `@RequestMapping("/")` 或 `@RequestMapping("/**")` 搶佔靜態資源路徑。

4. 靜態資源物理路徑與 location 一致性

⚠️ `location` 必須以 `/` 結尾表示目錄，`mapping` 以 `/**` 結尾表示遞歸匹配。

5. Spring Boot 專用：屬性配置優先

# application.yml
spring:
  mvc:
    static-path-pattern: /static/**  # 默認 /**
  resources:
    static-locations: classpath:/static/,classpath:/public/  # 默認多個
    cache:
      period: 3600
      cachecontrol:
        max-age: 3600

Spring Boot 2.x+ **不需手寫 ``**，屬性配置即可。手寫配置可能覆蓋默認導致衝突。

6. 緩存/瀏覽器/代理干擾

• 強制刷新 `Ctrl+Shift+R` / 清除瀏覽器緩存。
• 檢查 Nginx/Apache 反向代理 `location /static/` 是否轉發正確。
• CDN 緩存未刷新。

快速自查 Checklist

1. ☐ `web.xml` → `url-pattern` 是 `/` 而非 `/*`？
2. ☐ 啟動 DEBUG 日志見 `Mapped URL path [/static/**]`？
3. ☐ Controller 無 `@RequestMapping("/")` 等通配搶佔？
4. ☐ `src/main/resources/static/` 目錄存在且文件在內？
5. ☐ Spring Boot 用 `spring.resources.static-locations` 而非 XML？
6. ☐ 瀏覽器 Network 面板請求 URL、Response Headers、`Content-Type` 正確？

總結

靜態資源 404 核心三大塊：**DispatcherServlet 映射 `/`**、**ResourceHandler 註冊生效**、**Controller 不搶佔路徑**。Spring Boot 專案優先用屬性配置，傳統 XML 專案核對 `url-pattern` 與 `` 對應關係。開啟 DEBUG 日志是定位最快捷徑。