- Stable
2.0.1
- Beta
3.0.0-beta.1
- Canary
3.0.0-alpha.18
Toggle Menu
5.81s
40.14s
Passthrough File Copy
Contents
如果我们需要把非 Eleventy 模板之类的文件复制到输出目录中的话,可以使用被称为直接复制文件(Passthrough File Copy)的功能。
Configuration API Method
使用 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 目录是被如何处理的
如上所示,直接复制文件(passthrough file copy)所复制的文件路径是相对于项目的根目录(而不是所设置的输入目录)而言的。因此,如果直接复制文件(passthrough file copy)所复制的路径位于输入目录内的话,则输入目录将被剥离。
例如:
input
directory issrc
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 模式匹配
在本例中,我们将所有 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
更改输出目录
除了传入字符串类型的参数,还支持对象作为参数,结构如下:{ "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 模式匹配并指定输出目录
注意,此方式比采用非 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
根据文件扩展名原样复制文件
默认情况下,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"
格式的图片文件上。
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:
module.exports = function (eleventyConfig) {
// the default is "copy"
eleventyConfig.setServerPassthroughCopyBehavior("passthrough");
};
This behavior will revert to "copy"
in your project automatically if:
- If you are running Eleventy without
--serve
(a standard build or via--watch
) - You change from the default development server: Eleventy Dev Server (e.g. swap back to Browsersync)
2.0.0-canary.12
through 2.0.0-canary.30
. It was changed to opt-in in 2.0.0-canary.31
.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:
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.