千古前端教程：深入解析 SSI 服务器端嵌入（Server Side Include）与静态页面动态化-育师

文档
教程
前端

【免费下载链接】Web

千古前端图文教程，超详细的前端入门到进阶知识库。从零开始学前端，做一名精致优雅的前端工程师。

项目地址：https://gitcode.com/gh_mirrors/we/Web

导读

在 16-前端综合/html相关.md 中，作者记录了一个前端开发中容易忽略、但在真实站点中非常实用的机制——SSI（Server Side Include，服务器端嵌入）。通俗地说，SSI 允许你在一个"本地"的 HTML 静态页面中，以注释的形式插入服务器上其他文件的代码，从而让静态页面也能呈现动态拼接的内容。读完本文，你将掌握 SSI 的核心语法、Apache/Nginx 下的开启方式、典型应用场景（如公共头部/导航的复用），以及它与前端模板引擎之间的边界划分。

SSI 是什么：服务器端嵌入

SSI 全称Server Side Include，直译为"服务器端嵌入"，是 Web 服务器（如 Apache、Nginx）提供的一项传统服务端技术。

它的核心思想非常简单：

在本地的 HTML 页面中，插入服务器上的文件。即：静态页面中，插入动态的代码。

这句话包含两层含义：

静态页面：你编写的文件本身是.html或.shtml这样的静态文件，浏览器可以直接打开。
服务器端处理：当用户请求该页面时，服务器会在把响应返回给浏览器之前，先扫描页面中的特殊指令，把指令指向的服务器端文件内容"嵌入"进来，拼装成完整的 HTML 再下发。

从仓库的学习脉络看，这与 06-JavaScript基础：异步编程/00-服务器分类及PHP入门.md 中介绍的B/S 架构（浏览器 + 服务器）一脉相承：页面最终的呈现由服务器加工完成，浏览器只负责接收和渲染。

原文档示例逐行拆解

原文档给出了一个典型的 SSI 应用场景——在页面的<head>区域嵌入服务器端的公共头部文件：

<head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <meta http-equiv="X-UA-Compatible" content="ie=edge"> <title>Document</title> <style> </style> <!--#include virtual="/sinclude/common/head_inc.shtml"--> <!--#include virtual="/sinclude/common/head_shortcut.shtml"--> <!--#include virtual="head.shtml"--> </head>

这段代码中，三个 HTML 注释里写的正是 SSI 指令：

指令	说明
`<!--#include virtual="/sinclude/common/head_inc.shtml"-->`	以虚拟路径（站点根目录起始的绝对路径）引入服务器上的公共头部资源文件
`<!--#include virtual="/sinclude/common/head_shortcut.shtml"-->`	以虚拟路径引入"快捷导航"公共片段
`<!--#include virtual="head.shtml"-->`	以相对路径（相对当前页面）引入同目录下的公共头部片段

正如原文档所说："注释里的代码，就是 SSI 部分，它加载的是服务器端的 html 页面。"

需要注意，这类被引入的文件通常使用.shtml扩展名。.shtml是"SSI-enabled HTML"的惯例命名，用来标识该文件包含需要服务器解析的 SSI 指令；如果服务器未开启 SSI 解析，这段注释内容就只是普通注释，不会产生任何效果。

SSI 的指令语法与常见指令

SSI 指令全部写在 HTML 注释内部，基本格式为：

<!--#指令名 参数名="参数值" -->

#与指令名之间不能有空格，指令可以单独占一行，也可以与普通 HTML 混排。常见的指令包括：

#include：最核心的指令，把另一个文件的内容嵌入当前位置。它有两种寻址方式：
- virtual="/路径/文件"：虚拟路径，以站点根目录为起点，如；
- file="相对路径/文件"：文件路径，相对于当前文件所在目录，如。注意file方式禁止使用../向上越级引用，virtual方式则更灵活，是原文档示例采用的主流写法。
#exec：在服务器上执行外部程序或命令，如。该指令对服务器安全影响较大，多数生产环境默认关闭。
#echo：输出环境变量或 SSI 变量，如可以输出服务器本地时间。
#config：设置 SSI 输出格式，如时间格式、错误信息等。
#set/#if/#elif/#else/#endif：变量赋值与条件分支，可让静态页面具备简单的逻辑判断能力，例如根据QUERY_STRING参数决定输出哪一段内容。

如何开启 SSI：Apache 与 Nginx 的通用配置

SSI 属于服务端功能，需要在 Web 服务器上开启后才会生效（以下为业界通用配置方法，具体以你的服务器环境为准）：

Apache（通过 mod_include 模块）：确认加载了mod_include模块，在配置或.htaccess中开启解析，并指定.shtml（或.html）文件参与 SSI 解析。Apache 官方文档将#include的两种寻址方式规定为virtual（URL 路径）与file（文件系统相对路径）。
Nginx（通过 ssi 模块）：在http/server/location块中开启ssi on;，即可对响应内容中的 SSI 指令进行解析。

开启后，务必确认：

请求的页面确实经过了服务器解析（直接双击本地.html文件用浏览器打开，SSI 不会生效，因为此时没有服务器参与处理）；
被#include的服务器端文件路径正确、可读；
.shtml后缀与解析配置匹配。

这也是原文档强调"插入服务器上的文件"的原因——SSI 的"动态"发生在服务器端，而非浏览器端。

典型应用场景：静态站点的"公共部件复用"

SSI 最常见的价值，是解决纯静态站点中公共代码重复的问题。以原文档的示例为例：

全站每个页面都要引入相同的一套<meta>标签、外链 CSS/JS（对应head_inc.shtml）；
每个页面顶部都要展示相同的 logo、快捷导航（对应head_shortcut.shtml）。

如果没有 SSI，维护这些公共片段意味着要么复制粘贴到每个页面（改一处要全局同步），要么引入前端模板/构建工具。而使用 SSI 后，只需维护服务器上的一份公共文件，所有页面在请求时自动拼接，改一处即全站生效——这正是它在服务器端完成"动态化"的价值所在。

SSI 与前端模板引擎的分工边界

仓库的另一篇文档 16-前端综合/模板引擎.md 介绍了 ArtTemplate 等前端模板引擎：它们把 JSON 数据与 HTML 模板在浏览器端（JavaScript）通过正则替换等方式渲染成最终 DOM。两相对比，可以清晰看到分工：

维度	SSI 服务器端嵌入	前端模板引擎（如 ArtTemplate）
处理位置	服务器端，返回前完成	浏览器端，JS 执行时完成
数据来源	服务器文件、环境变量	Ajax 请求返回的 JSON 数据
典型用途	静态页公共片段复用、页面拼装	列表渲染、数据绑定、局部刷新
依赖条件	服务器开启 SSI 解析	引入模板 JS 库即可

两者并不冲突：SSI 负责"页面骨架的服务器端拼装"，前端模板负责"数据与结构的浏览器端渲染"。理解这条边界，有助于在实际项目中按需选用，避免把两类技术混为一谈。

注意事项与局限

依赖服务器解析：SSI 只有经过配置过的服务器才会处理，普通静态托管或本地直接打开.html时，指令仅以注释形式存在，不会生效；
缓存与性能：每次请求都需要服务器扫描、拼接，因此高并发场景下需结合服务器缓存策略使用；
安全限制：#exec等可执行指令存在安全隐患，生产环境应默认关闭，仅保留#include等无害指令；
排错技巧：页面中若出现"SSI 指令原文"或错误提示，优先检查服务器是否开启 SSI、文件路径是否正确、权限是否可读。

小结

SSI 是 Web 早期就存在的服务端嵌入机制，用"注释即指令"的巧妙方式，让纯静态页面也能完成公共部件的服务器端拼装。原文档 16-前端综合/html相关.md 用一个<head>区域的实例点明了它的核心用法：这类指令加载的正是服务器端的 HTML 页面。结合本仓库对 HTML 基础（如 01-HTML/01-认识Web和Web标准.md）、服务器架构（06-JavaScript基础：异步编程/00-服务器分类及PHP入门.md）与前端模板引擎（16-前端综合/模板引擎.md）的系统讲解，你可以在"纯静态方案"与"重前端工程化方案"之间，找到 SSI 这条轻量、可靠的服务端中间路线。