Spring MVC 頁面跳轉 404 錯誤全鏈路排查指南

前言

Spring MVC 項目啟動正常、首頁可訪問，但表單提交/頁面跳轉卻報 404。這通常是請求映射路徑、視圖解析器配置、Controller 返回值、表單 action 地址四個環節不匹配導致。本文提供系統性排查清單、常見錯誤模式與修正方案。

核心排查鏈路

1. 請求 URL → 2. DispatcherServlet 映射 → 3. HandlerMapping 匹配 Controller → 4. Controller 處理返回 ModelAndView / 視圖名 → 5. ViewResolver 解析物理視圖路徑 → 6. 視圖渲染響應

任一環節斷裂即 404。

常見錯誤模式與修正

1. 表單 action 與 @RequestMapping 不匹配

// JSP
<form action="upload/searchByFileName2/0" method="post">  // 相對路徑，易受當前頁面影響

// Controller
@RequestMapping(value="/searchByFileName2/{pagenow}")  // 缺少項目前綴 /upload
public ModelAndView searchByFilename(...) { ... }

修正：

• JSP 用絕對路徑：action="${pageContext.request.contextPath}/upload/searchByFileName2/0"
• 或 Controller 加類級映射：@Controller @RequestMapping("/upload")

2. 視圖解析器前綴/後綴與返回視圖名不符

<bean class="org.springframework.web.servlet.view.InternalResourceViewResolver">
    <property name="prefix" value="/WEB-INF/views/" />
    <property name="suffix" value=".jsp" />
</bean>

@Controller
public class LoginController {
    @RequestMapping("/login")
    public String login() { return "success"; }  // 解析為 /WEB-INF/views/success.jsp
}

檢查點：

• 返回值 "success" + prefix/suffix = /WEB-INF/views/success.jsp 文件是否存在？
• 是否誤返回 "success.jsp" 導致雙重後綴？
• 是否需避開 /WEB-INF/ 直接訪問保護？

3. Controller 返回 ModelAndView 但視圖名錯誤

mv.setViewName("success");  // 需與 ViewResolver 配置匹配
// 若配置了 prefix=/pages/ suffix=.jsp，實際尋找 /pages/success.jsp

4. web.xml 中 DispatcherServlet url-pattern 過濾攔截

<servlet-mapping>
    <servlet-name>springmvc</servlet-name>
    <url-pattern>*.htm</url-pattern>  // 僅攔截 .htm 結尾
</servlet-mapping>

若請求 /upload/searchByFileName2/0 不以 .htm 結尾，DispatcherServlet 不會處理 → 404。
修正：<url-pattern>/</url-pattern> (攔截所有) 或 <url-pattern>/*</url-pattern> (注意靜態資源)。

5. 靜態資源被攔截導致 404 (CSS/JS/圖片)

<mvc:default-servlet-handler />  // 或
<mvc:resources mapping="/resources/**" location="/resources/" />

6. 表單提交方法不匹配 (GET vs POST)

@RequestMapping(value="/login", method=RequestMethod.POST)  // 僅接受 POST
// JSP form method="get" → 404/405

快速定位技巧

1. 開啟 DEBUG 日誌：logging.level.org.springframework.web=DEBUG，查看 DispatcherServlet 處理流程、HandlerMapping 匹配詳情。
2. 瀏覽器 Network 面板：檢查實際請求 URL、Method、Status、Response。
3. 斷點調試 Controller：確認方法是否被調用、返回值為何。
4. 手動訪問視圖路徑：在瀏覽器輸入推測的物理路徑 /WEB-INF/views/success.jsp (需繞過保護) 或部署後直接訪問 /success.jsp (若未受保護)。

代碼規範建議 (預防 404)

• 類級 @RequestMapping("/module") + 方法級 @GetMapping("/list")，路徑清晰可控。
• 統一使用 @Controller + @RequestMapping，避免混用 @RestController 導致視圖解析失效。
• 視圖名常量化：public static final String VIEW_SUCCESS = "success";。
• JSP 用 ${pageContext.request.contextPath} 或 <c:url value="/login"/> 生成絕對路徑。
• 單元測試覆蓋 Controller：mockMvc.perform(post("/login")).andExpect(view().name("success"));。

針對原問題代碼的具體修正

原代碼中：

• JSP action="upload/searchByFileName2/0" 為相對路徑，若當前頁在 /upload/list.htm，實際請求變 /upload/upload/searchByFileName2/0 → 404。
• Controller 無類級映射，方法級 /searchByFileName2/{pagenow} 需全路徑匹配。
• web.xml *.htm 僅攔截 .htm，請求無後綴 → 不進 DispatcherServlet。

最小修正：

1. web.xml 改 <url-pattern>/</url-pattern>。
2. Controller 加 @RequestMapping("/upload")。
3. JSP 改 action="${pageContext.request.contextPath}/upload/searchByFileName2/0"。
4. 確認 InternalResourceViewResolver prefix/suffix 與返回視圖名匹配。

總結

Spring MVC 404 本質是請求路徑與處理鏈路不匹配。按「URL → web.xml → HandlerMapping → Controller → ViewResolver → 視圖文件」逐環節核對，配合 DEBUG 日誌與 Network 面板，可在分鐘級定位。規範路徑映射、統一視圖解析、編寫測試，是長效預防之道。