ssi 页面渲染异常主因是nginx未执行解析或解析中断，需分层验证：确认location中启用ssi on和ssi_types、检查被包含文件可访问及响应头合规、开启log_subrequest追踪子请求、规避富文本双层转义。
SSI 包含出错导致页面渲染异常，核心问题往往不是语法写错，而是 Nginx 未真正执行 SSI 解析，或解析过程中因路径、权限、MIME 类型、子请求日志缺失等环节中断。解决关键在于分层验证：先确认 SSI 功能是否启用并命中，再检查包含内容能否被正确读取与返回，最后用日志还原完整调用链。
确认 SSI 已启用且作用域匹配
SSI 不是全局生效的，必须在对应 location 块中显式开启：
- 确保配置了 ssi on;，且该指令位于处理 HTML/SHTML 请求的 location 内（不能只放在 http 或 server 块顶层）
- 匹配的 MIME 类型必须明确声明：ssi_types text/html text/shtml;（若包含 .html 文件，必须加 text/html）
- 避免 alias 与 root 混用：使用 root 时，
include virtual="/header.html"会拼成$root/header.html；用 alias 则需注意末尾斜杠和路径映射关系，否则 404 静默发生
验证被包含文件可访问且响应头合规
浏览器不直接请求 SSI 片段，但 Nginx 内部子请求会模拟 GET 访问它。需像调试普通接口一样验证：
- 手动 curl 被包含路径，例如
curl -I http://localhost/header.html，确认返回 200 + Content-Type: text/html - 检查文件权限和 SELinux 上下文（如启用），Nginx worker 进程必须有读取权限：
ls -Z /path/to/header.html - 若 header.html 本身也含 SSI，确保其所在 location 同样启用 ssi 和 ssi_types，否则嵌套包含中断
开启 log_subrequest 追踪子请求执行细节
默认日志看不到 SSI 包含行为，开启后才能定位失败点：
- 在对应 location 中添加：log_subrequest on;
- 定义带
$request_id和$request_completion的日志格式，例如：log_format ssi_log '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent req_id:"$request_id" sub:"$request_completion";' - 查看日志：主请求与子请求共享同一
req_id；若子请求 status 为 404/403，说明路径或权限问题；若 status 为 000 但 sub:"FAILED"，多因上游服务异常或超时
注意富文本场景下的双层解析冲突
当 SSI 标签来自数据库（如富文本编辑器保存的 <!--#include ...-->），需防止被前端或后端二次转义：
- Nginx SSI 解析发生在响应输出前，若后端已对 HTML 做了 htmlspecialchars，标签变成
<!--#include...，Nginx 就无法识别 - 确保后端返回原始未转义的 HTML 字符串，且响应头 Content-Type 必须为 text/html（不能是 application/json 或 text/plain）
- 若需编辑态保留 SSI 标签（不执行），应改用客户端模板语法（如
{{ includeHeader }}），而非服务端 SSI
