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 = {
  // 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
}

Glob 模式

逐一指定所有來源檔案路徑通常不切實際，因此 Grunt 支援透過內建的 node-glob 函式庫進行檔案名稱擴充 (也稱為 glob)。

請參閱設定工作指南的「Glob 模式」部分，以取得 glob 模式範例。

grunt.file.expand

傳回與給定 glob 模式相符的所有檔案或目錄路徑的唯一陣列。此方法接受以逗號分隔的 glob 模式或 glob 模式陣列。與以 ! 開頭的模式相符的路徑會從傳回的陣列中排除。模式會依序處理，因此包含和排除順序很重要。

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。此檔案路徑可能會根據指定的選項而扁平化或重新命名。請參閱 grunt.file.expand 方法文件，了解如何指定 patterns 和 options 參數。

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 - 檔案 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

Glob 模式

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