Eleventy是最轻量可控的HTML SSG方案，支持纯手写HTML/CSS/JS，以.html为模板、front matter控制元数据，并可精准排除文件不处理。
eleventy 是最轻量可控的 HTML SSG 方案
如果你手头已有纯 index.html、about.html 这类文件，又想自动加 layout、注入元数据、生成目录页，但不想被 React/Vue/JSX 绑架——eleventy 就是目前最贴合需求的选择。它不强制你写组件、不 hijack 文件结构、连原生 .html 都能当模板用。
常见错误是把它当 Next.js 用：装一堆插件、配 webpack.config.js、试图在 .eleventy.js 里写服务端逻辑。其实你只需要：
- 全局或本地安装：
npm install --save-dev @11ty/eleventy - 根目录放一个
.eleventy.js，内容只需：module.exports = {}; - 把已有 HTML 放进
src/（如src/index.html），运行npx @11ty/eleventy - 输出默认到
_site/，直接可部署
它默认把 .html 当 Nunjucks 模板处理，{{ title }} 这类变量能直接从 front matter 读取，无需额外配置。
front matter 必须严格满足两个条件才生效
Eleventy 要识别 front matter，不是“有三横线就行”，而是硬性要求：
立即学习“前端免费学习笔记（深入）”；
- 开头必须是
---，且紧贴文件首行——前面不能有空行、BOM、HTML 注释或任何字符 - YAML 值里不能出现未引号包裹的冒号，比如
desc: foo: bar会解析失败；得写成desc: "foo: bar"或改用 JSON front matter
layout 的值是文件名，不是路径。如果模板放在 _includes/base.njk，就写 layout: base.njk，不要写 _includes/base.njk。若你用的是 base.html，需在 .eleventy.js 中显式启用：eleventyConfig.setTemplateFormats(["html", "njk"])。
如何让某些 HTML 文件完全跳过渲染
像 googleabc123.html、ads.txt 这类第三方验证文件，你既不想它被模板引擎解析，也不希望 front matter 被误读——eleventy 默认会处理所有 .html，但可以精准排除。
在 .eleventy.js 中加这两行：
eleventyConfig.addPassthroughCopy("src/google*.html");
eleventyConfig.addPassthroughCopy("src/ads.txt");
关键点：
-
addPassthroughCopy接收字符串或正则，但不支持 glob（**/*.html会失效） - 路径基于 input 目录（默认是项目根），不是
src/；如果你的源目录是src/，得先调用eleventyConfig.setConfigPathOverride("./.eleventy.js")并设置dir.input
Next.js 的 SSG 更适合 React 项目，但门槛明显更高
如果你已在用 React，并需要动态路由（如 product/[id].js）、增量静态再生（ISR）、多层数据嵌套，Next.js 的 getStaticProps 和 getStaticPaths 是成熟方案。但它要求你接受它的约定式路由、服务端 API 层、以及构建时的数据拉取模型。
容易被忽略的点：
-
getStaticPaths返回的paths必须覆盖所有要预渲染的动态路径，漏掉一个，访问时就是 404 -
fallback: false表示只渲染明确列出的路径；fallback: true会让未列出路径返回 fallback 页面，等客户端 hydrate 后再请求数据——这已不是纯 SSG，而是混合模式 - 构建时数据获取失败，整个页面生成中断，CI/CD 流程会卡住，必须做好错误兜底（比如缓存上一次成功数据）
SSG 不是“一键开启性能”，而是把运行时不确定性提前移到构建阶段。数据是否稳定、路径是否可枚举、错误是否可容忍——这些判断比写几行配置更关键。
