OpenCms 中 JSP 管理機制深度解析

核心架構：VFS 虛擬文件系統

OpenCms 將所有資源（含 JSP）存儲於數據庫（VFS），而非真實文件系統 (RFS)。但 Servlet 容器只能編譯磁盤上的 .jsp 文件。OpenCms 通過「映射」機制橋接兩者：

1. 請求進入 OpenCmsServlet (映射 /opencms/opencms/*)。
2. 識別為 JSP 請求 → 將 VFS 中的 JSP 文件「存儲」至 Web 應用目錄 /WEB-INF/jsp/ 下。
3. 區分 online (發布版) 與 offline (編輯版) 兩個子目錄，實現版本隔離。
4. 文件名轉換：VFS 路徑 /index.jsp → 磁盤 /WEB-INF/jsp/online/index.jsp.jsp（雙重 .jsp 後綴）。
5. 處理 JSP 指令 (<%@ include file="..."%>, <%@ page errorPage="..."%>) 中的引用路徑，同樣進行映射轉換。
6. 調用 requestDispatcher.include() 交給容器標準編譯執行。

關鍵機制詳解

1. 文件名轉換

為避免同名衝突並保留 VFS 路徑信息，映射規則：
VFS_PATH + ".jsp" → DISK_PATH
例：/sub/page.jsp → /WEB-INF/jsp/online/sub/page.jsp.jsp

2. Online/Offline 隔離

• 編輯環境訪問 /WEB-INF/jsp/offline/...，修改即時生效，不影響線上用戶。
• 發布操作將 offline 目錄同步至 online 目錄。
• 共享同一 ServletContext（應用上下文），故 application 域屬性互通，需謹慎使用。

3. JSP 指令解析與映射

• 支持：<%@ include file="..." %>、<%@ page errorPage="..." %> → 自動映射被引用文件。
• 不支持：<jsp:directive.include file="..." /> (XML 語法)，無法解析路徑 → 被引用文件不會被映射 → 運行時報錯。必須使用標準指令語法。
• 其他標準動作 (jsp:useBean, jsp:setProperty 等) 無路徑引用，正常工作。

4. 靜態導出支持

• JSP 默認導出屬性 false（動態頁不適合靜態化）。
• 需導出時：右鍵資源 → 屬性 → 勾選「導出」，或程序化設置 CmsResource.setExported(true)。
• 靜態鏈接必須使用 <cms:link> 標籤或 cms.link() 方法，確保導出後路徑正確。

開發最佳實踐

1. 嚴格使用 <%@ include ... %> 替代 XML 指令語法。
2. 避免在 JSP 中直接操作 application 域，防止 online/offline 交叉污染；改用 OpenCms API (CmsFlexController, CmsJspStandardContextBean) 獲取上下文信息。
3. 模組化開發：將 JSP 放入模塊目錄 (/modules/myModule/jsp/)，利用模塊部署實現版本管理與熱部署。
4. 調試技巧：查看 /WEB-INF/jsp/online/ 下生成的 .java/.class 文件排查編譯錯誤；啟用 OpenCms 調試日誌 (org.opencms.jsp)。

常見問題排查

總結

OpenCms 通過 VFS→RFS 映射、Online/Offline 雙目錄、指令預解析，實現了 JSP 在 CMS 環境下的版本控制、工作流發布與靜態導出。開發者只需遵循「標準指令語法、謹慎用 application 域、善用 cms:link」三原則，即可順暢開發。