11ty的--incremental参数未生效？增量构建异常问题咨询

首先，你的问题核心是**--incremental增量构建没有按预期工作**，导致每次执行npm run build时_site下所有文件的修改时间都更新了。结合你的配置和11ty的特性，我整理了几个关键排查点和修复方案：

1. 优先升级11ty版本（最关键） #

你当前使用的是@11ty/eleventy@0.12.1，这是一个比较老旧的版本（2021年发布），它的增量构建逻辑存在不少已知问题，比如依赖追踪不准确、passthrough文件处理逻辑不完善。

升级到最新的稳定版（比如v1.x或更高）会解决大部分增量构建的底层问题：

• 修改package.json中的devDependencies：

  "@11ty/eleventy": "^1.0.0"
  

• 执行npm install完成升级，之后再测试npm run build。

2. 检查增量构建的详细日志 #

添加--verbose参数运行构建，查看11ty认为哪些文件“发生了变化”，从而定位根因：

npx @11ty/eleventy --incremental --verbose

日志中会显示类似[11ty] Changed file: ./blog/post.md的条目，你可以从中看到11ty触发全量构建的原因（比如某个全局数据文件被修改、某个依赖的partial更新等）。

3. 修复Shortcode的依赖追踪 #

你的.eleventy.js中定义了几个异步shortcode，但没有告诉11ty它们的依赖关系。即使现在这些shortcode返回空字符串，11ty可能无法判断使用这些shortcode的模板是否需要重新渲染，从而默认重新构建所有相关模板。

如果你的shortcode实际会读取本地文件（比如image短代码读取图片），需要手动声明依赖：

async function imageShortcode(src, alt, width, height) {
  // 告诉11ty这个短代码依赖src对应的文件（v1.x版本用法）
  this.addDependency(src);
  // 你的实际逻辑...
  return '';
}

升级到v1.x后，shortcode的this上下文会包含addDependency方法，用于追踪依赖文件的变化。

4. 优化Passthrough文件复制 #

你设置了passthroughFileCopy: true，结合dir.input: './'，这意味着11ty会复制项目根目录下所有非模板文件到_site。在旧版本中，11ty可能会每次都重新复制这些文件，导致它们的修改时间更新。

解决方案：

• 精确指定需要passthrough的目录，而不是全局开启：

  return {
    dir: { input: './', output: './_site' },
    passthroughFileCopy: ['assets', 'images', 'css'] // 只复制需要的静态资源目录
  };
  

• 升级到v1.x后，passthrough文件会自动检查修改时间，只有变化的文件才会被复制。

5. 检查全局数据或Partial的意外修改 #

如果你的_data目录下有全局数据文件，或者_includes中的partial被意外修改（比如编辑器自动保存导致mtime变化），11ty会重新渲染所有依赖这些资源的模板。

可以运行以下命令检查最近修改的文件：

find . -type f -mtime -1h | grep -E "(_data|_includes)"

看看是否有文件被意外更新。

6. 确认缓存目录正常 #

11ty的增量构建依赖.cache目录存储构建缓存，如果这个目录被删除或者权限问题，11ty会触发全量构建。确保.cache目录存在且可读写，不要手动删除它（除非需要强制全量构建）。

内容的提问来源于stack exchange，提问作者Alvaro