symlink()

创建用于将 Vinyl 对象链接到文件系统的流。

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

用法

¥Usage

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

function link() {

return src('input/*.js')

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

}

exports.link = link;

签名

¥Signature

symlink(directory, [options])

参数

¥Parameters

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

返回

¥Returns

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

¥A stream that can be used in the middle or at the end of a pipeline to create symbolic links on the file system. Whenever a Vinyl object is passed through the stream, it creates a symbolic link to the original file on the file system at the given directory.

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

¥Whenever a symbolic link 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 symbolic link.

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

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

• contents 属性将设置为 null。

  ¥The contents property will be set to null.

• symlink 属性将被添加或替换为原始路径。

  ¥The symlink property will be added or replaced with original path.

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

¥Note: On Windows, directory links are created using junctions by default. The useJunctions option disables this behavior.

错误

¥Errors

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

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

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

¥When directory is not a string or function, throws an error with the message, "Invalid symlink() 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() 组合。
dirMode	数字 功能		创建目录时使用的模式。如果未设置，将使用进程模式。
overwrite	布尔 函数	true	如果为 true，则使用相同路径覆盖现有文件。
relativeSymlinks	布尔 函数	false	如果为 false，则创建的任何符号链接都将是绝对的。 注意：如果正在创建连接，则忽略，因为它们必须是绝对的。
useJunctions	布尔 函数	true	此选项仅在 Windows 上相关，在其他地方被忽略。如果为 true，则创建目录符号链接作为连接。详细见下文 Windows 上的符号链接。

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 type 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 '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 when creating a dangling link to a directory. Avoid this scenario.