Skip to navigation Skip to main content
Eleventy
Eleventy Documentation
Blog
11ty is joining Font AwesomeIndieWeb Avatar for https://fontawesome.com/
Versions
Stable
3.0.0
Toggle Menu
Compare npm install
Eleventy 5.81s
Remix 40.14s

Passthrough File Copy

Contents

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

Configuration API Method

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

eleventy.config.js
export default function (eleventyConfig) {
	// Output directory: _site

	// Copy `img/` to `_site/img`
	eleventyConfig.addPassthroughCopy("img");

	// Copy `css/fonts/` to `_site/css/fonts`
	// Keeps the same directory structure.
	eleventyConfig.addPassthroughCopy("css/fonts");

	// Copy any .jpg file to `_site`, via Glob pattern
	// Keeps the same directory structure.
	eleventyConfig.addPassthroughCopy("**/*.jpg");
};
module.exports = function (eleventyConfig) {
	// Output directory: _site

	// Copy `img/` to `_site/img`
	eleventyConfig.addPassthroughCopy("img");

	// Copy `css/fonts/` to `_site/css/fonts`
	// Keeps the same directory structure.
	eleventyConfig.addPassthroughCopy("css/fonts");

	// Copy any .jpg file to `_site`, via Glob pattern
	// Keeps the same directory structure.
	eleventyConfig.addPassthroughCopy("**/*.jpg");
};
INFO:
直接复制文件（Passthrough File Copy）功能所复制的内容是相对于项目更目录的，而 不是 你为 Eleventy 所设置的输入目录（即配置文件中的 input 配置项）。

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

input 目录是被如何处理的

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

例如：

  • input directory is src
  • output directory is _site.

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

eleventy.config.js
export default function (eleventyConfig) {
	// Input directory: src
	// Output directory: _site

	// The following copies to `_site/img`
	eleventyConfig.addPassthroughCopy("src/img");
};
module.exports = function (eleventyConfig) {
	// Input directory: src
	// Output directory: _site

	// The following copies to `_site/img`
	eleventyConfig.addPassthroughCopy("src/img");
};

使用 Glob 模式匹配

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

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

eleventy.config.js
export default function (eleventyConfig) {
	// Find and copy any `jpg` files, maintaining directory structure.
	eleventyConfig.addPassthroughCopy("**/*.jpg");
};
module.exports = function (eleventyConfig) {
	// Find and copy any `jpg` files, maintaining directory structure.
	eleventyConfig.addPassthroughCopy("**/*.jpg");
};

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

  • img/avatar.jpg will copy to _site/img/avatar.jpg
  • subdir/img/avatar.jpg will copy to _site/subdir/img/avatar.jpg

更改输出目录

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

eleventy.config.js
export default 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" });
};
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 模式匹配并指定输出目录

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

eleventy.config.js
export default 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" });
};
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 之后的完整路径如下：

  • img/avatar.jpg would copy to _site/img/avatar.jpg
  • subdir/img/avatar.jpg would copy to _site/img/avatar.jpg

根据文件扩展名原样复制文件

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

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

eleventy.config.js
export default function (eleventyConfig) {
	eleventyConfig.setTemplateFormats([
		"md",
		"css", // css is not yet a recognized template extension in Eleventy
	]);
};
module.exports = function (eleventyConfig) {
	eleventyConfig.setTemplateFormats([
		"md",
		"css", // css is not yet a recognized template extension in Eleventy
	]);
};

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

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

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

Emulate Passthrough Copy During --serve Added in v2.0.0

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:

eleventy.config.js
export default function (eleventyConfig) {
	// the default is "copy"
	eleventyConfig.setServerPassthroughCopyBehavior("passthrough");
};
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

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:

eleventy.config.js
export default function (eleventyConfig) {
	eleventyConfig.addPassthroughCopy("img", {
		expand: true, // expand symbolic links
	});

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

	eleventyConfig.addPassthroughCopy({ img: "subfolder/img" }, {
		debug: true, // log debug information
	});
};

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: