Eleventy是最轻量可控的HTML静态站点生成器，支持纯手写HTML/CSS/JS，无需强制JSX或Webpack，直接以.html为模板，通过front matter控制元数据，并可精准排除特定文件不处理。
用 eleventy 做 HTML SSG 最轻量且可控
想纯手写 HTML、CSS、JS，又想要自动构建、模板复用、目录生成？eleventy 是目前最贴合这个需求的静态站点生成器——它不强制 JSX、不捆绑 Webpack、不 hijack 你的文件结构，连 .html 文件都能直接当模板用。
常见错误是把它当 Next.js 用：装一堆插件、配 webpack.config.js、试图跑服务端逻辑。其实你只需要：
- 全局或项目本地安装：
npm install --save-dev @11ty/eleventy - 根目录放一个
.eleventy.js，内容只需导出空对象：module.exports = {}; - 把已有 HTML 放进
src/（比如src/about.html），运行npx @11ty/eleventy，输出就到_site/
它默认把 .html 当 Nunjucks 模板处理，变量如 {{ title }} 可直接从文件 front matter 读取，无需额外配置。
front matter 怎么写才不被 eleventy 忽略
Eleventy 要识别 front matter，必须满足两个硬性条件：开头三横线 ---，且必须紧贴文件首行（前面不能有空行、BOM、注释）。哪怕多一个空格或 UTF-8 BOM，整个 front matter 就失效，title、layout 全部读不到。
立即学习“前端免费学习笔记（深入）”；
正确写法示例（src/index.html）：
---
title: 首页
layout: base.njk
---
<h1>{{ title }}</h1>注意点：
-
layout值是文件名，不是路径；若放在_includes/下，就写base.njk，不用写_includes/base.njk - 如果用了
.html后缀模板（比如base.html），需在.eleventy.js中显式启用：eleventyConfig.setTemplateFormats(["html", "njk"]); - YAML 中避免用
:在值里（如desc: "foo: bar"），会解析失败；改用引号包裹或换 JSON front matter
如何让 eleventy 不处理某些 HTML 文件
有些 HTML 是给第三方用的（比如验证文件 googleabc123.html、ads.txt），你不想它被模板引擎解析、也不希望 front matter 被误读——eleventy 默认会处理所有 .html，但可以精准排除。
在 .eleventy.js 中加这条规则：
eleventyConfig.addPassthroughCopy("src/google*.html");
eleventyConfig.addPassthroughCopy("src/ads.txt");这会让这些文件原样复制到 _site/，跳过任何渲染和 front matter 解析。关键点：
-
addPassthroughCopy接收字符串或正则，但不支持 glob 通配符（**/*.html会失效） - 路径基于
input目录（默认是项目根），不是src/；所以如果src/是你的源目录，得先用eleventyConfig.setConfigPathOverride("./.eleventy.js")并设dir.input: "src" - 别用
addWatchTarget()替代——它只影响热重载，不影响构建行为
生成速度慢？检查是否启用了 watch 或 server 模式
本地开发时运行 npx @11ty/eleventy --serve 很方便，但很多人没意识到：这个命令默认开启文件监听 + 自动重建 + 内置服务器，CPU 占用高、首次构建慢，且会锁定某些文件句柄（尤其 Windows 下导致 Git 操作卡住）。
真正做静态生成时，只要干净构建：
- CI/CD 中一律用
npx @11ty/eleventy --input=src --output=_site --quiet -
--quiet关掉日志能提速 10%~20%，尤其页面超 50 个时明显 - 禁用
watch相关配置：确认.eleventy.js里没有eleventyConfig.setWatchThrottleWaitTime(0)这类调试残留 - 如果用了
liquidjs或markdown-it插件，它们的 parser 实例是单例复用的，但初始化开销大；简单站点坚持用 Nunjucks + 原生 HTML 模板，启动快一倍
复杂点在于：eleventy 的「静态」是相对的——它本质是构建时执行 JS 函数，每个 templateData 或 beforeBuild 钩子都可能引入异步 IO 或 CPU 密集操作，而这些不会报错，只会悄悄拖慢生成。
