Apache 默认未启用 mod_include 模块，需通过 httpd -M 或检查 httpd.conf 启用；.html 文件默认不解析 SSI，须配置 Options +Includes、AddType 和 AddOutputFilter；file 与 virtual 路径规则不同，且需注意权限与 SELinux 限制。
确认 Apache 是否已启用 mod_include
SSI（Server Side Includes）依赖 mod_include 模块，它不是默认启用的。直接访问带 的页面却看到原始注释或 500 错误，大概率是模块没开。
检查方式：httpd -M | grep include（Linux/macOS）或 apache2ctl -M | grep include；Windows 下查 httpd.conf 是否有 LoadModule include_module modules/mod_include.so 且未被注释。
若未启用，需取消该行注释，并确保 Include conf/extra/httpd-includes.conf 类似行存在（或手动添加配置）。重启 Apache 后再验证。
让特定文件类型解析 SSI 指令
Apache 默认不会对 .html 文件执行 SSI —— 即使模块开着， 也只会原样输出。必须显式声明哪些后缀要交由 mod_include 处理。
在虚拟主机或目录配置中加入：
<directory>
Options +Includes
AddType text/html .shtml
AddOutputFilter INCLUDES .shtml
</directory>
说明：
Apache Superset 是一个广泛采用的开源 BI 平台，用于 SQL 探索、图表构建和仪表板交付。当代理需要查询仓库数据、组装仪表板或使用成熟的分析界面解释指标而不是临时笔记本代码时，此技能非常有用。
-
Options +Includes是必需的，否则即使类型匹配也会拒绝执行 SSI - 推荐用
.shtml作扩展名，避免对全站 HTML 增加解析开销；若硬要用.html，则改用AddOutputFilter INCLUDES .html，但注意性能影响 -
AddType确保响应头为text/html，防止浏览器下载文件
的两种路径写法与权限限制
SSI 的 file 和 virtual 参数行为差异很大，用错会直接报错或静默失败：
-
：只接受**相对于当前文件所在目录**的路径，不能向上跳转（即不支持../），否则 Apache 返回 500 并记日志：unable to include ... in parsed file -
：接受**相对于网站根目录**的路径（以/开头），支持完整路径，但要求目标文件在 DocumentRoot 内且可被 Web 访问 - 所有被包含文件都需满足 Apache 的读取权限（如
chmod 644）和 SELinux 上下文（Linux 发行版常见坑）
示例：当前页是 /var/www/html/blog/post.shtml，想引入同级的 nav.shtml，应写 ；若想引入 /var/www/html/includes/ads.html，必须写 。
调试 SSI 失败时优先看错误日志和响应头
SSI 不像 PHP 那样有明显报错页面，失败常表现为内容消失、注释残留或 500 页面。关键排查点：
- 打开 Apache 错误日志（
ErrorLog配置项指向的文件），搜索include或mod_include，常见提示如：unable to include ... not found、unable to include ... in parsed file - 用
curl -I http://localhost/test.shtml检查响应头是否含Content-Type: text/html；若为text/plain，说明AddType没生效 - 确认被包含文件本身没有语法错误（比如嵌套了未闭合的
）；SSI 不递归解析，但会因格式错乱中断后续处理
真实项目里最容易被忽略的是 SELinux 策略（RHEL/CentOS/Fedora）——即使文件权限 644，httpd_can_network_connect 关闭时连本地文件包含都会被拒，此时需 setsebool -P httpd_read_user_content 1。
