Grunt 入门指南2：任务配置

配置tasks

这份指南解释了在你的项目里怎么用Gruntfiile配置tasks。

Grunt 配置

task 配置通过grunt.initConfig 方法在Gruntfile中指定。配置主要是task-named 属性，但也会包含一些数据。

grunt.initConfig({
  concat: {
    // concat task configuration goes here.
  },
  uglify: {
    // uglify task configuration goes here.
  },
  // Arbitrary non-task-specific properties.
  my_property: 'whatever',
  my_src_files: ['foo/*.js', 'bar/*.js'],
});

Task 配置和 Targets

当一个task执行，Grunt会查找配置上与此task同名的属性.多个task可以有多个配置，它们被叫做 “targets”.在下面这个例子中, concat 有 foo 和 bar 两个 target， uglify 只有一个 bar target.

grunt.initConfig({
  concat: {
    foo: {
      // concat task "foo" target options and files go here.
    },
    bar: {
      // concat task "bar" target options and files go here.
    },
  },
  uglify: {
    bar: {
      // uglify task "bar" target options and files go here.
    },
  },
});

像grunt concat:foo 或者 grunt concat:bar 这样的task和target 只在指定的目标的配置上处理，当执行grunt concat时会迭代所有的targets，对每一个进行处理. 注意如果一个task被grunt.renametask 方法重命名后，Grunt将会按新的名字来寻找配置对象。

Options

在task配置中，指定options属性会覆盖内置的默认options. 并且每个target都可以指定一个options属性.Target级的options会覆盖Task级的options.

options 属性是可选的，如果不需要可以省略.

grunt.initConfig({
  concat: {
    options: {
      // Task-level options may go here, overriding task defaults.
    },
    foo: {
      options: {
        // "foo" target options may go here, overriding task-level options.
      },
    },
    bar: {
      // No options specified; this target will use task-level options.
    },
  },
});

Files

因为大量的tasks都需要执行文件操作，Grunt提供了强大的文件操作能力. 有很多种方式去定义src-dest(源码-目标)文件映射，可以在不同角度进行控制. 每个task都理解以下的格式, 你可以按需选择.

所有的文件格式都支持src和dest, 但是"Compact"和"Files Array"格式支持一些附加的属性:

• filter src里的路径通过任意一个有效的 fs.Stats 函数名或者一个函数通过返回true和false决定是否匹配
• nonull 当一个匹配没有找到时，返回包含这个模式的列表自身.当没有任何一个匹配时,返回一个空列表.结合grunt 的--verbore参数，这个选项可以帮助debug文件的路径问题.
• dot 即使模式没有包含开始的.,dot匹配文件名时也会开始于.
• matchBase 如果设置了, 模式在带有斜杠的文件名中,只会最后一个结尾的文件名,比如, a?b 只会匹配 /xyz/123/acb, 但不会匹配xyz/acb/123
• expand 提供一个动态的 src-dest 文件映射, 细节请看 "Building the files object dynamically"
• 其他的参数只在某些识别它的库中使用. 更多细节可以参考 node-glob 和 minimatch 文档

Compact Format

这种形式允许一个独立的 src-dest 文件映射到每个target. 通常用于只读的tasks, 像 grunt-contrib-jslint, 只有src没有dest.这个格式也支持在每个src-dest文件映射上附加属性

grunt.initConfig({
  jshint: {
    foo: {
      src: ['src/aa.js', 'src/aaa.js']
    },
  },
  concat: {
    bar: {
      src: ['src/bb.js', 'src/bbb.js'],
      dest: 'dest/b.js',
    },
  },
});

Files Object Format

这种形式支持在一个target里放多个 src-dest 映射，属性名是目标文件，值是单个或多个源码文件. 通过这个方法可以防止任意数量的 src-dest 文件映射, 但是这种形式不能增加附加属性.

grunt.initConfig({
  concat: {
    foo: {
      files: {
        'dest/a.js': ['src/aa.js', 'src/aaa.js'],
        'dest/a1.js': ['src/aa1.js', 'src/aaa1.js'],
      },
    },
    bar: {
      files: {
        'dest/b.js': ['src/bb.js', 'src/bbb.js'],
        'dest/b1.js': ['src/bb1.js', 'src/bbb1.js'],
      },
    },
  },
});

File Array Format

这个形式也支持一个target里放多个 src-dest 映射，并且允许每个映射增加附加的属性.

grunt.initConfig({
  concat: {
    foo: {
      files: [
        {src: ['src/aa.js', 'src/aaa.js'], dest: 'dest/a.js'},
        {src: ['src/aa1.js', 'src/aaa1.js'], dest: 'dest/a1.js'},
      ],
    },
    bar: {
      files: [
        {src: ['src/bb.js', 'src/bbb.js'], dest: 'dest/b/', nonull: true},
        {src: ['src/bb1.js', 'src/bbb1.js'], dest: 'dest/b1/', filter: 'isFile'},
      ],
    },
  },
});

Older Format

dest-as-target (target里直接定义dest) 格式是历史遗留的格式，目标文件路径即是target的名字. 不幸的是,因为target名字就是路径,执行 grunt task:target 就变得很尴尬. 同样,你也不能在每个src-dest文件映射上指定一个target级别的options或者附加属性.

考虑到这种格式已经被废弃,请不要使用它.

grunt.initConfig({
  concat: {
    'dest/a.js': ['src/aa.js', 'src/aaa.js'],
    'dest/b.js': ['src/bb.js', 'src/bbb.js'],
  },
});

Custom Filter Function

filter属性可以在细节上帮你定位文件. 最简单的是使用一个有效的 fs.Status 函数. 下例中将会只匹配真正的文件:

grunt.initConfig({
  clean: {
    foo: {
      src: ['tmp/**/*'],
      filter: 'isFile',
    },
  },
});

你也可以写一个自己的filter函数，并且在文件匹配时返回true和false.下例中只会匹配空目录:

grunt.initConfig({
  clean: {
    foo: {
      src: ['tmp/**/*'],
      filter: function(filepath) {
        return (grunt.file.isDir(filepath) && require('fs').readdirSync(filepath).length === 0);
      },
    },
  },
});

Globbing patterns

很多情况下我们不会指定所有文件的明确路径，所以Grunt 通过内置的 node-glob 和 minimatch 库支持文件名扩展(也就是文件名通配).

常用的通配模式有: * *匹配任意数量的字符，但不匹配/ * ?匹配单个字符,但不匹配/ * **匹配任意长度的字符,包括/,只要它是路径的唯一部分. * {}允许用逗号分割一个'或'关系的列表 * !在开头表示这个模式是反向的

大多数人们需要知道 foo/*.js会匹配所有在foo/目录中结尾为.js的文件，但是foo/**/*.js会匹配foo/文件夹以及它的所有子孙级文件夹中结尾为.js的文件.

同样,对于复杂的通配模式,Grunt允许使用文件路径或者通配模式数组. 在!前缀的模式从结果集中排除匹配的文件,所有模式将被按序预处理.结果集是去重的。

例子:

// You can specify single files:
{src: 'foo/this.js', dest: ...}
// Or arrays of files:
{src: ['foo/this.js', 'foo/that.js', 'foo/the-other.js'], dest: ...}
// Or you can generalize with a glob pattern:
{src: 'foo/th*.js', dest: ...}

// This single node-glob pattern:
{src: 'foo/{a,b}*.js', dest: ...}
// Could also be written like this:
{src: ['foo/a*.js', 'foo/b*.js'], dest: ...}

// All .js files, in foo/, in alpha order:
{src: ['foo/*.js'], dest: ...}
// Here, bar.js is first, followed by the remaining files, in alpha order:
{src: ['foo/bar.js', 'foo/*.js'], dest: ...}

// All files except for bar.js, in alpha order:
{src: ['foo/*.js', '!foo/bar.js'], dest: ...}
// All files in alpha order, but with bar.js at the end.
{src: ['foo/*.js', '!foo/bar.js', 'foo/bar.js'], dest: ...}

// Templates may be used in filepaths or glob patterns:
{src: ['src/<%= basename %>.js'], dest: 'build/<%= basename %>.min.js'}
// But they may also reference file lists defined elsewhere in the config:
{src: ['foo/*.js', '<%= jshint.all.src %>'], dest: ...}

想要看更多的通配模式语法，可以参考node-glob和minimatch文档。

Building the files object dynamically

当你想要处理很多独立的文件， 有些附加的属性可能用于动态构建文件列表.以下属性可以指定在"Compact"和"Files Array"映射格式中.

• expand 设置为true开启以下的选项:
• cwd 所有src匹配都相对于(但不包含)这个路径
• src 模式匹配时相对于cwd
• dest 目标文件路径前缀
• ext 在生成的dest路径中替换所有存在的扩展名为这个值
• flatten 将生成dest路径移除所有路径部分
• rename 这个函数会被每个src路径调用(在扩展被改名和flatten之后).dest和匹配的src路径会当参数传进去，这个函数必须返回一个新的dest 值. 如果同样的dest被多次返回,每次src都会用它添加到源码的数组中去.

下面的例子中,minifytask在sratic_mappings和dynamic_mappings targets 会看到同样的src-dest列表, 因为Grunt 会自动的扩展dynamic_mappings文件对象把四个单独的文件放入 src-dest 文件映射，加入4个文件可以在task执行的时候被找到的话.

静态和动态的文件映射可以随便结合着用.

grunt.initConfig({
  minify: {
    static_mappings: {
      // Because these src-dest file mappings are manually specified, every
      // time a new file is added or removed, the Gruntfile has to be updated.
      files: [
        {src: 'lib/a.js', dest: 'build/a.min.js'},
        {src: 'lib/b.js', dest: 'build/b.min.js'},
        {src: 'lib/subdir/c.js', dest: 'build/subdir/c.min.js'},
        {src: 'lib/subdir/d.js', dest: 'build/subdir/d.min.js'},
      ],
    },
    dynamic_mappings: {
      // Grunt will search for "**/*.js" under "lib/" when the "minify" task
      // runs and build the appropriate src-dest file mappings then, so you
      // don't need to update the Gruntfile when files are added or removed.
      files: [
        {
          expand: true,     // Enable dynamic expansion.
          cwd: 'lib/',      // Src matches are relative to this path.
          src: ['**/*.js'], // Actual pattern(s) to match.
          dest: 'build/',   // Destination path prefix.
          ext: '.min.js',   // Dest filepaths will have this extension.
        },
      ],
    },
  },
});

Templates

模版使用 <% %> 分割符，并且在tasks读入它的配置后自动扩展.模式会递归的扩展.

整个配置对象是每个确定的属性的上下文. 此外,grunt在模版内提供了它的方法,比如 <%= grunt.template.today('yyyy-mm-dd') %>

• <%= prop.subprop %> 被展开为配置中的 prop.subprop的值,而不用管类型.模版可以使用引用或者值类型.
• <% %> 可以指定任意的一行javascript代码, 在控制流程和循环的时候很有用

下面给出一个concattask配置的例子, 执行grunt concat:sample将会产生一个名为 build/abcde.js文件，这个文件用banner /* abcde */连接了所有匹配的文件 foo/*.js+bar/*.js + baz/*.js.

grunt.initConfig({
  concat: {
    sample: {
      options: {
        banner: '/* <%= baz %> */\n',   // '/* abcde */\n'
      },
      src: ['<%= qux %>', 'baz/*.js'],  // [['foo/*.js', 'bar/*.js'], 'baz/*.js']
      dest: 'build/<%= baz %>.js',      // 'build/abcde.js'
    },
  },
  // Arbitrary properties used in task configuration templates.
  foo: 'c',
  bar: 'b<%= foo %>d', // 'bcd'
  baz: 'a<%= bar %>e', // 'abcde'
  qux: ['foo/*.js', 'bar/*.js'],
});

Import External Data

在下面的Gruntfile中, 项目元数据是从package.json中导入的，并且 grunt-contrib-uglify 插件 uglify task 配置为压缩源码并且动态使用元数据添加banner.

Grunt 拥有 grunt.file.readJSON 和 grunt.file.readYAML 方法来导入 JSON 和 YAML 数据.

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