Eleventy 无内置热重载，需运行 npx @11ty/eleventy --serve 启动基础服务器，修改文件后需手动刷新；如需自动刷新，应集成 browser-sync 并通过 npm-run-all 并行运行构建与监听服务。
如何在 VSCode 中启动 Eleventy 开发服务器
Eleventy 本身不带内置热重载（HMR）服务，eleventy --serve 启动的是一个基础的静态文件服务器，只监听文件变化并重建页面——但不会自动刷新浏览器。直接在终端运行 npx @11ty/eleventy --serve 是最轻量的启动方式，适合快速验证内容渲染是否正常。
常见错误现象：执行后控制台显示 Local server: http://localhost:8080，但修改 .md 文件后页面没变 → 实际是重建完成了，但浏览器未刷新，需手动 F5；这不是 bug，是 Eleventy 默认行为。
- 确保项目根目录存在
.eleventy.js或eleventy.config.js，否则--serve可能报错Error: Could not locate configuration file - 若使用自定义输入目录（如
src/），必须显式传参：npx @11ty/eleventy --input=src --serve - 端口被占用时，加
--port=3000指定新端口，避免卡在Waiting for localhost:8080
为什么不能直接用 VSCode 的“运行和调试”面板启动 eleventy
VSCode 的默认 Node.js 调试配置（launch.json 中 type: "node"）会尝试 attach 到一个正在运行的 Node 进程，而 eleventy --serve 启动后立即进入监听循环，并不暴露调试端口。直接配置 "program": "node_modules/@11ty/eleventy/cmd.js" 通常失败，报错 Cannot find module '.../cmd.js' —— 因为该路径随安装方式（全局 vs 本地）和包管理器（npm vs pnpm）变化，不可靠。
真正可行的方式是绕过直接调试 Eleventy CLI 本身，转而调试你自己的配置逻辑或插件代码：
- 在
.eleventy.js开头加debugger;，然后用node --inspect-brk node_modules/@11ty/eleventy/cmd.js --serve启动（注意：仅限本地安装，且需确认cmd.js存在） - 更稳定的做法：把 Eleventy 配置拆成独立模块（如
config/eleventy.js），在launch.json中设"program": "./config/eleventy.js"并启用"runtimeExecutable": "npx"，配合"args": ["@11ty/eleventy", "--serve"] - 绝大多数用户其实不需要调试 Eleventy 内部，只需验证
addFilter、addCollection等函数行为 → 直接在配置文件里加console.log，比断点更高效
如何让保存 Markdown 时自动重建 + 浏览器刷新
Eleventy 原生不支持 Live Reload，但可以借助 browser-sync 补足。这不是 VSCode 特有功能，但能在编辑器内无缝集成：
先安装依赖：npm install --save-dev browser-sync
然后在 package.json 中添加脚本：
"scripts": {
"dev": "npx @11ty/eleventy --serve && npx browser-sync start --server dist --files 'dist/**/*' --no-open"
}
注意：这里用了 && 是错的，实际应改用并发工具（如 npm-run-all），否则 browser-sync 不会启动。正确写法：
npm install --save-dev npm-run-all"dev": "npm-run-all --parallel eleventy:serve bs:watch""eleventy:serve": "npx @11ty/eleventy --serve""bs:watch": "npx browser-sync start --server dist --files 'dist/**/*' --no-open"
这样配置后，在 VSCode 中按 Ctrl+Shift+P → “Tasks: Run Task” → 选 dev，就能同时跑构建和刷新服务。修改 .md 文件后，Eleventy 重建 dist/，browser-sync 检测到文件变化，自动触发浏览器刷新。
调试 Eleventy 模板中的 JavaScript 逻辑（比如 Nunjucks 中的 {% set %} 或 {% js %}）
Eleventy 模板里嵌入的 JS（尤其是 {% js %} 块或 JavaScript template language）无法被 VSCode 断点捕获——它是在运行时由 V8 执行的字符串代码，不是源码文件的一部分。想验证这类逻辑，唯一可靠方式是输出日志：
- 在
.njk或.11ty.js中用console.log打印变量，查看终端输出（Eleventy 构建日志里会显示） - 如果用了
addJavaScriptFunction注册了自定义函数，可在函数体内加debugger，再用上面提到的--inspect-brk方式启动，Chrome DevTools 就能断点进去 - 避免在模板中写复杂逻辑：Eleventy 的设计哲学是“数据驱动”，把计算移到
data/或collections配置里，模板只负责展示
最常被忽略的一点：Eleventy 的 --serve 模式下，每次文件变更都会完整重建整个站点，不是增量编译。如果你的站点有几百个页面，保存一次 Markdown 可能卡顿 3–5 秒——这不是 VSCode 的问题，是 Eleventy 本身的限制，别误以为是配置错了。
