symlink()

创建流以将 Vinyl 对象链接到文件系统。

用法

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

函数 link() {

返回 src('input/*.js')

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

}

exports.link = link;

签名

symlink(directory, [options])

参数

参数	类型	备注
directory (必需)	字符串 函数	将创建符号链接的输出目录的路径。如果使用函数，则将使用每个 Vinyl 对象调用该函数，并且必须返回字符串目录路径。
选项	对象	在下面的 选项 中详细说明。

返回

一个流，可以在管道中间或末尾使用，以便在文件系统上创建符号链接。每当 Vinyl 对象通过流时，它都会在给定目录的文件系统上创建到原始文件的符号链接。

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

• cwd、base 和 path 属性将被更新以匹配创建的符号链接。
• stat 属性将被更新以匹配文件系统上的符号链接。
• contents 属性将被设置为 null。
• symlink 属性将被添加或替换为原始路径。

注意：在 Windows 上，默认情况下使用连接点创建目录链接。useJunctions 选项禁用此行为。

错误

当 directory 为空字符串时，抛出带有消息“无效的 symlink() 文件夹参数。请指定一个非空字符串或函数”的错误。

当 directory 不是字符串或函数时，抛出带有消息“无效的 symlink() 文件夹参数。请指定一个非空字符串或函数”的错误。

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

选项

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

名称	类型	默认值	备注
cwd	字符串 函数	process.cwd()	将与任何相对路径组合以形成绝对路径的目录。对于绝对路径，将忽略此选项。用于避免将 directory 与 path.join() 结合使用。
dirMode	数字 函数		创建目录时使用的模式。如果未设置，将使用进程的模式。
overwrite	布尔值 函数	true	为 true 时，覆盖具有相同路径的现有文件。
relativeSymlinks	布尔值 函数	false	为 false 时，创建的任何符号链接都将是绝对的。 注意：如果正在创建连接点，则忽略，因为它们必须是绝对的。
useJunctions	布尔值 函数	true	此选项仅适用于 Windows，在其他地方会被忽略。为 true 时，将目录符号链接创建为连接点。详见下文的Windows 上的符号链接。

Windows 上的符号链接

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

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

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

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

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