11ty 默认不解析纯.html文件，需通过添加空YAML front matter或配置addTemplateExtension("html", {templateLanguage: "njk"})启用模板处理；permalink控制输出路径，url仅用于链接生成；数据需按作用域正确加载，迁移时注意资源路径、JS运行时逻辑及watch重载限制。
怎么让 .html 文件被 11ty 当作模板处理
默认情况下，11ty 不会处理纯 .html 文件——它只认 .njk、.md、.liquid 等带模板语法的后缀。直接放一个 index.html 在 src/ 下，它会被原样复制，但不会解析其中的 {% set %} 或 {{ title }}。
解决方法是显式告诉 11ty：这个 HTML 也要走模板引擎流程：
- 在文件顶部加一段
---前置数据（YAML front matter），哪怕空着也行：--- --- <h1>{{ title }}</h1> - 或者在
.eleventy.js中配置：eleventyConfig.addPassthroughCopy("*.html"); // ❌ 这只是复制，不解析<br>eleventyConfig.addTemplateExtension("html", {<br> templateLanguage: "njk", // 或 "liquid"、"md"<br>}); // ✅ 让 .html 走 nunjucks 引擎 - 注意：如果用了
templateLanguage: "njk"，那文件里就得写 nunjucks 语法，不是所有 HTML 内联 JS 都能直接跑
permalink 和 url 在 HTML 模板里怎么控制输出路径
很多人把 index.html 放进 src/ 后发现生成到了 _site/src/index.html，而不是想要的 _site/index.html——这是 11ty 默认按源路径映射导致的。
必须用 permalink 显式指定目标位置：
- 在 HTML 文件顶部加：
--- permalink: /index.html ---
- 想输出到子目录？写成
permalink: /blog/welcome.html - 动态路径也支持：
permalink: /posts/{{ page.fileSlug }}/index.html，但注意page.fileSlug来自文件名，不是路径 - 别混淆
url：它是用于生成链接的（比如导航栏），不影响实际输出位置；permalink才决定文件落地哪儿
HTML 模板里引用 data、collections 为什么报错 undefined
常见现象：在 about.html 里写 {{ collections.posts | length }}，结果输出 0 或报错；或者 {{ myDataVar }} 完全不渲染。
立即学习“前端免费学习笔记（深入）”；
原因通常是数据加载时机或作用域没对上：
- 全局数据（
_data/*.js）可以直取，但要确保导出的是对象：module.exports = {<br> title: "My Site",<br> menu: [{ label: "Home", href: "/" }]<br>}; - 页面级数据（
about.11tydata.js）只对同名模板生效，about.html必须配about.11tydata.js，不能叫page.11tydata.js -
collections是构建时生成的，只有启用了对应模板语言（如.md或已注册的.html）且有匹配tags的文件，才会进集合；纯静态.html默认不入collections.all - 调试技巧：在模板里临时加
<pre class="brush:php;toolbar:false;">{{ page | dump }}</pre>（需启用dumpfilter）看当前上下文
从 HTML 迁移要注意的三个兼容性坑
直接把老 HTML 丢进 11ty 很容易翻车，尤其涉及路径、资源引用和构建流程时：
-
<img src="img/logo.png">在开发时可能正常，但生成后变成_site/img/logo.png—— 如果你没配addPassthroughCopy("img/**")，这图就 404 - 内联
<script>fetch("/api/data")</script>没问题，但如果是<script src="js/app.js"></script>，得确保js/app.js被 passthrough 或由其他插件处理，否则不会进_site - 使用了
document.write或依赖window.location.pathname做路由判断？静态页里这些值是固定的，运行时逻辑可能失效；这类 JS 最好拆出来单独处理或改用 build-time 数据注入
最常被忽略的一点：11ty 的 watch 模式不会自动重载 HTML 模板里的数据变更——改了 _data/site.js，得手动保存任意一个模板文件触发重建。
