Apache 模組 mod_include

啟用伺服器端包含

伺服器端包含由 INCLUDES 篩選器 實作。如果包含伺服器端包含指令的文件套用 .shtml 副檔名，下列指令將讓 Apache 剖析這些文件，並將結果文件指定為 text/html 格式。

AddType text/html .shtml
AddOutputFilter INCLUDES .shtml

針對包含 shtml 檔案的目錄，必須輸入下列指令（通常在 <Directory> 區段，但如果設定了 AllowOverride Options，這個指令在 .htaccess 檔案中也有效）

Options +Includes

基於向下相容性的考量，server-parsed 處理模組 也會啟用 INCLUDES 篩選器。此外，Apache 會為任何文件類型為 text/x-server-parsed-html 或 text/x-server-parsed-html3 的文件啟用 INCLUDES 篩選器（而產生的輸出文件類型會是 text/html）。

如需深入了解，請參閱我們的 伺服器端包含教學。

含有伺服器端包含內容的 PATH_INFO

預設情況下，已處理伺服器端包含的檔案不再接受包含 PATH_INFO（尾隨路徑資訊）的要求。您可以使用 AcceptPathInfo 指令設定伺服器，以接受包含 PATH_INFO 的要求。

可用的組成元件

文件會以 HTML 文件的型式剖析，並將特殊指令嵌入為 SGML 註解。指令的語法為

value 通常會 enclose 在雙引號中，但也可以使用單引號（'）和反引號（`）。許多指令只允許單一的屬性-值配對。請注意，註解終止符（-->）之前應該要有空白，以確保它不會被視為 SSI 代碼的一部分。另外，開頭的 <!--# 是一個代碼，不可包含任何空白。

允許的組成元件列在下列表格中

組成元件	簡介
註解	SSI 註解
設定	設定輸出格式
echo	列印變數
執行	執行外部程式
fsize	列印檔案大小
flastmod	列印檔案的上次修改時間
包含	包含檔案
printenv	列印所有可用的變數
set	設定變數值

除了 mod_include 之外，其他模組也可以定義 SSI 組成元件。實際上，mod_cgi 提供了 exec 組成元件，且只有在載入此模組時才會提供這個元件。

註解組成元件

此指令不會輸出任何內容。它唯一的用途是在檔案中新增註解。這些註解不會列印出來。

此語法可在 2.4.21 及更新版本使用。

config 組成元件

此指令控制剖析的各項設定。有效的屬性為

echomsg（Apache 2.1 及更新版本）

若 echo 元素嘗試迴顯未定義的變數 value 會傳送一個訊息回用戶端。這會覆寫任何 SSIUndefinedEcho 指令。

<!--#config echomsg="[值未定義]" -->

errmsg

若分析文件時發生錯誤，value 會傳送一個訊息回用戶端。這會覆寫任何 SSIErrorMsg 指令。

<!--#config errmsg="[糟糕，出了點問題。]" -->

sizefmt

顯示檔案大小時，value 會設定要使用的格式。有效值為 bytes（以位元組計數）或 abbrev（以 Kb 或 Mb 計數，視情況而定），例如大小 1024 位元組將印出為「1K」。

<!--#config sizefmt="abbrev" -->

timefmt

印出日期時，value 是 strftime(3) 函式庫常式要使用的字串。

<!--#config timefmt=""%R, %B %d, %Y"" -->

echo 元素

此命令會印出下方定義的 include 變數 之一。如果該變數未設定，結果將由 SSIUndefinedEcho 指令決定。列印的任何日期都會受到目前設定的 timefmt 約束。

屬性

var

value 是要印出的變數名稱。

decoding

指定 Apache 是否應從變數中去除編碼，然後再進一步處理此變數。預設值為 none，表示不執行任何解碼。如果設定為 url，將執行 URL 解碼（也稱為百分比編碼；適用于連結中的網址）。如果設定為 urlencoded，將去除與 application/x-www-form-urlencoded 相容的編碼（在查詢字串中找到）。如果設定為 base64，將解碼 base64，如果設定為 entity，將去除 HTML 實體編碼。解碼是在對變數執行任何進一步編碼之前執行。可以透過指定多個逗號分隔的編碼來去除多個編碼。解碼設定將持續有效，直到遇到下一個解碼屬性或元素結束為止。

若要讓 decoding 屬性發揮作用，它必須先於對應的 var 屬性。

encoding

指定 Apache 輸出變數中的特殊字元之前如何編碼。如設定為 none，則不執行編碼。如設定為 url，則會執行 URL 編碼（又稱為 %-編碼；適合用在連結中的網址等）。如設定為 urlencoded，則會改為執行與 application/x-www-form-urlencoded 相容的編碼，並應與查詢字串一併使用。如設定為 base64，則會執行 base64 編碼。在 echo 元素的開頭，預設設定為 entity，產生實體編碼（適用於區塊等級 HTML 元素，例如段落文字）。這可以透過新增一個 encoding 屬性來變更，而且這個屬性會維持效力，直到遇到下一個 encoding 屬性或元素結束，以先發生的為準。

encoding 屬性必須先於對應的 var 屬性，才能發揮作用。

為了避免跨網站指令碼問題，您應該總是編碼使用者提供的資料。

範例

<!--#echo encoding="entity" var="QUERY_STRING" -->

exec 元素

exec 指令執行指定的 shell 指令或 CGI 指令碼。它需要 mod_cgi 出現在伺服器中。如果 選項 IncludesNOEXEC 被設定，此指令就會完全停用。有效的屬性為

cgi

這個值指定一個到 CGI 指令碼的（%-編碼）網址路徑。如果路徑不是以斜線（/）開頭，則視為相對應於目前的文件。透過此路徑參考到的文件會被呼叫為 CGI 指令碼，即使伺服器平常不會將它識別為 CGI 指令碼也是一樣。但是，該指令碼所在的目錄必須已啟用 CGI 指令碼（透過 ScriptAlias 或 選項 ExecCGI）。

CGI 指令碼會取得來自客戶端的原始要求的 PATH_INFO 和查詢字串 (QUERY_STRING)；這些不能在網址路徑中指定。除了標準的 CGI 環境外，include 變數也會提供給指令碼。

範例

<!--#exec cgi="/cgi-bin/example.cgi" -->

如果指令碼傳回 Location: 標頭而不是輸出，它就會被轉為 HTML anchor。

include virtual 元素應該優先於 exec cgi 使用。特別是，如果您需要透過查詢字串將額外的參數傳遞給 CGI 程式，則無法使用 exec cgi 來執行此動作，但可以使用 include virtual 來執行此動作，如下所示

<!--#include virtual="/cgi-bin/example.cgi?argument=value" -->

cmd

伺服器會使用 /bin/sh 執行指定的字串。除了通常的一組 CGI 變數外，還可以對指令碼使用 include 變數。

使用 #include virtual 幾乎在所有情況都比使用 #exec cgi 或 #exec cmd 來得合適。前者（#include virtual）使用標準 Apache 子請求機制來包含檔案或指令碼。它經過更廣泛地測試和維護。

此外，在某些平台（例如 Win32）和在使用 suexec 的 unix 上，你無法在 exec 指令中將參數傳遞到指令，或是包含指令中其他空白。因此，儘管下列指令在 unix 的非 suexec 組態下會運作，它將無法在 Win32 或執行 suexec 時產生預期結果

<!--#exec cmd="perl /path/to/perlscript arg1 arg2" -->

fsize 元素

這個指令印出指定檔案的大小，受 sizefmt 格式規範影響。屬性

file

值是相對應的目前正在分析的文件資料夾路徑。

這個檔案的大小為 <!--#fsize file="mod_include.html" --> bytes。

file 的值不能以斜線 (/) 開頭，它也不能包含 ../ 這個字串作為參照目前資料夾上層或文件根目錄之外的檔案。嘗試這麼做將會產生錯誤訊息：The given path was above the root path（已傳遞的路徑高於根路徑）。

virtual

值是一個（%-編碼的）URL 路徑。如果它不是以斜線 (/) 開頭，則它應被視為相對應目前文件。請注意，這將不會印出任何 CGI 輸出的大小，而是 CGI 腳本本身的大小。

請注意，在許多情況下，這兩個指令完全相同。然而，file 屬性不支援 URL 空間別名。

flastmod 元素

這個指令印出指定檔案的最後修改日期，受 timefmt 格式規範影響。屬性與 fsize 指令相同。

include 元素

這個指令將另一個文件或檔案的文字插入到分析過的文件中。任何包括的文件都受一般存取控制影響。如果包含分析過的文件的資料夾已設定 選項 IncludesNOEXEC，則只有文字 MIME 類型（text/plain、text/html 等）的文件才會被包。否則，CGI 腳本會使用指令中提供完整的 URL（包含任何查詢字串）以一般的方式呼叫。

屬性定義文件的所在位置，而且可以在 include 元素中出現多次；會輪流對 include 指令提供給的每個屬性執行包含。可用的屬性如下

file

值是一個相對於目前正在解析文件之目錄的路徑。它不能含有 ../，也不能是一個絕對路徑。因此，您無法包含位於文件根目錄之外，或在目錄結構中位於目前文件之上的檔案。virtual 屬性應該總是優先使用它。

virtual

值是一個（％編碼）URL 路徑。該 URL 不能包含一個範例或主機名稱，只能包含一個路徑和一個可選擇的查詢字串。如果它不是從正斜線（/）開頭，則它被認為與目前的文件相關。

從屬性建構一個 URL，且如果由客戶端存取該 URL，伺服器將回傳的輸出會包含在已解析的輸出中。因此，包含的檔案可以是巢狀的。

如果指定的 URL 是 CGI 程式，程式會被執行，而它的輸出會插入已解析檔案中的指令取代它。您可以在 CGI URL 中包含一個查詢字串

<!--#include virtual="/cgi-bin/example.cgi?argument=value" -->

include virtual 應該優先於 exec cgi 使用，以包含 CGI 程式的輸出至一個 HTML 文件。

如果 KeptBodySize 指令已正確設定且對這個包含的檔案有效，嘗試將 POST 請求傳送到封裝的 HTML 文件時將會傳遞至子請求作為 POST 請求。沒有該指令時，所有子請求會被處理為 GET 請求。

onerror

值是一個（％編碼）URL 路徑，如果先前嘗試包含一個檔案或虛擬屬性失敗時，會顯示它。這個屬性必須在所涵蓋的檔案或虛擬屬性之後指定，才能生效。如果嘗試包含 onerror 路徑失敗，或如果沒有指定 onerror，會包含預設的錯誤訊息。

# 簡單範例
<!--#include virtual="/not-exist.html" onerror="/error.html" -->

# 專用 onerror 路徑
<!--#include virtual="/path-a.html" onerror="/error-a.html" virtual="/path-b.html" onerror="/error-b.html" -->

printenv 元素

這會列印一個純文字清單，列出所有現有變數及其值。特殊字元會在輸出前以實體編碼（詳細資訊請參閱 echo 元素）。沒有屬性。

set 元素

這會設定變數的值。屬性

var

要設定的變數名稱。

value

要給予變數的值。

decoding

指定 Apache 在進一步處理變數之前是否要從變數中移除編碼。預設值為 none，表示不進行任何解碼。如果設定為 url、urlencoded、base64 或 entity，則會分別執行 URL 解碼、application/x-www-form-urlencoded 解碼、base64 解碼或 HTML 實體解碼。可以透過逗號分隔來指定多個解碼。解碼設定會持續有效，直到遇到下一個解碼屬性或元素結束為止。decoding 屬性必須 在 對應的 var 屬性之前出現才能生效。

encoding

指定 Apache 在設定特殊字元之前，如何對變數中包含的特殊字元進行編碼。預設值為 none，表示不進行任何編碼。如果設定為 url、urlencoding、base64 或 entity，則會分別執行 URL 編碼、application/x-www-form-urlencoded 編碼、base64 編碼或 HTML 實體編碼。可以透過逗號分隔來指定多個解碼。編碼設定會持續有效，直到遇到下一個編碼屬性或元素結束為止。encoding 屬性必須 在 對應的 var 屬性之前出現才能生效。編碼會在移除所有解碼後套用。

內含變數

除了標準 CGI 環境中的變數之外，這些變數可用於 echo 命令、if 和 elif，以及文件呼叫的任何程式。

DATE_GMT

格林威治標準時間的目前日期。

DATE_LOCAL

當地時區的目前日期。

DOCUMENT_ARGS

這個變數包含 active SSI 文件的查詢字串，如果沒有包含查詢字串，則為空字串。對於透過 include SSI 指令呼叫的子請求，QUERY_STRING 將會代表子請求的查詢字串，而 DOCUMENT_ARGS 將會代表 SSI 文件的查詢字串。（Apache HTTP Server 2.4.19 版本及後續版本才有提供）

DOCUMENT_NAME

使用者要求的文件檔名（不含目錄）。

DOCUMENT_PATH_INFO

尾端的路徑資訊。進一步瞭解 PATH_INFO，請參閱指令 AcceptPathInfo。

DOCUMENT_URI

使用者要求的文件的（經過 %-解碼）URL 路徑。請注意，在巢狀內含文件的狀況下，這 不是 目前文件的 URL。另外請注意，如果 URL 在內部被修改（例如透過 alias 或 directoryindex），會顯示修改後的 URL。

LAST_MODIFIED

使用者要求的文件最後修改日期。

QUERY_STRING_UNESCAPED

如果活動的 SSI 文件請求中含有查詢字串，這個變數包含 (% 解碼後的) 查詢字串，供 Shell 使用 (特殊字元如 & 等前面加上反斜線)。如果查詢字串不存在，不會設定。如果不需要 Shell 轉譯，請使用 DOCUMENT_ARGS。

USER_NAME

檔案擁有者的使用者名稱。

變數置換

變數置換出現在大部分情況的帶引號字串中，這些情況很可能作為 SSI 指令參數出現。這包含 config、exec、flastmod、fsize、include、echo 和 set 指令。如果 SSILegacyExprParser 設為 on，也會在條件運算子的參數中進行置換。您可以使用反斜線引號將文字美元號插入字串中

如果變數參照需要置換於字元序列中間，而該字元序列可能被視為本身的有效識別碼，則可以將參照括於括弧中，這類似於 Shell 中的置換

如果有 REMOTE_HOST 為 "X"、REQUEST_METHOD 為 "Y"，這將會導致 Zed 變數設為 "X_Y"。

流程控制元素

基本流程控制元素為

if 元素的工作原理，如同程式語言中的 if 陳述式。會評估測試條件，如果結果為 true，則會將文字包含於輸出串流中，直至下一個 elif、else、endif 元素。

如果原始 test_condition 為 false，elif 或 else 陳述式用於將文字置於輸出串流中。這些元素為選用項目。

endif 元素會終止 if 元素，且為必備項目。

test_condition 是一個布林表達式，遵循 ap_expr 語法。語法可以使用 SSILegacyExprParser 變更為相容於 Apache HTTPD 2.2.x。

使用 var 元素所設定的 SSI 變數會匯出至請求環境中，且可以使用 regvenv 函數存取。為了簡便，mod_include 內部也可以使用函數名稱 v。

下列範例會在客戶端 IP 位址屬於 10.0.0.0/8 網路時，列印「來自本地網路」。

如果變數 foo 設定為值 "bar"，以下範例將會印出 "foo is bar"。

舊版表達式語法

此部分說明了 #if expr 元素的語法，前提是將 SSILegacyExprParser 設為 on。

字串

若 string 不為空，則為 true

-A 字串

如果設定允許存取字串所代表的 URL，則為 true；否則為 false。這會在頁面上的內容對未被授權檢視 URL 的使用者隱藏時很有用，例如連結到該 URL。請注意，URL 僅測試是否會被授予存取權限，而不測試 URL 是否存在。

範例

<!--#if expr="-A /private" -->
按一下 <a href="/private">這裡</a>，以存取私人資訊。
<!--#endif -->

string1 = string2
string1 == string2
string1 != string2

將 string1 和 string2 進行比較。如果 string2 的格式為 /string2/ ，它將被視為正規表示法。正規表示法是由 PCRE 引擎實作，且語法與 perl 5 中的語法相同。請注意，== 只是 = 的別名，且行為完全相同。

如果你正在配對正向 (= 或 ==)，你可以擷取正規表示法的群組化部分。擷取的部分儲存在特殊變數 $1 .. $9 中。正規表示法配對到的整個字串儲存在特殊變數 $0 中

範例

<!--#if expr="$QUERY_STRING = /^sid=([a-zA-Z0-9]+)/" -->
<!--#set var="session" value="$1" -->
<!--#endif -->

string1 < string2
string1 <= string2
string1 > string2
string1 >= string2

將 string1 和 string2 進行比較。請注意，字串會以字面意義進行比較 (使用 strcmp(3))。因此字串 "100" 小於 "20"。

( test_condition )

如果 test_condition 為 true，則為 true

! test_condition

如果 test_condition 為 false，則為 true

test_condition1 && test_condition2

如果 test_condition1 和 test_condition2 兩個都是 true，則為 true

test_condition1 || test_condition2

如果 test_condition1 或 test_condition2 其中一個為 true，則為 true

"=" 和 "!=" 的結合比 "&&" 和 "||" 更緊密。"!" 的結合最緊密。因此，下列兩者是相等的

布林運算子 && 和 || 有著相同的優先權。所以如果您想更嚴格地約束這樣的運算子，您應該使用圓括號。

任何無法識別為變數或運算子的東西都被視為字串。字串也可以用引號括起來：'string'。未加引號的字串不能包含空白（空格和標籤），因為這些是用來分隔像是變數這類的記號。如果在字串中找到了多個字串，它們會用空白串接。因此，

SSIEndTag "%>"

SSIErrorMsg "<!-- Error -->"

SSIStartTag "<%"
SSIEndTag   "%>"

SSITimeFormat "%R, %B %d, %Y"

SSIUndefinedEcho "<!-- undef -->"