ssg 的本质是将内容交付链路提前固化于构建阶段，输出物理存在、无状态、可缓存的 html 文件以直上 cdn；需确保资源路径正确、front matter 严格合规、模板引擎可控输出路径、动静资源分离部署。
SSG 不是“把页面存成 HTML”这么简单，而是把整个内容交付链路提前固化在构建阶段——它直接决定了你能否用 CDN 边缘节点扛住百万级并发，而不是靠扩容 Node 服务器硬撑。
SSG 输出的 HTML 文件为什么能直上 CDN？
因为它们是物理存在的、无状态的、可缓存的字节流。CDN 不需要理解 React 或 Vue，只认 index.html、/blog/post-1/index.html 这类路径；只要文件存在、HTTP 响应头里有 Cache-Control: public, max-age=31536000，边缘节点就能长期缓存并秒级响应。
- 所有 JS/CSS/图片都必须是相对路径或带完整哈希的绝对路径（如
/static/css/main.a1b2c3.css），否则 CDN 回源时会 404 - HTML 内不能含运行时生成的动态 class 或 data 属性（比如
class="post--{{ status }}"中的status必须在构建时确定，不能留到浏览器里算） - 如果用了
getStaticProps（Next.js）或eleventyConfig.addPassthroughCopy（Eleventy），要确认ads.txt、robots.txt、.well-known/这类非模板文件确实被复制进输出目录，否则 Google 搜索控制台会报错
Front Matter 解析失败会导致 SSG “静默失效”
你看到页面生成了，但标题为空、日期显示 Invalid Date、layout 没生效——这大概率不是模板写错了，而是 Front Matter 没被正确提取。
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
- 开头必须是紧贴首行的
---，前面不能有空行、BOM 字符、HTML 注释（<!-- -->）或 UTF-8 BOM - YAML 中冒号后必须有空格，
date:2026-06-11会解析失败，得写成date: 2026-06-11 - Hugo 默认只认
---，Jekyll 可配front_matter: { delimiter: "+++" }，但你的解析逻辑（比如自定义脚本）必须同步适配 - 字段名大小写敏感：
Date和date在 Hugo 中是两个变量，模板里写{{ .Date }}却只写了date: ...就会取不到值
模板引擎选型直接影响构建稳定性和路径控制能力
不是语法越像 JS 就越容易上手，而是要看它是否允许你在构建时完全掌控输出路径和文件结构——这对 CDN 缓存命中率至关重要。
- Go Template（Hugo）：路径拼接靠
{{ "/blog/" | relURL }}，但relURL依赖baseURL配置，本地开发和生产环境不一致就会导致链接 404 - Liquid（Jekyll / Eleventy 默认）：支持
{% assign path = page.url | prepend: site.baseurl %}，但过滤器链过长时容易漏掉空值判断，page.url为 null 会导致整个页面构建失败 - Nunjucks（Eleventy 可切换）：支持
{% set url = (page.url or '/') %}这种 JS 式 fallback，但若在模板里调用async函数（比如想实时 fetch 数据），构建会直接中断——SSG 构建阶段不执行异步代码
混合部署时 SSG 页面和动态接口的边界必须清晰
很多团队误以为“SSG + API 就是动静分离”，结果在 HTML 里埋了 fetch('/api/user')，却没意识到：这个请求仍要走 origin server，CDN 完全不缓存它，高并发下 origin 成瓶颈。
- 真正静态的部分（文章正文、作者信息、分类列表）必须全部在构建时注入 HTML，不能留白等 JS 去填
- 需要动态的部分（用户评论、实时点击数、个性化推荐）必须拆成独立接口，并设置短缓存（
Cache-Control: no-cache或max-age=60），且接口域名最好和静态资源域名分离（如static.example.comvsapi.example.com） - Next.js 的
getStaticProps+getServerSideProps混用时，别在同一个页面里混写；要么整页 SSG，要么用fallback: true+ ISR，否则构建产物里会混入服务端代码，破坏纯静态本质
最容易被忽略的是：SSG 的“静态”不是指内容不变，而是指“页面结构与数据绑定关系在构建那一刻就已固化”。哪怕你每小时跑一次 hugo build，只要中间没改模板或 Front Matter 规则，输出的 HTML 就仍是可预测、可缓存、可验证的原子单元——这才是它能在高性能分发架构里站稳脚跟的根本。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
