Spring MVC 註解掃描失效根因分析與解決方案

問題現象

專案啟動無錯誤，但 Controller 請求映射全部 404。頁面跳轉失效，請求未被任何 @RequestMapping 攔截，直接落入預設 Servlet 處理。

錯誤配置回顧

<!-- 錯誤示範 -->
<context:component-scan base-package="com.cjw.test.controller" use-default-filters="false">
</context:component-scan>
<mvc:annotation-driven/>
<mvc:default-servlet-handler/>

雖開啟 use-default-filters="false"，但未顯式指定只掃描 @Controller，導致掃描器不知該納入哪些註解類別。

修正方案一：精確指定掃描目標

<context:component-scan base-package="com.cjw.test.controller" use-default-filters="false">
    <context:include-filter type="annotation" expression="org.springframework.stereotype.Controller"/>
</context:component-scan>

明確告訴掃描器：只註冊標註 @Controller 的 Bean。

核心關鍵：<mvc:annotation-driven/> 不可或缺

實驗發現，移除 <mvc:annotation-driven/> 後同樣 404。原因在於：

• 缺少它： 所有 Controller 的 @RequestMapping 不會被解析，請求無對應 Handler，全部轉給 default-servlet-handler 處理靜態資源 → 404。
• 擁有它： 啟用 RequestMappingHandlerMapping、RequestMappingHandlerAdapter 等核心組件，Controller 映射生效；無對應 Controller 的請求（如靜態資源）才交給 default-servlet-handler。

結論： component-scan 負責「發現並註冊 Bean」，annotation-driven 負責「賦予註解行為能力」，兩者缺一不可。

web.xml 關鍵配置

<servlet-mapping>
    <servlet-name>dispatcher</servlet-name>
    <url-pattern>/</url-pattern> <!-- 攔截所有請求，含靜態資源 -->
</servlet-mapping>

搭配 default-servlet-handler 讓靜態資源（CSS/JS/圖片）正常服務。

總結檢查清單

1. component-scan 是否精確指定 include-filter @Controller？
2. <mvc:annotation-driven/> 是否宣告？
3. <mvc:default-servlet-handler/> 是否配合 url-pattern>/</url-pattern>？
4. Controller 類是否在掃描包路徑下且標註 @Controller？
5. 方法是否標註 @RequestMapping 且路徑正確？

逐項排查，Spring MVC 註解掃描失效問題即可迎刃而解。