本文介绍在不使用 javascript 动态加载的前提下，通过服务端包含（ssi）、构建工具、静态站点生成器等方案，实现 html 头部的集中维护与全站复用。
本文介绍在不使用 javascript 动态加载的前提下，通过服务端包含（ssi）、构建工具、静态站点生成器等方案，实现 html 头部的集中维护与全站复用。
在纯静态 HTML 网站开发中，将页眉（header）重复粘贴到每个 .html 文件中不仅低效，更违背“一次编写、多处复用”的工程原则。虽然原生 HTML 不支持文件内嵌引用（如 <!-- include header.html -->），但有多种成熟、轻量且无需运行时 JS 的解决方案，可根据项目规模与部署环境灵活选择。
✅ 推荐方案对比
| 方案 | 原理 | 是否需服务器支持 | 是否需构建步骤 | 适用场景 |
|---|---|---|---|---|
| 服务端包含（SSI） | Apache/Nginx 在响应前解析 <!--#include file="header.html" --> | ✅（需启用 SSI 模块） | ❌ | 已托管于支持 SSI 的传统主机（如 shared hosting） |
| 静态站点生成器（SSG） | 如 Hugo、Jekyll、Hugo：用模板（{{ partial "header.html" . }}）编译生成纯 HTML | ❌（仅本地构建时依赖） | ✅（需 hugo build 等命令） | 中小型静态站，追求可维护性与 SEO 友好 |
| 预处理器/构建工具 | 使用 PostHTML、Eleventy 或简单的 Node.js 脚本，在构建时注入头部内容 | ❌ | ✅（需配置脚本或插件） | 已有前端工作流（如 npm scripts），希望零学习成本介入 |
| 客户端 JS（备选） | fetch('header.html').then(...) + innerHTML | ❌ | ❌ | 仅当其他方案不可用时考虑；会延迟渲染、影响 SEO 和无障碍访问 |
? 示例：使用 Hugo 实现头部复用（推荐入门级 SSG）
-
创建布局文件：layouts/partials/header.html
<header class="site-header"> <nav> <a href="/">首页</a> <a href="/about">关于</a> <a href="/contact">联系</a> </nav> </header>
-
在主模板（如 layouts/_default/baseof.html）中调用：
anything-to-html下载将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
<!DOCTYPE html> <html> <head><title>{{ .Title }}</title></head> <body> {{ partial "header.html" . }} <main>{{ .Content }}</main> {{ partial "footer.html" . }} </body> </html> -
运行 hugo 命令后，所有页面自动注入统一头部 —— 修改 header.html 即全局生效。
立即学习“前端免费学习笔记（深入）”；
⚠ 注意事项
- 避免纯前端 JS 注入：尽管简单，但会导致首屏无导航、SEO 降权、CSP 策略冲突及爬虫不可见；
- SSI 需配置验证：Apache 中需启用 Includes 模块，并确保 .html 文件具有 +Includes 权限或使用 .shtml 扩展名；
- 路径一致性：无论采用哪种方案，header.html 的路径引用必须相对于当前处理上下文（模板路径 or 构建根目录），建议统一使用项目根目录为基准。
✅ 总结
“不重复添加代码”本质是工程化思维的体现。对于静态站点，静态站点生成器（如 Hugo）是最平衡的选择：零运行时依赖、完美 SEO、热重载开发体验，且学习曲线平缓。若受限于托管环境，优先启用 SSI；若已有构建流程，则集成 PostHTML 插件即可。拒绝复制粘贴，从一个可复用的 header.html 开始重构你的静态网站架构。
