JSP include 指令與 include 動作差異完整解析

快速比較表

include 指令（靜態包含）

語法

<%@ include file="header.jsp" %>

運作機制

1. JSP 容器在編譯階段將指定檔案內容原文插入主頁
2. 合併後產生單一 Servlet 類別
3. 被包含檔案的 <%! ... %> 宣告、<% ... %> 程式碼片段、HTML 全部融合

特性與陷阱

• 變數衝突：主頁與被包含頁若宣告同名區域變數會編譯失敗
• 共享範圍：request、session、application 物件當然共享
• 修改不立即生效：修改被包含檔後，必須觸發主頁重新編譯（修改主頁或刪除編譯產出的 class 檔）
• 適用場景：頁首/頁尾、共用常數宣告、工具函式、靜態 HTML 片段

include 動作（動態包含）

語法

<jsp:include page="menu.jsp" flush="true">
    <jsp:param name="category" value="news" />
</jsp:include>

運作機制

1. 主頁 Servlet 執行時，遇到 <jsp:include> 暫停
2. 容器建立新請求處理被包含頁，產生輸出
3. 將輸出寫入主頁回應流（flush="true" 強制刷新）
4. 主頁繼續執行

特性與優勢

• 隔離變數：被包含頁有獨立的 pageContext，區域變數不衝突
• 即時生效：修改被包含頁，下一次請求即見新內容
• 可傳參數：透過 <jsp:param> 傳遞資料
• 可包含 Servlet：page 屬性可指向 Servlet URL
• 適用場景：動態側邊欄、個人化區塊、獨立功能元件、需參數化的片段

程式碼範例對比

指令版：共用變數宣告

<!-- common_decls.jsp -->
<%! 
    public static final String SITE_NAME = "MySite";
    public String formatDate(Date d) { ... }
%>

<!-- main.jsp -->
<%@ include file="common_decls.jsp" %>
<%= SITE_NAME %> <%= formatDate(new Date()) %>

動作版：參數化動態片段

<!-- user_card.jsp -->
<%@ page import="java.util.*" %>
<%
    String name = request.getParameter("name");
    String role = request.getParameter("role");
%>
<div class="card">
    <h4><%= name %></h4>
    <span class="role"><%= role %></span>
</div>

<!-- dashboard.jsp -->
<jsp:include page="user_card.jsp" flush="true">
    <jsp:param name="name" value="<%= currentUser.getName() %>" />
    <jsp:param name="role" value="<%= currentUser.getRole() %>" />
</jsp:include>

常見誤區與最佳實踐

誤區 1：以為動作包含也能共享區域變數

錯誤寫法：

<!-- main.jsp -->
<% String msg = "Hello"; %>
<jsp:include page="show.jsp" />

<!-- show.jsp -->
<%= msg %> <!-- 編譯錯誤：msg 未定義 -->

正確做法：放入 request 範圍：

<% request.setAttribute("msg", "Hello"); %>
<jsp:include page="show.jsp" />

<<%= request.getAttribute("msg") %>

誤區 2：大量靜態內容用動作包含影響效能

純靜態 HTML 片段（版權聲明、導航列結構不變）用指令包含較佳，避免每次請求額外處理開銷。

現代替代方案：JSP 標籤檔 / Fragment

JSP 2.0+ 推薦使用 .tag 檔案（放在 /WEB-INF/tags/），提供更強大的封裝與參數型別檢查：

<!-- /WEB-INF/tags/userCard.tag -->
<%@ tag body-content="empty" %>
<%@ attribute name="name" required="true" type="java.lang.String" %>
<%@ attribute name="role" required="true" type="java.lang.String" %>
<div class="card"><h4>${name}</h4><span>${role}</span></div>

<-- 使用 -->
<%@ taglib prefix="my" tagdir="/WEB-INF/tags" %>
<my:userCard name="${user.name}" role="${user.role}" />

總結建議

• 靜態、共用、不變 → <%@ include %>（或改用 Tag File）
• 動態、參數化、獨立更新 → <jsp:include>
• 新專案 → 優先考慮 Tag File 或前端框架組件化