内置 Processor

EDP很重要的一个功能就是通过edp build来构建项目。在构建过程中，处理阶段，对资源的处理主要由一个或多个Processor完成。Processor直接是链式的串行处理过程，每个Processor处理的是上一个Processor处理后的结果。

公共属性

files属性

该属性从 1.0.0版本 开始引入。

通过Processor的files参数可以为Processor选择需要处理的文件。每个Processor都支持files，其是一个Array，其中每一项是一个符合glob规则的pattern string。后续的各个Processor介绍将不再对files参数进行说明。

每个Processor在开始处理前，其要处理的文件是一个空集，我们称作PROCESS_FILES。通过files的每一项pattern 按顺序 选择文件。

  • 如果pattern不以!开头，从BUILD_FILES中选出符合该pattern的文件放入PROCESS_FILES
  • 如果pattern以!开头，从PROCESS_FILES中将符合该pattern的文件排除
1
2
3
4
5
6
new LessCompiler({
    files: [
        '*.less',
        '!test/**/*.less'
    ]
})

LessCompiler

编译less文件，并对其他文件中less资源的引用替换成css。具体有：

  1. *.less编译为*.css
  2. entryFiles指定入口文件，把<link href="*.less">替换为<link href="*.css">
  3. *.js中通过插件引用*.less的地方修改为*.css
1
new LessCompiler({
    files: [ '*.less' ],
    /* entryExtnames: 'html,php,tpl' 旧版本使用 新版本种兼容但不推荐 推荐使用entryFiles*/
    entryFiles: [
        '*.html', '*.htm', '*.phtml',
        '*.tpl', '*.vm', '*.js'
    ]
});

下面是LessCompiler的参数说明：

compileOptions

Object。less编译参数，默认值为：

1
{
    paths: [ less file's directory ],
    relativeUrls: true
}

如果想要输出的css是压缩之后的，可以添加参数{ compress: true }即可，一定程度上可以代替CssCompressor的功能.

entryFiles

Array.<string>，less入口文件选择，规则与files相同。 默认值 是：

1
2
3
4
5
6
7
8
[ 
    '*.html', 
    '*.htm', 
    '*.phtml',
    '*.tpl',
    '*.vm',
    '*.js' 
]

被匹配上的文件被称为less入口文件。LessCompiler将自动扫描里面对less资源的引用，替换成css。

files

Array.<string>，默认值是[ '*.less' ]

less

Object，自定义的less模块。

edp-build有自己依赖的less版本，如果不想使用该版本，可以自己提供一个less模块：

1
new LessCompiler({
  less: require( "./tools/less" )
})

StylusCompiler

StylusCompiler的功能跟LessCompiler类似。编译styl文件，并对其他文件中styl资源的引用替换成css。

  1. *.styl编译为*.css
  2. entryFiles指定入口文件，把<link href="*.styl">替换为<link href="*.css">
  3. *.js中通过插件引用*.styl的地方修改为*.css
1
new StylusCompiler({
    files: [ '*.styl' ],
     /* entryExtnames: 'html,php,tpl' 旧版本使用 新版本种兼容但不推荐 推荐使用entryFiles */
    entryFiles: [
        '*.html', '*.htm', '*.phtml',
        '*.tpl', '*.vm', '*.js'
    ]

});

下面是StylusCompiler的参数说明：

compileOptions

Object，stylus编译参数，默认值为：

1
{
    paths: [ stylus file's directory ],
    pathname: 'stylus file's fullpath',
    use: this.compileOptions
}

如果想要输出的css是压缩之后的，可以添加参数{ compress: true }即可，一定程度上可以代替CssCompressor的功能.

entryFiles

请参考LessCompiler的entryFiles参数说明。

files

请参考LessCompiler的files参数说明。

stylus

Object，自定义的stylus模块。

edp-build有自己依赖的stylus版本，如果不想使用该版本，可以自己提供一个stylus模块。使用方式参考LessCompiler。

CssCompressor

对css资源进行压缩。edp-build使用的css压缩工具是clean-css。

1
new CssCompressor({
    files: [ '*.css', '*.less' ]
});

下面是CssCompressor的参数说明：

compressOptions

Object，clean-css的压缩参数，默认值为：

1
{
    "noAdvanced": true,  // clean-css的优化模式某些情况下存在问题，默认禁用
    "keepBreaks": true,  // 不压缩成一行
    "relativeTo": css file's directory
}

如果想了解clean-css还支持哪些参数，可以查看clean-css的参数说明。

files

Array.<string>，默认值是[ '*.css' ]。

JsCompressor

对js资源进行压缩。edp-build使用的js压缩工具是uglifyjs2。默认只处理*.js文件。

1
new JsCompressor({
    files: [ '*.js', '*.coffee' ]
});

下面是JsCompressor的参数说明：

files

Array.<string>，默认值是[ '*.js', '!*.min.js' ]。

compressOptions

Object，压缩选项，默认值是：{ "warnings": false, "conditionals": false }。详细信息请参考uglifyjs2 compress options

mangleOptions

Object，默认值是：{ "except": [ 'require', 'exports', 'module' ] }，也就是给变量重命名的时候，忽略这三个变量名。

sourceMapOptions

Object，生成 JavaScript Source Map 文件，默认值是: { enable: false, root: 'sourcemap', host: null } enable: 表示功能是否开启, root: 决定了 output 目录中的source map所在的目录, host: 决定了 sourceMappingURL 的前缀

ModuleCompiler

编译AMD模块。主要是将匿名模块具名化，并根据配置和依赖进行模块合并。默认只处理*.js。

ModuleCompiler的处理需要一个模块配置文件，该模块配置文件必须是一个JSON文件，详情请参见configFile配置项说明。

注意：如果最终发布的代码不需要对代码进行合并，那么就没有必要将匿名模块具名化，因此也无需使用ModuleCompiler。

1
new ModuleCompiler({
    configFile: 'my-module.conf'
});

下面是ModuleCompiler的参数说明：

files

Array.<string>，默认值是[ '*.js' ]。

configFile

模块配置文件，默认为module.conf。配置文件是一个JSON文件，允许包含以下属性：

  • {string}``baseUrl - 模块查找的根路径，相对于配置文件所在目录。
  • {Object}``paths - 特殊模块查找路径，相对于baseUrl
  • {Array.<Object>}``packages - 包引入配置，其中每个包配置location项的路径相对于baseUrl
  • {Object}``combine - 需要合并的模块，其中key为模块id，value为{boolean}或Object。

baseUrl、paths、packages配置项为AMD标准配置项，详细说明请参考AMD Common Config或ESL的配置文档

getCombineConfig

function(Object=):Object，接收一个Object，返回值是Object类型。ModuleCompiler在读取合并模块配置项的时候，主要参考两个地方：

  1. module.conf文件中的combine字段
  2. getCombineConfig函数的返回值

当我们发现配置了getCombineConfig之后，就会调用这个函数，传递的参数是module.conf中combine字段的值。

常见模块合并场景的配置方法

当我们想要合并一些文件的时候，是以Module Id的维度来声明的。例如，当我们想要合并src/common/main.js中的代码，那么可以简单的在module.conf中配置：

1
{
    "combine": {
        "common/main": true
    }
}

合并的过程是递归处理的，也就是先找到common/main的一级依赖，把这些依赖的代码合并进来，然后再找二级依赖，三级依赖等等，最终把common/main所有的依赖都合并进来。

1
....
....

define( "common/main", function( require ) {
    ...
    ...
})

当我们在合并的过程中想要排除一些模块的时候，可以使用modules，例如：

1
{
    "combine": {
        "common/main": {
            "modules": [ "!~er" ]
        }
    }
}

也就是虽然common/main最终可能依赖了er的代码，但是不要合并进来，而是需要的时候再去按需加载。

当我们在合并的过程中想要显式的加入一些模块的时候，可以使用modules，例如：

1
{
    "combine": {
        "common/main": {
            "modules": [ "~esui" ]
        }
    }
}

也就是虽然common/main没有直接依赖esui的代码，但是在将来的某个时刻可能会用到，那么就先合并进来，这样子后续使用的时候就不需要重新去加载了。

PathMapper

对最终输出的文件路径进行一些改动。主要是基于如下两个方面的考虑：

  1. 项目中源码主要放在src目录，如果我们最终输出的代码里面还是保留src目录，就看起来很不正式
  2. 对最终输出的路径进行一些改动，可以一定程度上降低因为浏览器或者CDN缓存导致没有获取最新资源的问题

PathMapper一般做为最后一个Processor。

下面是PathMapper的参数说明：

from

string，默认值是src，用来设置替换的源路径，一般都是配置成：{ "from": "src" }。

to

string，默认值是asset，用来设置替换的目标路径，一般都是配置成：{ "to": "asset" }。

有时候，我们希望多版本并存，以前的版本能够被保留，可以配置成：

1
// SvnRevision函数请自己实现
{ 
    "to": "asset-" + SvnRevision()
}

mapper

function(string):string，路径映射函数。可以理解为是加强版的from和to，如果单纯的配置from和to无法满足需求的话，可以配置mapper。

1
2
3
4
5
new PathMapper({
    mapper: function( value ) { 
        return value.replace( from, to ) 
    }
});

replacements

Array.<Object>，用于指定路径替换后相应资源的引用替换，比如将html中的img标签里src属性为src/img的替换成asset/img。replacements的默认值如下：

1
replacements: [
    { type: 'html', tag: 'link', attribute: 'href', extnames: pageEntries },
    { type: 'html', tag: 'img', attribute: 'src', extnames: pageEntries },
    { type: 'html', tag: 'script', attribute: 'src', extnames: pageEntries },
    { extnames: 'html', replacer: 'module-config' },
    { extnames: 'less,css', replacer: 'css' }
]

前面三条规则应该可以猜出是什么意思，这里就不解释了；第四条规则指的是替换*.html中require.config的配置，比如把：{ "baseUrl": "src" }替换为{ "baseUrl": "asset" }；第五条规则是替换所有css文件中引用图片的路径。

替换的时候只是替换相对路径的引用，如果路径是远程的资源，比如http://, https://, //就不会处理，也不应该处理。

TplMerge

这个Processor的作用是合并项目中出现过的模板资源，这样子在发布状态下就会尽可能的减少模板的请求。

下面是TplMerge的参数说明：

files

Array.<string>，默认值是[ 'src/**/*.js' ]。

pluginIds

Array.<string>，默认值是[ 'tpl', 'er/tpl' ]，数组中的每一项都是一个模板插件的Id，如果你的项目中模板插件的Id没有被包含在里面，那么就需要配置这个参数。

configFile

string，默认值是module.conf。详细请参考ModuleCompiler的configFile。

outputType

string，如果想要把合并之后的模板输出为一个AMD的模块，那么请把这个参数的值设置为js，设置其它的值是不接受的。

outputPluginId

string。

如果合并之后，如果想要把合并之后的模板输出为一个AMD的模块，那么请把这个参数值设置为一个模板插件的Id，例如jstpl。因为使用xhr的方式加载模板的插件跟使用require的方式来加载模板的插件应该是不一样的，所以需要单独设置一下这个参数的值。

注意：outputPluginId必须同时设置才会有效，否则没有效果。

如果我们把最终合并的模板输出为一个AMD的模块，那么就可以把模板也部署到Cookieless Domain下面了，不再受限于xhr的跨域问题的限制。

注意：如果需要输出为AMD的模块，那么主要的工作是由html2js这个npm package来完成的，因此TplMerge在一定程度上完成了Html2JsCompiler的工作。

AddCopyright

给最终输出的文件头部添加一个版权声明。

默认给css、less、js文件添加版权声明。即files的默认值为['*.css', '*.less', '*.js']。

如果在构建配置文件（通常为edp-build-config.js）同级目录下存在copyright.txt文件，则版权声明以该文件内容为准。否则将使用默认的版权声明信息：

1
'/*! ' + new Date().getFullYear() + ' Baidu Inc. All Rights Reserved */\n'

VariableSubstitution

将文本文件里{edp-variable:{variableName}}相应部分替换成相应variableName的值。通常用于为页面的资源引用附加版本号。

1
2
3
4
5
6
7
8
9
10
11
12
13
new VariableSubstitution({
    files: ['*.html'],
    variables: {
        version: '1.0.0'
    }
});

/* 
html里：
<link rel="stylesheet" href="main.css?{edp-variable:{version}}">
会被替换成：
<link rel="stylesheet" href="main.css?1.0.0">
*/

下面是VariableSubstitution的参数说明：

variables

Object，用于声明各个变量的值。

MD5Renamer

将静态文件根据MD5摘要命名，并且替换html和css中对该资源的引用地址。

以MD5命名通常有利于浏览器缓存，甚至可以在HTTP头声明该资源永久缓存。MD5Renamer将生成一个内容完全相同，名称为MD5摘要的文件。原文件将保留，不做删除。

MD5Renamer通常放在Processor链的倒数第二的位置，PathMapper前。

1
2
3
4
5
6
7
8
9
10
new MD5Renamer( {
    files: [ 
        "src/common/css/main.less"
    ],
    replacements: {
        html: [
            "index.html"
        ]
    }
} )

下面是MD5Renamer的参数说明：

replacements

Object，要替换的资源配置。该对象只支持html和css两个属性，分别是Array.<string>。

不同类型的资源，将进行不同的替换：

  • 对于html，替换script的src、img的src、link的href
  • 对于css，只替换url()

对非files中匹配的资源的引用，将不做替换。上面的例子中，只有对main.less的引用会被替换，ui.less的引用不会被替换。

OutputCleaner

如果观察最终输出的output目录中的文件，你可能会发现可能存在一些完全用不到的文件，例如*.less，*.styl，如果你想进一步优化的输出的内容，可以使用这个Processor来删除一些明确不需要的文件。

下面是OutputCleaner的参数说明：

files

Array.<string>，默认值是：[ '*.less', '*.styl', '*.ts', '*.coffee' ]

BabelProcessor

此处理器的作用是使用转译器 babel 将项目使用ES6语法的js代码转为ES5代码。

下面是BabelProcessor的参数说明：

files

Array.<string>，默认值是：[ '*.es6', '*.es' ]

compileOptions

Object, babel 的参数，默认值是：

1
{
    loose: 'all',
    modules: 'amd',
    compact: false,
    ast: false,
    blacklist: ['strict']
}

详细信息请参考Options for babel transpiling.

BcsUploader

可以使用这个处理器将文件上传到 bcs(百度云存储) 中

1
new BcsUploader({
    ak: 'ak',
    sk: 'sk',
    bucket: 'weigou-baidu-com',
    prefix: 'bcj-static/20140624',
    concurrent: 5,
    files: [
    ]
})

下面是BcsUploader的参数说明：

files

Array.<string> 处理器要处理的文件 默认值是：['*.js', '*.css', '*.less']

ak

string AccessKey bcs提供的

sk

string SecretKey bcs提供的

bucket

string bcs提供的bucket

prefix

string 上传文件的路径的前缀

concurrent

number 上传并发数，默认值是：5

maxSize

number 文件最大尺寸 默认值是：10 1024 1024

CssSpriter

通过css-spriter工具分析css文件中引用的图片文件构建成雪碧图，然后自动修改css文件中的图片引用信息

1
new CssSpriter({
    files: [
    ]
})

下面是CssSpriter的参数说明：

files

Array.<string> 处理器要处理的文件 默认值是：[]

HtmlMinifier

此处理器默认通过使用html-minifier工具分析html文档的内容，对html文档进行压缩，有效的减小项目内html文档的体积

1
new HtmlMinifier({
    files: [],
    minifyOptions: {}
})

下面是HtmlMinifier的参数说明:

files

Array.<string> 处理器要处理的文件 默认值是：['*.html', '*.tpl.html']

minifyOptions

Object, html-minifier 的参数，默认值是：

1
{
    ignoreCustomComments: [
        /^\s*(\/)?([a-z]+)\s*(?::([\s\S]*))?$/
    ]
}

更多配置参数请参考：html-minifier

Html2JsCompiler

将html文档转换成js文档，在js中引用时可以解决跨域的问题

下面是Html2JsCompiler的参数说明:

files

Array.<string> 处理器要处理的文件 默认值是：null

extnames

使用文件后缀名配置要处理的文件，与参数files功能相同，默认值是：['hjs', 'mustcahe']

需要注意的是：如果没有配置files和extnames处理器会自动使用extnames的默认值作为要处理的文件，当配置了files时处理器会忽略extnames的配置

clean

boolean 默认值是：false 配置为true将只发出一条警告，html2js不去处理文件

wrap

string 表示转换后js代码的包装器类型 默认值是：amd

可选值：null，amd，commonjs 分别表示无包装，amd包装，CommonJS包装

各参数具体效果请参考:html2js

mode

string 表示html转换成js代码后的代码样式 默认值是：null

可选值：

null 或者 default:表示保持原html文档的格式

compress:清除原文档中每行开始和结束位置两端的空白以及转义字符

format:整理成符合规范的js代码

各参数具体效果请参考:html2js

ReplaceDebug

修正DEBUG变量，将window.DEBUG的值改为false

下面是ReplaceDebug的参数说明:

files

Array.<string> 处理器要处理的文件 默认值是：null

extnames

使用文件后缀名配置要处理的文件，与参数files功能相同，默认值是：['html']

需要注意的是：如果没有配置files和extnames处理器会自动使用extnames的默认值作为要处理的文件，当配置了files时处理器会忽略extnames的配置

StringReplace

此处理器用于字符串替换

下面是StringReplace的参数说明:

files

Array.<string> 处理器要处理的文件 默认值是：null

replacements

Array.<Object>，用于指定要匹配的字符信息，以及要被替换成的字符串或者返回字符串的函数如下示例：

1
[
    {
        from: 'foo',
        to: 'bar'
    },
    {
       from: /(\w+)\s*, \s*(\w+)/,
       to: function(word, first, second){
           return '' + second + first;
       }
    }
]