JFinal 靜態資源 404 問題根因與最佳解決方案

問題現象

JFinal 項目中，頁面引用的 CSS、JS、圖片等靜態資源返回 404，常見於部署路徑非根目錄（如 /myapp）時。

根因分析

JFinal 默認不自動處理上下文路徑，導致頁面中相對路徑解析錯誤。若 Tomcat 配置 path="" 強制部署到根目錄雖可暫時繞過，但違反規範，且多應用部署時衝突。

推薦解決方案：ContextPathHandler + <base> 標籤

1. 配置 Handler

@Override
public void configHandler(Handlers handlers) {
    handlers.add(new ContextPathHandler());
}

ContextPathHandler 會自動將 ${CONTEXT_PATH} 變量注入模板引擎，值為應用上下文路徑（如 /myapp）。

2. 頁面引用規範化

<head>
    <base href="${CONTEXT_PATH}/">
    <link rel="stylesheet" href="css/style.css">
    <script src="js/main.js"></script>
</head>

• <base href="${CONTEXT_PATH}/"> 設置頁面基準路徑，所有相對鏈接自動拼接上下文路徑。
• 資源引用改為相對路徑（css/style.css），不再硬編碼上下文路徑。

方案優勢

• 兼容 path=""（根部署）與 path="/myapp"（子路徑部署）雙模式，無需修改引用地址。
• 符合 Servlet 規範，支持多應用共存。
• 一處配置，全局生效，維護成本極低。

避坑提示

• 確保模板引擎（如 Enjoy、FreeMarker、JSP）已正確接收 CONTEXT_PATH 變量。
• 若使用 Nginx 反向代理，需同步配置 proxy_set_header Host 及 location 路徑轉發。
• 靜態資源建議配置 configConstant 中的 devMode 為 false 以啟用緩存。