Eleventy(11ty) logo Eleventy
The possum is Eleventy’s mascot
Eleventy 中文文档
Menu
Compare npm install
Eleventy 5.81s
Remix 40.14s

Passthrough File Copy

Contents

如果我们需要把非 Eleventy 模板之类的文件复制到输出目录中的话，可以使用被称为直接复制文件（Passthrough File Copy）的功能。

Configuration API Method Jump to heading

使用 Eleventy 提供的 API 方法来指定需要复制的 文件 或 目录 。

Filename .eleventy.js
Output Directory _site
module.exports = function(eleventyConfig) {
  // 输出目录为： _site

  // 复制 `img/` 到 `_site/img`
  eleventyConfig.addPassthroughCopy("img");

  // 复制 `css/fonts/` 到 `_site/css/fonts`
  // 并保持原始的目录结构。
  eleventyConfig.addPassthroughCopy("css/fonts");

  // 复制所有 .jpg 文件（支持 Glob 模式匹配）到 `_site` 目录，
  // 并保持原始的目录结构。
  eleventyConfig.addPassthroughCopy("**/*.jpg");
};
INFO:
直接复制文件（Passthrough File Copy）功能所复制的内容是相对于项目更目录的，而 不是 你为 Eleventy 所设置的输入目录（即配置文件中的 input 配置项）。

如果不需要保持原始的目录结构的话，可以 改变输出目录。

input 目录是被如何处理的 Jump to heading

如上所示，直接复制文件（passthrough file copy）所复制的文件路径是相对于项目的根目录（而不是所设置的输入目录）而言的。因此，如果直接复制文件（passthrough file copy）所复制的路径位于输入目录内的话，则输入目录将被剥离。

例如：

如果我们使用直接复制文件（passthrough file copy）功能复制 src/img 的话，它将被复制到 _site/img 。

Filename .eleventy.js
Input Directory src
Output Directory _site
module.exports = function(eleventyConfig) {
  // `input` 目录设置为： src
  // `output` 目录设置为： _site

  // 将被复制到 `_site/img`
  eleventyConfig.addPassthroughCopy("src/img");
};

使用 Glob 模式匹配 Jump to heading

在本例中，我们将所有 jpg 图片文件复制到输出目录中，并保持各自原始的目录结构。如果不想保持原始目录结构的话，可以 修改输出目录。

注意，此方法比不使用 glob 模式匹配的方法慢，因为它需要搜索整个目录结构并由 Eleventy 逐个复制文件。

Filename .eleventy.js
module.exports = function(eleventyConfig) {
  // 搜索并复制所有 `jpg` 文件，并保持原始目录结构。
  eleventyConfig.addPassthroughCopy("**/*.jpg");
};

补上输出目录 _site 之后的完整路径如下：

更改输出目录 Jump to heading

除了传入字符串类型的参数，还支持对象作为参数，结构如下：{ "input": "target" }。

Filename .eleventy.js
Input Directory src
Output Directory _site
module.exports = function(eleventyConfig) {
  // Input directory: src
  // Output directory: _site

  // Copy `img/` to `_site/subfolder/img`
  eleventyConfig.addPassthroughCopy({ "img": "subfolder/img" });

  // Copy `src/img/` to `_site/subfolder/img`
  eleventyConfig.addPassthroughCopy({ "src/img": "subfolder/img" });

  // Copy `random-folder/img/` to `_site/subfolder/img`
  eleventyConfig.addPassthroughCopy({ "random-folder/img": "subfolder/img" });
};

使用 Glob 模式匹配并指定输出目录 Jump to heading

注意，此方式比采用非 Glob 模式匹配的方式慢，因为 Eleventy 需要搜索整个目录结构并复制文件。

Filename .eleventy.js
Output Dir _site
module.exports = function(eleventyConfig) {
  // Output directory: _site

  // Find and copy any `jpg` files in any folder to _site/img
  // Does not keep the same directory structure.
  eleventyConfig.addPassthroughCopy({ "**/*.jpg": "img" });
};

补上输出目录 _site 之后的完整路径如下：

根据文件扩展名原样复制文件 Jump to heading

默认情况下，Eleventy 会按照 templateFormats 配置项 所列出的文件扩展名搜索 Input 目录下的所有文件。也就是说，如果你把 njk 扩展名添加到 templateFormats 配置项中的话，我们就可以得到所有 Nunjucks 模板文件了（即文件扩展名为 .njk 的文件）。

如果某个文件格式并未被 Eleventy 当作模板文件，则 Eleventy 将忽略该文件。不过，你可以通添加该文件格式作为模板文件格式，从而改变此行为：

Filename .eleventy.js
module.exports = function(eleventyConfig) {
  eleventyConfig.setTemplateFormats([
    "md",
    "css" // Eleventy 并未把 css 文件当作模板文件格式
  ]);
};

在上述代码示例中，Eleventy 并未把 css 看作模板文件格式，但是 Eleventy 将再 Input 目录中查找所有 *.css 文件并复制到 Output 目录下（同时保持目录结构）。

你或许希望将这种行为模式应用到 "jpg"、"png" 甚至 "webp" 格式的图片文件上。

INFO:
请注意，此方式通常比前面提到的调用 addPassthroughCopy API 的方式慢，尤其是当你的项目很大、有大量文件时。

Emulate Passthrough Copy During --serve Added in v2.0.0 Jump to heading

The Eleventy Dev Server includes a great build-performance feature that will emulate passthrough file copy.

Practically speaking, this means that (during --serve only!) files are referenced directly and will not be copied to your output folder. Changes to passthrough file copies will not trigger an Eleventy build but will live reload appropriately in the dev server.

You can enable this behavior in your project using this configuration API method:

Filename .eleventy.js
module.exports = function(eleventyConfig) {
  // the default is "copy"
  eleventyConfig.setServerPassthroughCopyBehavior("passthrough");
};

This behavior will revert to "copy" in your project automatically if:

  1. If you are running Eleventy without --serve (a standard build or via --watch)
  2. You change from the default development server: Eleventy Dev Server (e.g. swap back to Browsersync)
INFO:
For 2.0 canary users, note that this behavior spent a fair bit of time as the default and required opt-out from 2.0.0-canary.12 through 2.0.0-canary.30. It was changed to opt-in in 2.0.0-canary.31.
Play Video: Emulated Passthrough File Copy (Weekly №15) Emulated Passthrough File Copy (Weekly №15) ▶7m23s

Advanced Options Added in v2.0.0 Jump to heading

Additionally, you can pass additional configuration options to the recursive-copy package. This unlocks the use passthrough file copy with symlinks, transforming or renaming copied files. Here are just a few examples:

Filename .eleventy.js
module.exports = function(eleventyConfig) {
  eleventyConfig.addPassthroughCopy("img", {
    expand: true, // expand symbolic links
  });
};
Filename .eleventy.js
module.exports = function(eleventyConfig) {
  let copyOptions = {
    debug: true, // log debug information
  };

  eleventyConfig.addPassthroughCopy({ "img": "subfolder/img" }, copyOptions);
};

Review the full list of options on the recursive-copy GitHub repository.

Play Video: Passthrough File Copy Advanced Options (Weekly №15) Passthrough File Copy Advanced Options (Weekly №15) ▶5m37s

Other pages in Configuration: