SSI 伺服器端包含技術全解析（二）：核心指令詳解與實戰模式

承接上篇啟用配置，本文深入剖析 SSI 核心指令——config、include、echo 的參數詳情、組合用法與實戰模式，助你構建可維護、高效能的靜態站點架構。

一、config 指令：全局行為配置

語法：<!--#config param="value" -->，**必須置於其他 SSI 指令之前**生效。

1. errmsg：自定義錯誤提示

<!--#config errmsg="<div class='ssi-error'>片段載入失敗，請聯繫管理員</div>" -->

替換預設的 [an error occurred while processing this directive]，提升用戶體驗、隱藏內部路徑。

2. timefmt：日期時間格式化

支援 strftime() 所有格式符號：

<!--#config timefmt="%Y-%m-%d %H:%M:%S %Z" -->
<!--#echo var="DATE_LOCAL" -->
<!-- 輸出：2024-04-12 14:30:05 CST -->

3. sizefmt：文件大小單位

• bytes：精確位元組（12345）
• abbrev（預設）：人類可讀縮寫（12K、1.2M）

<!--#config sizefmt="bytes" -->
<!--#fsize file="logo.png" -->

二、include 指令：片段復用核心

「修改一處，全站更新」的關鍵。兩種路徑模式：

1. virtual：虛擬路徑（推薦）

<!--#include virtual="/includes/header.html" -->

• 相對於網站根目錄（DocumentRoot），跨目錄引用無需計算相對層級。
• 支援動態腳本輸出：virtual="/cgi-bin/counter.cgi"
• **最佳實踐**：建立 /includes/ 目錄集中管理公共片段。

2. file：相對路徑（受限）

<!--#include file="header.html" -->

• 相對於**當前文檔目錄**，不支援 ../、絕對路徑。
• 每個子目錄需複製一份片段，**維護成本高，不推薦大型站點使用**。

3. 進階模式：參數化包含（模擬）

SSI 無原生參數傳遞，但可通過環境變量變通：

<!--#set var="PAGE_TITLE" value="產品列表" -->
<!--#include virtual="/includes/header.html" -->

在 header.html 中使用：<title><!--#echo var="PAGE_TITLE" --></title>

三、echo 指令：環境變量輸出

語法：<!--#echo var="VAR_NAME" -->，支援變量：

實戰：動態完整 URL 構建

<a href="https://example.com<!--#echo var="DOCUMENT_URI" -->">
  分享本頁
</a>

四、實戰架構模式

模式一：頁面骨架 + 內容注入

<!-- layout.shtml -->
<!DOCTYPE html>
<html>
<head><title><!--#echo var="PAGE_TITLE" --></title></head>
<body>
  <!--#include virtual="/includes/header.html" -->
  <main>
    <!--#include virtual="/content/<!--#echo var="CONTENT_FILE" -->" -->
  </main>
  <!--#include virtual="/includes/footer.html" -->
</body>
</html>

每個內容頁僅需：

<!-- product-a.shtml -->
<!--#set var="PAGE_TITLE" value="產品 A 詳情" -->
<!--#set var="CONTENT_FILE" value="product-a.html" -->
<!--#include virtual="/layout.shtml" -->

模式二：條件化輸出（配合 CGI/腳本）

<!--#include virtual="/cgi-bin/auth_check.cgi?action=banner" -->
<!-- auth_check.cgi 根據登錄狀態輸出不同 banner HTML -->

模式三：靜態化加速（配合 Cron）

1. 動態頁面（PHP/Node）生成內容片段至 /content/cache/。
2. SSI 頁面包含緩存片段：<!--#include virtual="/content/cache/article-123.html" -->
3. Cron 定期重新生成熱門頁面片段，兼具動態數據與靜態效能。

五、避坑指南

• ❌ include virtual 路徑以 / 開頭表示網站根，**非**文件系統根目錄。
• ❌ 巢狀包含深度過大（>5 層）會顯著增加延遲，扁平化片段結構。
• ❌ 二進制文件（圖片、PDF）**不可**用 include 包含，僅限文本/HTML 片段。
• ✅ 所有包含文件建議以 .html 或 .inc 結尾，配合 <Files ~ "\.inc$"> Order allow,deny Deny from all </Files> 防止直接訪問。
• ✅ 開發環境啟用 XBitHack off 便於即時預覽，生產環境 on 提升效能。