dest()

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

使用方法

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

function copy() {
  return src('input/*.js')
    .pipe(dest('output/'));
}

exports.copy = copy;

签名

dest(directory, [options])

参数

参数	类型	说明
directory (必填)	string function	将要写入文件的输出目录路径。如果使用函数，则会对每个 Vinyl 对象调用该函数，函数必须返回一个字符串形式的目录路径。
options	object	详细信息请参见下方的选项。

返回值

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

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

• cwd、base 和 path 属性将更新以匹配创建的文件。
• stat 属性将更新以匹配文件系统上的文件。
• 如果 contents 属性是流，它将被重置，以便可以再次读取。

错误

当 directory 为空字符串时，抛出错误，错误信息为"Invalid dest() folder argument. Please specify a non-empty string or a function."（无效的 dest() 文件夹参数。请指定非空字符串或函数。）

当 directory 不是字符串或函数时，抛出错误，错误信息为"Invalid dest() folder argument. Please specify a non-empty string or a function."（无效的 dest() 文件夹参数。请指定非空字符串或函数。）

当 directory 是一个返回空字符串或 undefined 的函数时，发出错误，错误信息为"Invalid output folder"（无效的输出文件夹）。

选项

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

名称	类型	默认值	说明
cwd	string function	process.cwd()	将与任何相对路径组合形成绝对路径的目录。对于绝对路径会被忽略。用于避免将 directory 与 path.join() 组合。
mode	number function	Vinyl 对象的 stat.mode	创建文件时使用的模式。如果未设置且 stat.mode 缺失，将使用进程的模式。
dirMode	number function		创建目录时使用的模式。如果未设置，将使用进程的模式。
overwrite	boolean function	true	当为 true 时，覆盖具有相同路径的现有文件。
append	boolean function	false	如果为 true，将内容添加到文件末尾，而不是替换现有内容。
sourcemaps	boolean string function	false	如果为 true，将内联 sourcemaps 写入输出文件。指定 string 路径将在给定路径写入外部 sourcemaps。
relativeSymlinks	boolean function	false	当为 false 时，创建的任何符号链接将是绝对路径。 注意：如果正在创建的是联结点（junction），则忽略此选项，因为联结点必须是绝对路径。
useJunctions	boolean function	true	此选项仅在 Windows 上相关，在其他地方被忽略。当为 true 时，将目录符号链接创建为联结点。详情见下方 Windows 上的符号链接。

元数据更新

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

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

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

Sourcemaps

Sourcemap 支持直接内置于 src() 和 dest() 中，但默认情况下是禁用的。启用它以生成内联或外部 sourcemaps。

内联 sourcemaps：

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

src('input/**/*.js', { sourcemaps: true })
  .pipe(uglify())
  .pipe(dest('output/', { sourcemaps: true }));

外部 sourcemaps：

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

src('input/**/*.js', { sourcemaps: true })
  .pipe(uglify())
  .pipe(dest('output/', { sourcemaps: '.' }));

Windows 上的符号链接

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

• 当目标是常规文件时为 'file'
• 当目标是目录时为 'junction'
• 当目标是目录且用户禁用了 useJunctions 选项时为 'dir'

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

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

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