Grunt 入门 Getting Started


29 March 2013

原文:https://github.com/gruntjs/grunt/wiki/Getting-started

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

这些说明为 Grunt 0.4.x 而写,但是对于 Grunt 0.3.x 仍然有效。只需要注意 0.3.x 的插件名称和任务配置选项可能与“The Gruntfile”一节所述不同。

Grunt 0.4x 要求 Node.js 的版本 >= 0.8.0

1. 安装 CLI

如果已经全局安装了 Grunt,需要先删除它:

npm uninstall -g grunt

为了开始使用 Grunt,需要全局安装 Grunt 的命令行接口。你可能需要使用指令 sudo(OSX、*nix、BSD 等),或者以管理员身份运行命令解释程序来做到这一点。

npm install -g grunt-cli

这将把 grunt 放入系统路径中,使得可以从任意目录运行它。

注意:安装 grunt-cli 并不会安装 grunt!CLI 的工作很简单:运行已安装的与 Gruntfile 紧挨着的 grunt 版本。这样可以在一台机器上同时安装多个版本的 grunt。

2. CLI 是如何工作的

每次 grunt 被运行时,它会使用 node 的 require() 系统寻找一个本地安装的 grunt。正因为如此,你可以在项目的任意子文件夹中运行 grunt

如果找到了本地安装的 Grunt,CLI 会加载它,并且应用 Gruntfile 中的配置,然后执行所要求的所有任务。

要了解真正发生了什么,读读这段代码,很短的。

3. 用现有的 grunt 项目工作

假设 Grunt CLI 已经被安装,并且项目已经配置了 package.jsonGruntfile,那么很容易使用 Grunt 开始工作:

  1. 切换到项目的根目录。
  2. 使用 `npm install` 安装项目的依赖库。
  3. 使用 `grunt` 运行 Grunt。

这就是所要做的所有工作。安装的 Grunt 任务可以通过运行 grunt --help 罗列出来,通常这也是一个好主意:从项目的文档开始。

4. 准备一个新的 grunt 项目

一次典型的安装会涉及添加两个文件到你的项目中:package.jsonGruntfile

package.json:该文件被 npm 用来存储被发布为 npm 模块的项目的元数据。你将在该文件的 devDependencies 中列出项目所依赖的 grunt 和插件。

该文件用来存储 npm 模块的元数据,通过 devDependencies 列出项目依赖的 grunt 和插件。

Gruntfile:该文件被命名为 Gruntfile.jsGruntfile.coffee,被用于配置或定义任务、加载 Grunt 插件。

在 Grunt 0.3.x 版本中,该文件被命名为 grunt.js

5. package.json

文件 package.json 为了项目的根目录,紧挨着 Gruntfile,并且应该随项目源码一起提交。在文件 package.json 的同级目录下运行 npm install 将安装其中列出的每个依赖模块。

有几种方式为你的项目创建一个 package.json 文件:

  • 大部分 grunt-init 模板会自动创建一个项目特定的 package.json 文件。
  • npm init 命令会创建一个基本的 package.json 文件。
  • 从下面的例子开始,需要时扩展,遵循这个规范
{
  "name": "my-project-name",
  "version": "0.1.0",
  "devDependencies": {
    "grunt": "~0.4.1",
    "grunt-contrib-jshint": "~0.1.1",
    "grunt-contrib-nodeunit": "~0.1.2"
  }
}

5.1 安装 Grunt 和 插件

向一个已存在的 package.json 添加 Grunt 和插件的最简单的方式是使用命令 npm install <module> --save-dev。不仅会本地安装 <module>,还会被自动添加到 devDependencies,使用波浪号版本范围

下面的例子将安装最新版本的 Grunt 到你的项目文件夹中,并且添加到你的 devDependencies:

npm install grunt --save-dev

Grunt 插件和其他 node 模块同样可以这么做。当你完成后,请务必提供更新后的 package.json

6. Gruntfile

文件 Gruntfile.jsGruntfile.coffee 是一个有效的 JavaScript 或 CoffeeScript 文件,位于项目的更目录中,紧挨着文件 package.json,并且应该随你的项目源码一起提交。该文件在 Grunt 0.3.x 版本中被命名为 grunt.js

一个 Gruntfile 文件由以下几部分组成:

  • 包裹函数
  • 项目和任务配置
  • 加载 grunt 插件和任务
  • 自定义任务

6.1 Gruntfile 示例

在下面的 Gruntfile 文件中,项目元数据被从项目的 package.json 文件导入到 grunt 配置,并且插件 grunt-contrib-uglify 的任务 uglify 被配置为压缩一个源文件,并且使用元数据动态生成一个标题注释。当通过命令行运行 gurnt 时,任务 uglify 默认被运行。

module.exports = function(grunt) {
  // Project configuration.
  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'
      }
    }
  });
  // Load the plugin that provides the "uglify" task.
  grunt.loadNpmTasks('grunt-contrib-uglify');
  // Default task(s).
  grunt.registerTask('default', ['uglify']);
};

现在你已经看到了完整的 Gruntfile,让我们看看它的组成部分。

6.2 包裹函数

每个 Gruntfile(和 Grunt 插件)使用这个基本格式,所有的 Grunt 代码必须被指定在这个函数内:

module.exports = function(grunt) {
  // Do grunt-related things in here
};

6.3 项目和任务配置

大部分 Grunt 任务依赖于传给方法 grunt.initConfig 的配置对象。

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

你可以在配置对象中存储任意数据,只要它不与你的任务需要的属性发生冲突,否则将被忽略。另外,因为是 JavaScript,所以不局限于 JSON;你可以在这里使用任何有效的 JS。有必要的话,你甚至可以用编程的方式生成配置对象。

像大部分任务一样,插件 grunt-contrib-uglify 的任务 uglify 需要它的配置被指定到一个同名属性。在这里,选项 banner 被指定,命名为 build 的一个 uglify 目标被一同指定,用于压缩一个源文件到一个目标文件。

// Project configuration.
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'
    }
  }
});

6.4 加载 grunt 插件和任务

常用的任务,例如 concatenationminificationlinting 都是有效的 grunt 插件。只要一个 插件在 package.json 中作为依赖库被指定,并且已经通过 npm install 安装,就可以在你的 Gruntfile 中使用一个简单的命令启用它:

// Load the plugin that provides the "uglify" task.
grunt.loadNpmTasks('grunt-contrib-uglify');

注意: 命令 grunt --help 将列出所有有效任务。

6.5 自定义任务

默认情况下,你可以定义一个 default 任务来运行一个或多个任务。在下面的例子中,在命令行中运行 grunt 而不指定一个任务,将运行任务 uglify。等价于明确的运行 grunt uglify,甚至等价于 grunt default。可以在数组中指定任务数量的任务(可以带有或不带参数)。

// Default task(s).
grunt.registerTask('default', ['uglify']);

如果 Grunt 插件不能提供项目所需的任务,你可以在 Gruntfile 中定义自定义任务。例如,下面的 Gruntfile 定义了一个完全自定义的任务 default,甚至没有使用任务配置:

module.exports = function(grunt) {

  // A very basic default task.
  grunt.registerTask('default', 'Log some stuff.', function() {
    grunt.log.write('Logging some stuff...').ok();
  });

};

自定义的项目特定任务不需要被定义在 Gruntfile 中;它们可以被定义在外部的 .js 文件中,然后通过方法 gruntgrunt.loadTasks 加载。

7. 延伸阅读

  • 安装 Grunt 指南详细描述了安装、生产、开发、Grunt 版本、grunt-cli 版本的信息。
  • 配置任务指南深入说明了如何在 Gruntfile 中配置任务、目标、选项和文件,还解释了模板、通配符以及导入外部数据。
  • 创建任务指南列出了 Grunt 任务之间的差异,并暂时了一些示例任务和配置。
  • 关于编写自定义任务或 Grunt 插件的更多信息,请查看开发人员文档

8. 译者后记

  1. [[]] 的链接是如何生成的?
  2. 通过在 md 文件的最后统一定义链接配置,以减少重复。
  3. 只用 [] 可以生成锚文。
  4. grunt 采用了什么版本的 md 转换工具?
posted @ 2013-10-19 13:39  agile30353  阅读(125)  评论(0编辑  收藏  举报