dest()

创建用于将 Vinyl 对象写入文件系统的流。

¥Creates a stream for writing Vinyl objects to the file system.

用法

¥Usage

const { src, dest } = require('gulp');

function copy() {

return src('input/*.js')

.pipe(dest('output/'));

}

exports.copy = copy;

签名

¥Signature

dest(directory, [options])

参数

¥Parameters

参数	type	note
目录 (必填)	字符串 函数	将写入文件的输出目录的路径。如果使用函数，则将使用每个 Vinyl 对象调用该函数，并且必须返回字符串目录路径。
options	object	详细见下文 选项。

返回

¥Returns

可以在管道的中间或末端使用的流，以在文件系统上创建文件。每当 Vinyl 对象通过流传递时，它就会将内容和其他详细信息写入给定目录的文件系统中。如果 Vinyl 对象具有 symlink 属性，则会创建符号链接而不是写入内容。文件创建后，其 元数据将被更新 与 Vinyl 对象匹配。

¥A stream that can be used in the middle or at the end of a pipeline to create files on the file system. Whenever a Vinyl object is passed through the stream, it writes the contents and other details out to the file system at the given directory. If the Vinyl object has a symlink property, a symbolic link will be created instead of writing the contents. After the file is created, its metadata will be updated to match the Vinyl object.

每当在文件系统上创建文件时，Vinyl 对象都会被修改。

¥Whenever a file is created on the file system, the Vinyl object will be modified.

• cwd、base 和 path 属性将更新以匹配创建的文件。

  ¥The cwd, base, and path properties will be updated to match the created file.

• stat 属性将更新以匹配文件系统上的文件。

  ¥The stat property will be updated to match the file on the file system.

• 如果 contents 属性是流，它将被重置，以便可以再次读取。

  ¥If the contents property is a stream, it will be reset so it can be read again.

错误

¥Errors

当 directory 为空字符串时，将引发错误并显示消息“无效的 dest() 文件夹参数。请指定一个非空字符串或一个函数。”

¥When directory is an empty string, throws an error with the message, "Invalid dest() folder argument. Please specify a non-empty string or a function."

当 directory 不是字符串或函数时，会引发错误并显示消息“无效的 dest() 文件夹参数。请指定一个非空字符串或一个函数。”

¥When directory is not a string or function, throws an error with the message, "Invalid dest() folder argument. Please specify a non-empty string or a function."

当 directory 是返回空字符串或 undefined 的函数时，会触发错误消息 "输出文件夹无效"。

¥When directory is a function that returns an empty string or undefined, emits an error with the message, "Invalid output folder".

选项

¥Options

对于接受函数的选项，将使用每个 Vinyl 对象调用传递的函数，并且必须返回另一个列出类型的值。

¥For options that accept a function, the passed function will be called with each Vinyl object and must return a value of another listed type.

name	type	default	note
cwd	字符串 函数	process.cwd()	将与任何相对路径组合形成绝对路径的目录。绝对路径被忽略。用于避免将 directory 与 path.join() 组合。
mode	数字 功能	Vinyl 对象的 stat.mode	创建文件时使用的模式。如果未设置且缺少 stat.mode，则将使用进程模式。
dirMode	数字 功能		创建目录时使用的模式。如果未设置，将使用进程模式。
overwrite	布尔 函数	true	如果为 true，则使用相同路径覆盖现有文件。
append	布尔 函数	false	如果为 true，则将内容添加到文件末尾，而不是替换现有内容。
sourcemaps	布尔 字符串 函数	false	如果为 true，则将内联源映射写入输出文件。指定 string 路径将在给定路径写入外部 sourcemaps。
relativeSymlinks	布尔 函数	false	如果为 false，则创建的任何符号链接都将是绝对的。 注意：如果正在创建连接，则忽略，因为它们必须是绝对的。
useJunctions	布尔 函数	true	此选项仅在 Windows 上相关，在其他地方被忽略。如果为 true，则创建目录符号链接作为连接。详细见下文 Windows 上的符号链接。

元数据更新

¥Metadata updates

每当 dest() 流创建文件时，Vinyl 对象的 mode、mtime 和 atime 都会与创建的文件进行比较。如果它们不同，创建的文件将被更新以反映 Vinyl 对象的元数据。如果这些属性相同，或者 gulp 无权进行更改，则会静默跳过该尝试。

¥Whenever the dest() stream creates a file, the Vinyl object's mode, mtime, and atime are compared to the created file. If they differ, the created file will be updated to reflect the Vinyl object's metadata. If those properties are the same, or gulp doesn't have permissions to make changes, the attempt is skipped silently.

此功能在 Windows 或其他不支持 Node 的 process.getuid() 或 process.geteuid() 方法的操作系统上被禁用。这是由于 Windows 通过使用 fs.fchmod() 和 fs.futimes() 产生了意外结果。

¥This functionality is disabled on Windows or other operating systems that don't support Node's process.getuid() or process.geteuid() methods. This is due to Windows having unexpected results through usage of fs.fchmod() and fs.futimes().

注意：fs.futimes() 方法在内部将 mtime 和 atime 时间戳转换为秒。在 32 位操作系统上除以 1000 可能会导致一些精度损失。

¥Note: The fs.futimes() method internally converts mtime and atime timestamps to seconds. This division by 1000 may cause some loss of precision on 32-bit operating systems.

源映射

¥Sourcemaps

Sourcemap 支持直接内置于 src() 和 dest() 中，但默认情况下处于禁用状态。使其能够生成内联或外部源映射。

¥Sourcemap support is built directly into src() and dest(), but it is disabled by default. Enable it to produce inline or external sourcemaps.

内联源映射：

¥Inline sourcemaps:

const { src, dest } = require('gulp');

const uglify = require('gulp-uglify');

src('input/**/*.js', { sourcemaps: true })

.pipe(uglify())

.pipe(dest('output/', { sourcemaps: true }));

外部源映射：

¥External sourcemaps:

const { src, dest } = require('gulp');

const uglify = require('gulp-uglify');

src('input/**/*.js', { sourcemaps: true })

.pipe(uglify())

.pipe(dest('output/', { sourcemaps: '.' }));

Windows 上的符号链接

¥Symbolic links on Windows

在 Windows 上创建符号链接时，会将 type 参数传递给 Node 的 fs.symlink() 方法，该方法指定要链接的目标类型。链接类型设置为：

¥When creating symbolic links on Windows, a type argument is passed to Node's fs.symlink() method which specifies the kind of target being linked. The link type is set to:

• 'file'（当目标是常规文件时）

  ¥'file' when the target is a regular file

• 'junction'（当目标是目录时）

  ¥'junction' when the target is a directory

• 'dir'（当目标是目录且用户禁用 useJunctions 选项时）

  ¥'dir' when the target is a directory and the user disables the useJunctions option

如果你尝试创建悬空（指向不存在的目标）链接，则无法自动确定链接类型。在这些情况下，行为将根据悬空链接是通过 symlink() 还是通过 dest() 创建而有所不同。

¥If you try to create a dangling (pointing to a non-existent target) link, the link type can't be determined automatically. In these cases, behavior will vary depending on whether the dangling link is being created via symlink() or via dest().

对于通过 symlink() 创建的悬空链接，传入的 Vinyl 对象代表目标，因此其统计数据将确定所需的链接类型。如果 isDirectory() 返回 false，则创建 'file' 链接，否则根据 useJunctions 选项的值创建 'junction' 或 'dir' 链接。

¥For dangling links created via symlink(), the incoming Vinyl object represents the target, so its stats will determine the desired link type. If isDirectory() returns false then a 'file' link is created, otherwise a 'junction' or a 'dir' link is created depending on the value of the useJunctions option.

对于通过 dest() 创建的悬空链接，传入的 Vinyl 对象代表链接 - 通常通过 src(..., { resolveSymlinks: false }) 从磁盘加载。在这种情况下，无法合理确定链接类型，默认使用 'file'。如果你要创建目录的悬空链接，这可能会导致意外行为。避免这种情况。

¥For dangling links created via dest(), the incoming Vinyl object represents the link - typically loaded from disk via src(..., { resolveSymlinks: false }). In this case, the link type can't be reasonably determined and defaults to using 'file'. This may cause unexpected behavior if you are creating a dangling link to a directory. Avoid this scenario.