Passthrough File Copy

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

Configuration API Method Jump to heading #

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

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");
};

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

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

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

例如：

• input directory is src
• output directory is _site.

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

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

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

使用 Glob 模式匹配 Jump to heading #

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

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

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

更改输出目录 Jump to heading #

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

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 需要搜索整个目录结构并复制文件。

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

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

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

如果某个文件格式并未被 Eleventy 当作模板文件，则 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" 格式的图片文件上。

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:

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)

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:

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

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.

Other pages in Configuration:

• Passthrough File Copy
• Ignore Files
• Filters
  • url
  • slugify
  • log
  • get*CollectionItem
  • inputPathToUrl
• 快捷码（Shortcodes）
• Custom Tags
• Events
• Transforms
• Watch and Serve
  • Eleventy Dev Server
  • Browsersync
  • Vite