从 0.3 升级到 0.4

请注意，即使您熟悉 grunt，也值得阅读新的 入门指南。

Grunt 现在分为三个部分：grunt、grunt-cli 和 grunt-init。

1. npm 模块 grunt 应该安装到您的项目本地。它包含运行任务、加载插件等的代码和逻辑。
2. npm 模块 grunt-cli 应该全局安装。它将 grunt 命令添加到您的 PATH 中，以便您可以在任何地方执行它。它本身不做任何事情；它的工作是加载并运行已安装到您项目本地的 Grunt，而不管版本如何。有关此更改原因的更多信息，请阅读 npm 1.0：全局安装与本地安装。
3. init 任务已被拆分为其自己的 npm 模块 grunt-init。它应该使用 npm install -g grunt-init 全局安装，并使用 grunt-init 命令运行。在接下来的几个月里，Yeoman 将完全取代 grunt-init。有关更多信息，请参阅 grunt-init 项目页面。

Grunt 0.3 说明

如果您从 Grunt 0.3 升级，请确保卸载全局 grunt

npm uninstall -g grunt

请注意，对于 0.3.x 版本，插件名称和任务配置选项可能与“Gruntfile”部分中显示的不同。

此文件在 0.3.x 版本的 Grunt 中名为 grunt.js。

预先存在任务和插件

所有 grunt-contrib-* 系列插件都已准备好用于 Grunt 0.4。但是，为 Grunt 0.3 编写的第三方插件在更新之前不太可能继续与 0.4 一起使用。我们正在积极与插件作者合作，以确保这种情况尽快发生。

即将发布的 Grunt 版本将专注于解耦 grunt 的架构，以便插件不会受到未来更新的影响。

要求

• Grunt 现在需要 Node.js 版本 >= 0.8.0

Gruntfile

• “Gruntfile”已从 grunt.js 更改为 Gruntfile.js。
• 您的 Gruntfile.coffee 项目 Gruntfile 或 *.coffee 任务文件支持 CoffeeScript（自动转换为 JS）。

有关更多信息，请参阅 入门指南 的“Gruntfile”部分。

核心任务现在是 Grunt 插件

Grunt 0.3 中包含的八个核心任务现在是独立的 Grunt 插件。每个都是一个离散的 npm 模块，必须按照 入门指南 的“加载 Grunt 插件和任务”部分安装为插件。

• concat → grunt-contrib-concat 插件
• init → 独立的 grunt-init 实用程序
• lint → grunt-contrib-jshint 插件
• min → grunt-contrib-uglify 插件
• qunit → grunt-contrib-qunit 插件
• server → grunt-contrib-connect 插件
• test → grunt-contrib-nodeunit 插件
• watch → grunt-contrib-watch 插件

某些任务名称和选项已更改。请务必查看上面链接的每个插件的文档以获取最新的配置详细信息。

配置

Grunt 0.4 任务的配置格式已标准化并得到极大增强。有关更多信息，请参阅 配置任务 指南以及各个插件文档。

• 文件通配符（通配符）模式现在可以被否定以排除匹配的文件。
• 任务现在支持标准的 options 对象。
• 任务现在支持标准的 files 对象。

在 Gruntfile 中指定为配置数据的 <% %> 样式模板字符串会自动扩展，有关更多信息，请参阅 grunt.template 文档。

指令已被删除，但它们的功能已被保留。可以进行以下替换

• '<config:prop.subprop>' → '<%= prop.subprop %>'
• '<json:file.json>' → grunt.file.readJSON('file.json')
• '<file_template:file.js>' → grunt.template.process(grunt.file.read('file.js'))

现在不是使用 '<banner>' 或 '<banner:prop.subprop>' 在文件列表中指定横幅，而是 grunt-contrib-concat 和 grunt-contrib-uglify 插件都有一个 banner 选项。

现在不是使用 '<file_strip_banner:file.js>' 从文件中单独剥离横幅，而是 grunt-contrib-concat 和 grunt-contrib-uglify 插件都有一个选项来剥离/保留横幅。

别名任务更改

指定别名任务时，现在必须将要运行的任务列表指定为数组。

// v0.3.x (old format)
grunt.registerTask('default', 'jshint nodeunit concat');
// v0.4.x (new format)
grunt.registerTask('default', ['jshint', 'nodeunit', 'concat']);

任务参数现在可以包含空格

上述别名任务更改（任务列表必须指定为数组）使这成为可能。只需确保在命令行上指定包含空格的任务参数时用引号将其括起来，以便可以正确解析它们。

grunt my-task:argument-without-spaces "other-task:argument with spaces"

字符编码

添加了 file.defaultEncoding 方法来规范字符编码，并且所有 grunt.file 方法都已更新以支持指定的编码。

助手

Grunt 的助手系统已被删除，取而代之的是 node require。有关如何在 Grunt 插件之间共享功能的简洁示例，请参阅 grunt-lib-legacyhelpers。鼓励插件作者升级他们的插件。

API

Grunt API 从 0.3 到 0.4 发生了重大变化。

• grunt
  • 删除了 grunt.registerHelper 和 grunt.renameHelper 方法。
• grunt.config
  • 更改了 config.get 方法以自动递归扩展 <% %> 模板。
  • 添加了 config.getRaw 方法，该方法将检索原始（未扩展的）配置数据。
  • 更改了 config.process 方法，现在可以像从配置中检索值一样处理值，递归地扩展模板。此方法在 config.get 内部调用，但*不在* config.getRaw 内部调用。
• 添加了 grunt.event，以便任务可以发出事件。
• grunt.fail
  • 如果指定了 --no-color 选项，则不会发出哔声。
  • 添加了 fail.code 退出代码映射。
  • 删除了 fail.warnAlternate 方法。
• grunt.file
  • 不再从 ~/.grunt/tasks/ 目录自动加载任务（将它们安装到您的项目本地！）。
  • 添加了 file.defaultEncoding 方法，用于规范所有 grunt.file 方法的字符编码。
  • 添加了 file.delete 方法。
  • 添加了相对不言自明的 file.exists、file.isDir、file.isFile、file.isLink、file.isPathCwd、file.isPathInCwd、file.doesPathContain、file.arePathsEquivalent 测试方法。
  • 添加了 file.match 和 file.isMatch 方法，以方便将通配符模式与文件路径进行匹配。
  • 添加了 file.expandMapping 方法，用于生成 1 对 1 的源目标文件映射。
  • 添加了 file.readYAML 方法。
  • 更改了 file.findup 以使用 findup-sync 模块。
  • 更改了 file.glob 以使用 glob 模块。
  • 添加了 file.minimatch，它公开了 minimatch 模块。
  • 删除了 file.userDir 方法（移至 grunt-init）。
  • 删除了 file.clearRequireCache 方法。
  • 删除了 file.expandFiles 和 file.expandDirs 方法，请改用 file.expand 的 filter 选项。
  • 删除了 file.expandFileURLs 方法。不要指定应该指定文件的 URL（例如，qunit 任务现在允许使用 urls 选项）。
• grunt.task
  • 使用 task.registerTask 和 task.registerMultiTask 注册的任务都获得了一个 this.options 方法。
  • 添加了 task.normalizeMultiTaskFiles 方法，以方便将多任务 files 对象规范化为 this.file 属性。
  • 删除了 task.registerHelper 和 task.renameHelper 方法。
  • 删除了 task.searchDirs 属性。
  • 删除了 task.expand task.expandDirs task.expandFiles task.getFile task.readDefaults 方法（移至 grunt-init）。
• grunt.package 反映了 grunt 的 package.json 中存储的元数据。
• grunt.version 是 Grunt 的当前版本，以字符串形式表示。
• grunt.template
  • 添加了 template.addDelimiters 方法来添加新的模板分隔符。
  • 添加了 template.setDelimiters 方法来选择模板分隔符。
  • init 和 user 模板分隔符已被删除，但如果需要，您可以使用 template.addDelimiters 再次添加它们（grunt-init 使用它来启用 {% %} 模板分隔符）。
• grunt.util 替换了现在已删除的 grunt.utils。
  • 更改了 util._ 以使用 Lo-Dash
  • 添加了 util.callbackify 方法。
  • 更改了 util.spawn 方法，使其行为更加规范，并将更一致的参数传递给其回调。

任务/插件作者

插件作者，请在您的存储库 README 上清楚地注明您的 Grunt 插件的哪个版本号破坏了与 Grunt 0.3 的兼容性。

任务

• 多任务
  • 现在可以在 files 对象中的每个目标指定多个源目标文件映射（这是可选的）。
• this.files / grunt.task.current.files
  • this.files 属性是一个源目标文件映射对象数组，将在您的多任务中对其进行迭代。它始终是一个数组，即使最常见的用例是指定单个文件，您也应该始终对其进行迭代。
  • 每个源目标文件映射对象都有一个 src 和 dest 属性（可能还有其他属性，具体取决于用户指定的属性）。src 属性已经从用户可能指定的任何 glob 模式中扩展。
• this.filesSrc / grunt.task.current.filesSrc
  • this.filesSrc 属性是由所有指定的 src 属性匹配的所有文件的简化、唯一数组。对只读任务很有用。
• this.options / grunt.task.current.options
  • this.options 方法可以在任务中用于规范化选项。在任务内部，您可以指定选项默认值，例如：var options = this.options({option: 'defaultvalue', ...});

插件

• 已经为与 Grunt 0.4 兼容的插件创建了一个更新的 gruntplugin 模板，并且可以在独立的 grunt-init 中使用。

故障排除

• 如果您之前安装过 Grunt 0.4 的开发版本或任何 grunt-contrib 插件，请务必先使用 npm cache clean 清理您的 npm 缓存，以确保您正在获取 Grunt 和 grunt-contrib 插件的最终版本。