grunt.file

提供了许多用于读取和写入文件、遍历文件系统以及通过匹配通配符模式查找文件的方法。这些方法中的许多是围绕内置的 Node.js 文件功能的包装器，但增加了额外的错误处理、日志记录和字符编码规范化。

注意：除非使用 grunt.file.setBase 或 --base 命令行选项更改了当前工作目录，否则所有文件路径都相对于 Gruntfile。

字符编码

grunt.file.defaultEncoding

设置此属性以更改所有 grunt.file 方法使用的默认编码。默认为 'utf8'。如果确实需要更改此值，建议尽早在 Gruntfile 中更改。

grunt.file.defaultEncoding = 'utf8';

grunt.file.preserveBOM

在 0.4.2 版本中添加

是否在 file.read 时保留字节顺序标记（BOM），而不是去除它。

grunt.file.preserveBOM = false;

读取和写入

grunt.file.read

读取并返回文件的内容。返回一个字符串，除非 options.encoding 为 null，在这种情况下返回一个 Buffer。

grunt.file.read(filepath [, options])

options 对象具有以下可能的属性：

var options = {
  // 如果未指定编码，默认为 grunt.file.defaultEncoding。
  // 如果指定为 null，则返回未解码的 Buffer 而不是字符串。
  encoding: encodingName
};

grunt.file.readJSON

读取文件的内容，将数据解析为 JSON 并返回结果。有关支持的选项，请参见 grunt.file.read。

grunt.file.readJSON(filepath [, options])

grunt.file.readYAML

读取文件的内容，将数据解析为 YAML 并返回结果。有关支持的选项，请参见 grunt.file.read。

grunt.file.readYAML(filepath [, options])

grunt.file.write

将指定内容写入文件，必要时创建中间目录。字符串将使用指定的字符编码进行编码，Buffers 将按指定方式写入磁盘。

如果指定了 --no-write 命令行选项，则文件实际上不会被写入。

grunt.file.write(filepath, contents [, options])

options 对象具有以下可能的属性：

var options = {
  // 如果未指定编码，默认为 grunt.file.defaultEncoding。
  // 如果 `contents` 是 Buffer，则忽略编码。
  encoding: encodingName
};

grunt.file.copy

将源文件复制到目标路径，必要时创建中间目录。

如果指定了 --no-write 命令行选项，则文件实际上不会被写入。

grunt.file.copy(srcpath, destpath [, options])

options 对象具有以下可能的属性：

var options = {
  // 如果未指定编码，默认为 grunt.file.defaultEncoding。
  // 如果为 null，`process` 函数将接收 Buffer 而不是字符串。
  encoding: encodingName,
  // 源文件内容、源文件路径和目标文件路径
  // 传递到此函数，其返回值将用作目标文件的内容。如果此函数返回 `false`，
  // 则文件复制将被中止。
  process: processFunction,
  // 这些可选的通配符模式将与文件路径（而非文件名）匹配
  // 使用 grunt.file.isMatch。如果任何指定的通配符模式匹配，
  // 则文件将不会通过 `process` 函数处理。
  // 如果指定 `true`，则将阻止处理。
  noProcess: globbingPatterns
};

grunt.file.delete

删除指定的文件路径。将递归删除文件和文件夹。

除非指定了 --force 命令行选项，否则不会删除当前工作目录或当前工作目录之外的文件。

如果指定了 --no-write 命令行选项，则文件路径实际上不会被删除。

grunt.file.delete(filepath [, options])

options 对象有一个可能的属性：

var options = {
  // 启用删除当前工作目录之外的文件。此选项可能
  // 被 --force 命令行选项覆盖。
  force: true
};

目录

grunt.file.mkdir

类似于 mkdir -p。创建一个目录以及任何中间目录。如果未指定 mode，则默认为 0777 & (~process.umask())。

如果指定了 --no-write 命令行选项，则目录实际上不会被创建。

grunt.file.mkdir(dirpath [, mode])

grunt.file.recurse

递归进入一个目录，为每个文件执行 callback。

grunt.file.recurse(rootdir, callback)

回调函数接收以下参数：

function callback(abspath, rootdir, subdir, filename) {
  // 当前文件的完整路径，实际上就是
  // rootdir + subdir + filename 参数的连接。
  abspath
  // 最初指定的根目录。
  rootdir
  // 相对于 rootdir 的当前文件目录。
  subdir
  // 当前文件的文件名，不包含任何目录部分。
  filename
}

通配符模式

单独指定所有源文件路径通常是不切实际的，因此 Grunt 通过内置的 node-glob 库支持文件名扩展（也称为通配符）。

有关通配符模式示例，请参见配置任务指南的"通配符模式"部分。

grunt.file.expand

返回与给定通配符模式匹配的所有文件或目录路径的唯一数组。此方法接受逗号分隔的通配符模式或通配符模式数组。以 ! 开头的路径模式将从返回的数组中排除。模式按顺序处理，因此包含和排除的顺序很重要。

grunt.file.expand([options, ] patterns)

文件路径相对于 Gruntfile，除非使用 grunt.file.setBase 或 --base 命令行选项更改了当前工作目录。

options 对象支持所有 minimatch 库 选项，以及一些其他选项。例如：

• filter 可以是有效的 fs.Stats 方法名称，也可以是传递匹配的 src 文件路径并返回 true 或 false 的函数。
• nonull 保留 src 模式，即使它们未能匹配文件。与 Grunt 的 --verbose 标志结合，此选项可帮助调试文件路径问题。
• matchBase 没有斜杠的模式将仅匹配基本名称部分。例如，这使 *.js 的工作方式类似于 **/*.js。
• cwd 模式将相对于此路径匹配，并且所有返回的文件路径也将相对于此路径。

grunt.file.expandMapping

返回 src-dest 文件映射对象的数组。对于每个由指定模式匹配的源文件，将该文件路径连接到指定的 dest。根据指定的选项，此文件路径可能会被展平或重命名。有关如何指定 patterns 和 options 参数的说明，请参见 grunt.file.expand 方法文档。

grunt.file.expandMapping(patterns, dest [, options])

注意，虽然此方法可用于以编程方式为多任务生成 files 数组，但配置任务指南的"动态构建文件对象"部分中描述的声明性语法是首选。

除了 grunt.file.expand 方法支持的选项外，options 对象还支持以下属性：

var options = {
  // 匹配模式的目录。任何指定为
  // cwd 的字符串都将从所有匹配路径的开头有效地剥离。
  cwd: String,
  // 从所有匹配的 src 文件中删除路径组件。src 文件路径
  // 仍然连接到指定的 dest。
  flatten: Boolean,
  // 删除目标路径中（包括）第一个或最后一个 "." 之后的任何内容，
  // 然后附加此值。
  ext: String,
  // *在 0.4.3 版本中添加*
  // 指示分隔扩展名的句号的位置。可以是：
  // - 'first'（扩展名从文件名中的第一个句号之后开始）
  // - 'last'（扩展名从最后一个句号之后开始）
  // 默认：'first'
  extDot: String,
  // 如果指定，此函数将负责返回最终
  // 目标文件路径。默认情况下，它像这样连接 dest 和 matchedSrcPath：
  rename: function(dest, matchedSrcPath, options) {
    return path.join(dest, matchedSrcPath);
  }
};

grunt.file.match

匹配一个或多个通配符模式与一个或多个文件路径。返回与任何指定通配符模式匹配的所有文件路径的唯一数组。patterns 和 filepaths 参数都可以是单个字符串或字符串数组。以 ! 开头的路径模式将从返回的数组中排除。模式按顺序处理，因此包含和排除的顺序很重要。

grunt.file.match([options, ] patterns, filepaths)

options 对象支持所有 minimatch 库 选项。例如，如果 options.matchBase 为 true，没有斜杠的模式将匹配包含斜杠的路径的基本名称，例如，模式 *.js 将匹配文件路径 path/to/file.js。

grunt.file.isMatch

此方法具有与 grunt.file.match 方法相同的签名和逻辑，但简单地返回 true（如果匹配了任何文件），否则返回 false。

File types

grunt.file.exists

给定路径是否存在？返回一个布尔值。

类似于 Node.js path.join 方法，此方法将连接所有参数并规范化结果路径。

grunt.file.exists(path1 [, path2 [, ...]])

grunt.file.isLink

给定路径是否是符号链接？返回一个布尔值。

类似于 Node.js path.join 方法，此方法将连接所有参数并规范化结果路径。

grunt.file.isLink(path1 [, path2 [, ...]])

如果路径不存在，则返回 false。

grunt.file.isDir

给定路径是否是目录？返回一个布尔值。

类似于 Node.js path.join 方法，此方法将连接所有参数并规范化结果路径。

grunt.file.isDir(path1 [, path2 [, ...]])

如果路径不存在，则返回 false。

grunt.file.isFile

给定路径是否是文件？返回一个布尔值。

类似于 Node.js path.join 方法，此方法将连接所有参数并规范化结果路径。

grunt.file.isFile(path1 [, path2 [, ...]])

如果路径不存在，则返回 false。

Paths

grunt.file.isPathAbsolute

给定的文件路径是否是绝对路径？返回一个布尔值。

类似于 Node.js path.join 方法，此方法将连接所有参数并规范化结果路径。

grunt.file.isPathAbsolute(path1 [, path2 [, ...]])

grunt.file.arePathsEquivalent

指定的所有路径是否引用同一路径？返回一个布尔值。

grunt.file.arePathsEquivalent(path1 [, path2 [, ...]])

grunt.file.doesPathContain

指定的祖先路径是否包含所有后代路径？返回一个布尔值。

注意：不检查路径是否实际存在。

grunt.file.doesPathContain(ancestorPath, descendantPath1 [, descendantPath2 [, ...]])

grunt.file.isPathCwd

给定的文件路径是否是当前工作目录（CWD）？返回一个布尔值。

类似于 Node.js path.join 方法，此方法将连接所有参数并规范化结果路径。

grunt.file.isPathCwd(path1 [, path2 [, ...]])

grunt.file.isPathInCwd

给定的文件路径是否在当前工作目录（CWD）内？注意：CWD 不在 CWD 内。返回一个布尔值。

类似于 Node.js path.join 方法，此方法将连接所有参数并规范化结果路径。

grunt.file.isPathInCwd(path1 [, path2 [, ...]])

grunt.file.setBase

更改 Grunt 的当前工作目录（CWD）。默认情况下，所有文件路径都相对于 Gruntfile。这与 --base 命令行选项的工作方式相同。

grunt.file.setBase(path1 [, path2 [, ...]])

类似于 Node.js path.join 方法，此方法将连接所有参数并规范化结果路径。

External libraries

已弃用

下面列出的所有外部库现在都已弃用。

请使用 npm 管理项目依赖中的这些外部库。

例如，如果要使用 Lo-Dash，请先安装 npm install lodash，然后在 Gruntfile 中使用：var _ = require('lodash');

grunt.file.glob

已弃用

glob - 文件通配符实用工具。

grunt.file.minimatch

已弃用

minimatch - 文件模式匹配实用工具。

grunt.file.findup

已弃用

findup-sync - 向上搜索匹配的文件模式。