Eleventy配置需显式声明dir、templateFormats等核心项，避免隐式路径与格式遗漏；addPassthroughCopy仅搬运静态资源，不可替代构建处理；addTransform仅作用于终态HTML，不介入数据或模板渲染。
Eleventy 默认不强制任何目录结构或模板约定，但随意组织会导致构建变慢、复用困难、协作混乱——真正影响效率的不是工具本身，而是配置方式是否贴合项目实际演进路径。
eleventy.config.js 中 dir 配置必须显式声明 input 和 output
默认 input 是当前目录，output 是 _site，但一旦项目分多站点或含共享资源，隐式路径会引发构建遗漏或覆盖冲突。比如把文档和博客混在根目录下，npx eleventy 可能错误地把 docs/ 下的 .md 也当成页面生成，而你本意只让它参与文档站点构建。
显式声明能切断歧义：
module.exports = function(eleventyConfig) {
return {
dir: {
input: "src", // 所有源文件必须在此之下
output: "_site", // 构建产物统一出口
includes: "_includes",
data: "_data"
}
};
};
- 如果多个子站点共用一套模板，
includes和data路径应指向共享目录（如../shared/_includes），而非每个子目录重复一份 -
input不支持数组，不能写成["src", "docs"]；需靠addPassthroughCopy或插件补位 - 修改
output后，本地服务端口映射、CI/CD 脚本里的部署路径都得同步更新，否则上线看到的是旧文件
templateFormats 必须按实际使用语言精确声明
Eleventy 默认只处理 html、md、njk、liquid 等已注册格式，未声明的扩展名（如 .webc、.11ty.js）会被跳过，即使文件存在也不会参与构建。
立即学习“前端免费学习笔记（深入）”；
常见误操作是删掉配置里某一项，以为“不用就不用”，结果发现组件没渲染、数据文件没加载——因为 _data 目录下的 site.11ty.js 依赖 javascript 在 templateFormats 中被启用：
module.exports = function(eleventyConfig) {
eleventyConfig.setTemplateFormats([
"html",
"md",
"njk",
"js" // ← 必须加上，否则 .11ty.js 数据文件不生效
]);
};
-
js格式用于_data和_includes中的动态数据模块，漏掉会导致page.url、pagination等全局变量为空 -
webc必须配合@11ty/eleventy-plugin-webc插件使用，单独加进templateFormats没用 - 声明了但没对应插件（如写了
"md"却没装@11ty/eleventy-plugin-md），构建时不会报错，但 Markdown 渲染逻辑缺失，输出的是原始文本
addPassthroughCopy 不是万能的静态资源搬运工
很多人用 addPassthroughCopy("assets") 把图片、字体、第三方 JS 全丢进 _site，看似省事，实则埋下三个隐患：路径硬编码失效、缓存失控、构建体积膨胀。
更可控的做法是分层处理：
- 图标、logo 等内容型静态资源 → 用
addPassthroughCopy，确保原样输出 - CSS/JS 文件 → 交给 PostCSS 或 ESBuild 处理后再输出，避免直接复制未压缩版本
- 第三方库（如
prism.js）→ 用npm install+require.resolve动态引入路径，防止版本错乱
例如正确引用 Prism：
eleventyConfig.addPassthroughCopy({
[require.resolve("prismjs/themes/prism.css")]: "assets/css/prism.css",
[require.resolve("prismjs/components/prism-javascript.min.js")]: "assets/js/prism.js"
});
这样既保证路径准确，又让 npm 版本管理生效，而不是手动下载再复制。
自定义 transform 的执行时机容易被忽略
addTransform 是 Eleventy 最灵活的钩子之一，但它在所有模板渲染完成后才运行，且只对最终 HTML 字符串起作用——这意味着它无法修改 page 对象、无法介入数据计算、也无法影响 pagination 分页逻辑。
典型误用场景：
- 想用 transform 给每个
<h2>加锚点 ID，却忘了它对 Nunjucks 中{% include %}的嵌套内容无效（因为嵌套内容已在 transform 前完成渲染） - 在 transform 中调用异步 API（如获取最新 GitHub stars 数），结果构建卡死或返回空值——transform 是同步函数，不支持 await
- 用正则替换
<img src="...">为懒加载格式，但没处理srcset或loading="eager"，导致部分图片仍阻塞渲染
真正需要动态处理的，应该放在 addGlobalData 或自定义 shortcode 里，而不是塞进 transform。
Eleventy 的配置自由度高，但也意味着每个选项的边界都很清晰——dir 决定范围，templateFormats 控制解析权，addPassthroughCopy 只负责搬运，addTransform 仅作用于终态 HTML。越早明确这些分工，后续加功能、换团队、扩规模时踩的坑就越少。
