grunt.file

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

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

字符编码

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 = {
  // If an encoding is not specified, default to grunt.file.defaultEncoding.
  // If specified as null, returns a non-decoded Buffer instead of a string.
  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

将指定内容写入文件，如有必要，创建中间目录。字符串将使用指定的字符编码进行编码，Buffer 将按原样写入磁盘。

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

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

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

var options = {
  // If an encoding is not specified, default to grunt.file.defaultEncoding.
  // If `contents` is a Buffer, encoding is ignored.
  encoding: encodingName
};

grunt.file.copy

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

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

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

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

var options = {
  // If an encoding is not specified, default to grunt.file.defaultEncoding.
  // If null, the `process` function will receive a Buffer instead of String.
  encoding: encodingName,
  // The source file contents, source file path, and destination file path
  // are passed into this function, whose return value will be used as the
  // destination file's contents. If this function returns `false`, the file
  // copy will be aborted.
  process: processFunction,
  // These optional globbing patterns will be matched against the filepath
  // (not the filename) using grunt.file.isMatch. If any specified globbing
  // pattern matches, the file won't be processed via the `process` function.
  // If `true` is specified, processing will be prevented.
  noProcess: globbingPatterns
};

grunt.file.delete

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

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

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

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

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

var options = {
  // Enable deleting outside the current working directory. This option may
  // be overridden by the --force command-line option.
  force: true
};

function callback(abspath, rootdir, subdir, filename) {
  // The full path to the current file, which is nothing more than
  // the rootdir + subdir + filename arguments, joined.
  abspath
  // The root director, as originally specified.
  rootdir
  // The current file's directory, relative to rootdir.
  subdir
  // The filename of the current file, without any directory parts.
  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 = {
  // The directory from which patterns are matched. Any string specified as
  // cwd is effectively stripped from the beginning of all matched paths.
  cwd: String,
  // Remove the path component from all matched src files. The src file path
  // is still joined to the specified dest.
  flatten: Boolean,
  // Remove anything after (and including) either the first or last "." in the
  // destination path (indicated by options.extDot), then append this value.
  ext: String,
  // *Added in 0.4.3*
  // Indicates where the period demarcating the extension is located. Can take:
  // - 'first' (extension begins after the first period in the file name)
  // - 'last' (extension begins after the last period)
  // Default: 'first'
  extDot: String,
  // If specified, this function will be responsible for returning the final
  // dest filepath. By default, it joins dest and matchedSrcPath like so:
  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。

文件类型

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。

路径

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 方法类似，此方法将所有参数连接在一起并规范化生成的路径。

外部库

已弃用

以下列出的所有外部库现已弃用。

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

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

grunt.file.glob

已弃用

glob - 文件通配符实用程序。

grunt.file.minimatch

已弃用

minimatch - 文件模式匹配实用程序。

grunt.file.findup

已弃用

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

在文档中发现错误？提交问题。

grunt.file

字符编码

grunt.file.defaultEncoding

grunt.file.preserveBOM

读取和写入

grunt.file.read

grunt.file.readJSON

grunt.file.readYAML

grunt.file.write

grunt.file.copy

grunt.file.delete

目录

grunt.file.mkdir

grunt.file.recurse

通配符模式

grunt.file.expand

grunt.file.expandMapping

grunt.file.match

grunt.file.isMatch

文件类型

grunt.file.exists

grunt.file.isLink

grunt.file.isDir

grunt.file.isFile

路径

grunt.file.isPathAbsolute

grunt.file.arePathsEquivalent

grunt.file.doesPathContain

grunt.file.isPathCwd

grunt.file.isPathInCwd

grunt.file.setBase

外部库

grunt.file.glob

grunt.file.minimatch

grunt.file.findup