Getting started

新手入门

概述

Grunt 和 Grunt 插件是通过 npm（Node.js 的包管理器）安装和管理的。

Grunt 0.4.x 要求 Node.js 稳定版本 >= 0.8.0。

在设置 Grunt 之前，请确保通过运行 npm update -g npm 更新您的 npm（在某些系统上可能需要 sudo）。

如果您已经安装了 Grunt 并正在寻找快速参考，请查看我们的 Gruntfile 示例和如何配置任务。

安装 CLI

使用 Grunt 0.3？请查看 Grunt 0.3 注意事项

要开始，您需要全局安装 Grunt 的命令行界面（CLI）。您可能需要使用 sudo（对于 OSX、*nix、BSD 等）或以管理员身份运行命令行（对于 Windows）来执行此操作。

npm install -g grunt-cli

这将把 grunt 命令放入您的系统路径，允许从任何目录运行它。

请注意，安装 grunt-cli 并不会安装 Grunt 任务运行器！Grunt CLI 的工作很简单：运行安装在 Gruntfile 旁边的 Grunt 版本。

这允许在同一台机器上同时安装多个版本的 Grunt。

CLI 的工作原理

每次运行 grunt 时，它都会使用 Node 的 require() 系统查找本地安装的 Grunt。正因如此，您可以从项目的任何子文件夹运行 grunt。

如果找到本地安装的 Grunt，CLI 将加载 Grunt 库的本地安装，应用 Gruntfile 中的配置，并执行您请求运行的任何任务。要真正理解正在发生的事情，请阅读代码。

使用现有的 Grunt 项目

假设已安装 Grunt CLI 并且项目已使用 package.json 和 Gruntfile 配置，那么开始使用 Grunt 非常简单：

切换到项目的根目录。
使用 npm install 安装项目依赖。
使用 grunt 运行 Grunt。

就是这样。已安装的 Grunt 任务可以通过运行 grunt --help 列出，但通常最好从项目文档开始。

准备新的 Grunt 项目

典型的设置将涉及向您的项目添加两个文件：package.json 和 Gruntfile。

package.json：这个文件由 npm 用于存储作为 npm 模块发布的项目的元数据。您将在此文件中列出项目需要的 grunt 和 Grunt 插件作为 devDependencies。

Gruntfile：这个文件被命名为 Gruntfile.js 或 Gruntfile.coffee，用于配置或定义任务和加载 Grunt 插件。 当本文档提到 Gruntfile 时，它指的是 Gruntfile.js 或 Gruntfile.coffee 文件。

package.json

package.json 文件应位于项目的根目录，与 Gruntfile 放在一起，并应与项目源代码一起提交。在与 package.json 文件相同的文件夹中运行 npm install 将安装 package.json 中列出的每个依赖的正确版本。

有几种方法可以为您的项目创建 package.json 文件：

大多数 grunt-init 模板将自动创建特定于项目的 package.json 文件。
npm init 命令将创建一个基本的 package.json 文件。
从下面的示例开始，并根据规范进行扩展。

{
  "name": "my-project-name",
  "version": "0.1.0",
  "devDependencies": {
    "grunt": "~0.4.5",
    "grunt-contrib-jshint": "~0.10.0",
    "grunt-contrib-nodeunit": "~0.4.1",
    "grunt-contrib-uglify": "~0.5.0"
  }
}

安装 Grunt 和 Grunt 插件

使用命令 npm install <module> --save-dev 是在现有 package.json 中添加 Grunt 和 Grunt 插件的最简单方法。不仅会在本地安装 <module>，还会自动将其添加到 devDependencies 部分，使用 [波浪号版本范围]。

例如，以下命令将在您的项目文件夹中安装最新版本的 Grunt，并将其添加到 devDependencies：

npm install grunt --save-dev

对于 Grunt 插件和其他 node 模块也是如此。例如，安装 JSHint 任务模块：

npm install grunt-contrib-jshint --save-dev

查看插件页面，了解可以安装和在项目中使用的当前可用的 Grunt 插件。

完成后，请务必提交更新后的 package.json 文件！

Gruntfile

Gruntfile.js 或 Gruntfile.coffee 文件是一个有效的 JavaScript 或 CoffeeScript 文件，属于项目的根目录，位于 package.json 文件旁边，并应与项目源代码一起提交。

Gruntfile 由以下部分组成：

"包装器"函数
项目和任务配置
加载 Grunt 插件和任务
自定义任务

Gruntfile 示例

在下面的 Gruntfile 中，项目元数据从项目的 package.json 文件导入到 Grunt 配置中，grunt-contrib-uglify 插件的 uglify 任务配置为压缩源文件并使用该元数据动态生成横幅注释。当在命令行运行 grunt 时，默认情况下将运行 uglify 任务。

module.exports = function(grunt) {

  // 项目配置。
  grunt.initConfig({
    pkg: grunt.file.readJSON('package.json'),
    uglify: {
      options: {
        banner: '/*! <%= pkg.name %> <%= grunt.template.today("yyyy-mm-dd") %> */\n'
      },
      build: {
        src: 'src/<%= pkg.name %>.js',
        dest: 'build/<%= pkg.name %>.min.js'
      }
    }
  });

  // 加载提供 "uglify" 任务的插件。
  grunt.loadNpmTasks('grunt-contrib-uglify');

  // 默认任务。
  grunt.registerTask('default', ['uglify']);

};

现在您已经看到了整个 Gruntfile，让我们看看它的组成部分。

"包装器"函数

每个 Gruntfile（和 Grunt 插件）使用这个基本格式，您的所有 Grunt 代码必须在此函数内指定：

module.exports = function(grunt) {
  // 在这里执行与 Grunt 相关的操作
};

项目和任务配置

大多数 Grunt 任务依赖于在传递给 grunt.initConfig 方法的对象中定义的配置数据。

在这个示例中，grunt.file.readJSON('package.json') 导入了存储在 package.json 中的 JSON 元数据到 grunt 配置中。因为 <% %> 模板字符串可以引用任何配置属性，所以像文件路径和文件列表这样的配置数据可以通过这种方式指定，以减少重复。

您可以在配置对象中存储任意数据，只要它不与任务所需的属性冲突，它就会被忽略。另外，因为这是 JavaScript，您不仅限于 JSON；您可以在此处使用任何有效的 JS。如果需要，您甚至可以以编程方式生成配置。

与大多数任务一样，grunt-contrib-uglify 插件的 uglify 任务希望其配置在同名属性中指定。在这里，指定了 banner 选项，以及一个名为 build 的单一 uglify 目标，该目标将单个源文件压缩到单个目标文件。

// 项目配置。
grunt.initConfig({
  pkg: grunt.file.readJSON('package.json'),
  uglify: {
    options: {
      banner: '/*! <%= pkg.name %> <%= grunt.template.today("yyyy-mm-dd") %> */\n'
    },
    build: {
      src: 'src/<%= pkg.name %>.js',
      dest: 'build/<%= pkg.name %>.min.js'
    }
  }
});

加载 Grunt 插件和任务

许多常用任务（如连接、压缩和代码检查）作为 Grunt 插件提供。只要在 package.json 中将插件指定为依赖项，并通过 npm install 安装，就可以在 Gruntfile 中使用简单的命令启用：

// 加载提供 "uglify" 任务的插件。
grunt.loadNpmTasks('grunt-contrib-uglify');

注意：grunt --help 命令将列出所有可用任务。

自定义任务

您可以通过定义默认任务来配置 Grunt 运行一个或多个任务。在下面的示例中，在命令行中运行 grunt 而不指定特定任务将运行 uglify 任务。这在功能上与显式运行 grunt uglify 或 grunt default 相同。

// 默认任务。
grunt.registerTask('default', ['uglify']);

如果您的项目需要不由 Grunt 插件提供的任务，您可以在 Gruntfile 中直接定义自定义任务。例如，这个 Gruntfile 定义了一个完全自定义的 default 任务，甚至不使用任务配置：

module.exports = function(grunt) {

  // 一个非常基本的默认任务。
  grunt.registerTask('default', '记录一些内容。', function() {
    grunt.log.write('正在记录一些内容...').ok();
  });

};

自定义项目特定任务不需要在 Gruntfile 中定义；它们可以在外部 .js 文件中定义，并通过 grunt.loadTasks 方法加载。

进一步阅读

Installing grunt 指南详细介绍了安装特定的、生产或开发中的 Grunt 和 grunt-cli 版本。
Configuring Tasks 指南深入解释了如何在 Gruntfile 中配置任务、目标、选项和文件，以及模板、通配符模式和导入外部数据的解释。
Creating Tasks 指南列出了 Grunt 任务类型之间的差异，并展示了一些示例任务和配置。
有关编写自定义任务或 Grunt 插件的更多信息，请查看开发者文档。

Found an error in the documentation? File an issue.