配置API

F.I.S可以支持从最简单的前端开发到大规模大团队项目开发，因此允许用户以 零配置 开始使用F.I.S，于此同时经过适当配置和扩展，F.I.S还能展现其强大的开发支持能力，足以应对大型商业产品开发需求。

零配置

不使用任何配置，fis将支持：

使用 fis install <name> 命令安装fis仓库提供的各种 组件、框架、示例、素材、配置等 开发资源。
使用 fis server start 命令启动一个本地调试服务器，完美支持php后端程序
使用 fis release --dest ./output --md5 命令为所有静态资源文件（js、css、图片、flash等）添加md5戳，并修改文件中的引用路径
使用 fis release --dest ./output --optimize 命令对js、css、html、htm文件进行压缩（后续还会加上对图片的自动压缩）
编译中对 js、 css 以及 类html ( html, htm, xhtml, tpl, php, jsp, asp ) 文件分别支持三种扩展语言能力：
- 资源定位：获取任何开发中所使用资源的线上路径；
- 内容嵌入：把一个文件的内容(文本)或者base64编码(图片)嵌入到另一个文件中；
- 依赖声明：在一个文本文件内标记对其他文件的依赖关系；

以上功能可满足传统前端开发所需的基本要求

使用配置文件

在项目目录下新建一个 fis-conf.js 文件，我们可以对fis的编译系统做各种定制化配置。配置fis系统的接口是：

fis.config.merge({...});

或者

fis.config.set(key, value);

由于fis自动化工具采用nodejs作为平台，因此其配置文件也是js书写的。fis变量是全局注册，config属性是fis系统的配置对象实例，merge方法用以合并配置数据。

内置的默认配置

由于fis系统是完全插件化的，因此fis.config对象会有一些内置配置用以为用户提供零配置下的基本功能，所以配置文件中使用fis.config.merge 或者 fis.config.set 接口来追加用户配置。而内部初始化的配置数是：

fis.config.init({
    project : {
        charset : 'utf8',
        md5Length : 7
    }
});

project.charset

解释：指定项目编译后产出文件的编码。
值类型：string
默认值：'utf8'

用法：在项目的fis-conf.js里可以覆盖为

fis.config.set('project.charset', 'gbk');

或者

fis.config.merge({
    project : { charset : 'gbk' }
});

project.md5Length

解释：文件MD5戳长度。
值类型：number
默认值：7

用法：在项目的fis-conf.js里可以修改为

fis.config.set('project.md5Length', 8);

或者

fis.config.merge({
    project : { md5Length : 8 }
});

project.md5Connector

解释：设置md5与文件的连字符。
值类型：string
默认值：'_'

用法：在项目的fis-conf.js里可以修改为

fis.config.merge({
    project : { md5Connector : '.' }
});

project.include

解释：设置项目源码文件include过滤器。只有命中include的文件才被视为源码，其他文件则忽略。
值类型：string | RegExp
默认值：无

用法：在项目的fis-conf.js里可以修改为

fis.config.merge({
    project : { include : 'src/**' }
});

project.exclude

解释：设置项目源码文件exclude过滤器。如果同时设置了 project.include 和 project.exclude 则表示在include所命中的文件中排除掉某些文件。
值类型：string | RegExp
默认值：无

用法：在项目的fis-conf.js里可以修改为

fis.config.merge({
    project : { exclude : /^\/_build\//i }
});

project.fileType.text

解释：追加文本文件后缀列表。
值类型：Array | string
默认值：无
说明：fis系统在编译时会对文本文件和图片类二进制文件做不同的处理，文件分类依据是后缀名。虽然内部已列出一些常见的文本文件后缀，但难保用户有其他的后缀文件，内部已列入文本文件后缀的列表为： [ 'css', 'tpl', 'js', 'php', 'txt', 'json', 'xml', 'htm', 'text', 'xhtml', 'html', 'md', 'conf', 'po', 'config', 'tmpl', 'coffee', 'less', 'sass', 'jsp', 'scss', 'manifest', 'bak', 'asp', 'tmp' ]，用户配置会追加，而非覆盖内部后缀列表。

用法：编辑项目的fis-conf.js配置文件

fis.config.merge({
    project : {
        fileType : {
            text : 'tpl, js, css'
        }
    }
});

project.fileType.image

解释：追加图片类二进制文件后缀列表。
值类型：Array | string
默认值：无
说明：fis系统在编译时会对文本文件和图片类二进制文件做不同的处理，文件分类依据是后缀名。虽然内部已列出一些常见的图片类二进制文件后缀，但难保用户有其他的后缀文件，内部已列入文本文件后缀的列表为： [ 'svg', 'tif', 'tiff', 'wbmp', 'png', 'bmp', 'fax', 'gif', 'ico', 'jfif', 'jpe', 'jpeg', 'jpg', 'woff', 'cur' ]，用户配置会追加，而非覆盖内部后缀列表。

用法：编辑项目的fis-conf.js配置文件

fis.config.merge({
    project : {
        fileType : {
            image : 'swf, cur, ico'
        }
    }
});

插件配置

fis系统有非常灵活的插件扩展能力，详细内容请参看运行原理，插件调用机制，插件扩展点列表等文档。

fis所有的插件配置都支持定义一个 数组或者逗号分隔的字符串序列 来依次处理文件内容。

modules.parser

解释：配置编译器插件，可以根据 文件后缀 将某种语言编译成标准的js、css、html语言。
值类型：Object
默认值：无
说明：fis对文件进行编译时，首先进入的是parser阶段，该阶段的定义是： 将非标准语言编译成标准的html、js、css语言。例如我们可以利用这个阶段的处理把coffee、前端模板文件编译成js，less、sass、compass编译成css。在该阶段配置的插件，实际调用的是 fis-parser-xxx，这是fis parser插件命名规范所约束的。parser插件通常不会内置，如需要相关插件，可以使用npm安装，具体说明请参考文档插件调用机制。由于parser的主要职责是统一标准语言，因此它经常会和 roadmap.ext 配置配合使用，用于标记某个后缀的文件在parser阶段之后当做某种标准语言进行处理。

用法：

//fis-conf.js
fis.config.merge({
    modules : {
        parser : {
            //coffee后缀的文件使用fis-parser-coffee-script插件编译
            coffee : 'coffee-script',
            //less后缀的文件使用fis-parser-less插件编译
            //处理器支持数组，或者逗号分隔的字符串配置
            less : ['less'],
            //md后缀的文件使用fis-parser-marked插件编译
            md : 'marked'
        }
    },
    roadmap : {
        ext : {
            //less后缀的文件将输出为css后缀
            //并且在parser之后的其他处理流程中被当做css文件处理
            less : 'css',
            //coffee后缀的文件将输出为js文件
            //并且在parser之后的其他处理流程中被当做js文件处理
            coffee : 'js',
            //md后缀的文件将输出为html文件
            //并且在parser之后的其他处理流程中被当做html文件处理
            md : 'html'
        }
    }
});

modules.preprocessor

解释：配置标准化预处理器插件，可以根据 文件后缀 对文件进行预处理。
值类型：Object
默认值：无
说明：标准化预处理的下一个阶段就是标准化处理阶段，标准化处理阶段主要责任是扩展三种语言能力，因此preprocessor插件可以在标准化处理之前对内容进行某些修改，比如 fis-preprocessor-image-set 插件，用于实现对retina屏的css的image-set属性支持。

用法：

//fis-conf.js
fis.config.merge({
    modules : {
        preprocessor : {
            //css后缀文件会经过fis-preprocessor-image-set插件的预处理
            css : 'image-set'
        }
    }
});

modules.postprocessor

解释：在fis对js、css和类html文件进行语言能力扩展之后调用的插件配置，可以根据 文件后缀 对文件进行后处理。该阶段的插件可以获取文件对象的完整requires信息。
值类型：Object
默认值：
```
{ js : 'jswrapper' }
```
说明：标准化处理之后，fis已经完成了对前端领域语言的三种语言能力扩展，此时文件对象的相关信息已经获取到了，这个阶段我们可以对文件进行一些相关处理，比如amd包装等。fis内置的 fis-postprocessor- jswrapper 插件就是在这个阶段对js进行包装的。
用法：类似 modules.preprocessor

modules.lint

解释：单文件编译过程中的代码检查插件。
值类型：Object
默认值：无
说明：fis支持在文件进行编译的过程中进行代码检查，这类插件 不会对文件内容做任何修改。fis模块内置没有安装任何校验插件，用户如果需要，可以自行开发，并发布到npm上。

用法：

//fis-conf.js
fis.config.merge({
    modules : {
        lint : {
            //js后缀文件会经过fis-lint-jshint插件的代码校验检查
            js : 'jshint'
        }
    }
});

modules.test

解释：单文件编译过程中的自动测试插件。
值类型：Object
默认值：无
说明：fis支持在文件进行编译的过程中进行自动化测试，这类插件 不会对文件内容做任何修改。fis模块没有内置任何测试插件，用户如果需要，可以自行开发，并发布到npm上。

用法：

//fis-conf.js
fis.config.merge({
    modules : {
        test : {
            //js后缀文件会经过fis-test-phantomjs插件的测试
            js : 'phantomjs'
        }
    }
});

modules.optimizer

解释：单文件编译过程中的最后阶段，对文件进行优化。
值类型：Object

默认值：

{
    js : 'uglify-js',
    css : 'clean-css',
    htm : 'html-minifier',
    html : 'html-minifier'
}

说明：单文件编译的最后阶段，可以对代码进行优化，通常是压缩、xss修复等工作，fis内置了3个压缩插件： fis-optimizer-uglify-js、fis-optimizer-clean-css、fis-optimizer-html-minifier。

用法：

//fis-conf.js
fis.config.merge({
    modules : {
        optimizer : {
            //js后缀文件会经过fis-optimizer-uglify-js插件的压缩优化
            js : 'uglify-js'
        }
    }
});

modules.prepackager

解释：打包预处理插件。
值类型：Array | string
默认值：无
说明：在fis打包操作前调用的插件， 不管调用fis release命令时是否使用 --pack 参数，该插件均会被调用。

用法：

//fis-conf.js
fis.config.merge({
    modules : {
        //打包前调用fis-prepackager-oo和fis-prepackager-xx插件进行处理
        prepackager : 'oo, xx'
    }
});

modules.packager

解释：打包处理插件。
值类型：Array | string
默认值：fis内置打包流程，生成 map.json 文件
说明：调用fis release命令时，添加 --pack 参数，该插件才会被调用。

用法：

//fis-conf.js
fis.config.merge({
    modules : {
        //打包调用fis-packager-your_packager插件进行处理
        packager : 'your_packager'
    }
});

modules.spriter

解释：打包后处理csssprite的插件。
值类型：Array | string
默认值：无
说明：调用fis release命令时，添加 --pack 参数，该插件才会被调用。

用法：

//fis-conf.js
fis.config.merge({
    modules : {
        //打包后调用fis-spriter-your_spriter插件进行css sprites化处理
        spriter : 'your_spriter'
    }
});

modules.postpackager

解释：打包后处理插件。
值类型：Array | string
默认值：无
说明：在fis打包操作后调用的插件， 不管调用fis release命令时是否使用 --pack 参数，该插件均会被调用。

用法：

//fis-conf.js
fis.config.merge({
    modules : {
        //打包后调用fis-postpackager-your_postpackager插件进行处理
        postpackager : 'your_postpackager'
    }
});

settings

解释：插件的配置数据节点。
值类型：Object
默认值：无
说明：插件要工作，偶尔也需要配置数据，比如fis内置的fis-optimizer-uglify-js、fis-optimizer-clean-css、fis-optimizer-html-minifier插件，它们的配置都是fis直接传递的，具体细节可以查看相应源码。配置节点具有很强的规律性，请参考下面的例子，小编就不一一枚举了。

用法：

//fis-conf.js
fis.config.merge({
    settings : {
        optimizer : {
            //fis-optimizer-uglify-js插件的配置数据
            'uglify-js' : {
                output : {
                    max_line_len : 500
                }
            },
            //fis-optimizer-clean-css插件的配置数据
            'clean-css' : {
                keepBreaks : true
            }
        }
    }
});

目录规范与域名配置

roadmap.path

解释：定制项目文件属性，包括但不限于 产出路径，访问url，资源id，默认依赖，文件类型。
值类型：Array
默认值：无
说明：roadmap.path配置是fis编译系中非常核心的机制，使用它可以控制文件编译后发布的路径或访问的url、操纵文件属性、为fis产出的资源表添加扩展信息，它的实现原理也很简单：当fis创建一个内部的 file对象时，会利用roadmap.path来匹配文件路径，如果命中，则将当前规则下的属性及其值赋给file对象，从而影响file对象的相关信息(发布路径、访问url、资源表属性等)。roadmap.path是fis系统中资源定位的核心能力，具有非常重要的意义。由于fis自动化工具接管了js、css和类html语言的 资源定位能力，因此，用户在开发时只需使用相对路径对资源进行引用，fis编译时会根据roadmap.path的配置调整引用内容，并将代码产出到配置指定的位置，一切都配合的非常完美！
支持的配置项：
- reg：用于匹配文件路径的正则(RegExp)或通配(String)。文件路径是相对项目根目录的路径，以 / 开头。
- release：设置文件的产出路径。默认是文件相对项目根目录的路径，以 / 开头。该值可以设置为 false ，表示为不产出（unreleasable）文件。
- url：指定文件的资源定位路径，以 / 开头。默认是 release 的值，url可以与发布路径 release 不一致。
- query：指定文件的资源定位路径之后的query，比如'?t=123124132'。
- id：指定文件的资源id。默认是 namespace + subpath 的值。
- charset：指定文本文件的输出编码。默认是 utf8，可以制定为 gbk 或 gb2312等。
- isHtmlLike：指定对文件进行html相关的语言能力扩展
- isJsLike：指定对文件进行js相关的语言能力扩展
- isCssLike：指定对文件进行css相关的语言能力扩展
- useCompile：指定文件是否经过fis的编译处理，如果为false，则该文件不会做任何编译处理。
- useHash：指定文件产出后是否添加md5戳。默认只有js、css、图片文件会添加。
- useDomain：指定文件引用处是否添加域名。
- useCache：指定文件编译过程中是否创建缓存，默认值是 true。
- useMap：指定fis在打包阶段是否将文件加入到map.json中索引。默认只有isJsLike、isCssLike、isMod的文件会加入表中
- useSprite：指定文件是否进行csssprite处理。默认是 false，即不对单个文件进行csssprite操作的，而只对合并后的文件进行。fis release中使用 --pack 参数即可触发csssprite操作。
- isMod：标记文件为组件化文件。被标记成组件化的文件会入map.json表。并且会对js文件进行组件化包装。
- extras：在map.json中的附加数据，用于扩展map.json表的功能。
- requires：默认依赖的资源id表，类型为Array。

用法：

fis.config.merge({
    roadmap : {
        path : [
            {
                //所有widget目录下的js文件
                reg : 'widget/**.js',
                //是模块化的js文件（标记为这种值的文件，会进行amd或者闭包包装）
                isMod : true,
                //默认依赖lib.js
                requires : [ 'lib.js' ],
                //向产出的map.json文件里附加一些信息
                extras : { say : '123' },
                //编译后产出到 /static/widget/xxx 目录下
                release : '/static$&'
            },
            {
                //所有的js文件
                reg : '**.js',
                //发布到/static/js/xxx目录下
                release : '/static/js$&'
            },
            {
                //所有的ico文件
                reg : '**.ico',
                //发布的时候即使加了--md5参数也不要生成带md5戳的文件
                useHash : false,
                //发布到/static/xxx目录下
                release : '/static$&'
            },
            {
                //所有image目录下的.png，.gif文件
                reg : /^\/images\/(.*\.(?:png|gif))/i,
                //访问这些图片的url是 '/m/xxxx?log_id=123'
                url : '/m/$1?log_id=123',
                //发布到/static/pic/xxx目录下
                release : '/static/pic/$1'
            },
            {
                //所有template目录下的.php文件
                reg : /^\/template\/(.*\.php)/i,
                //是类html文件，会进行html语言能力扩展
                isHtmlLike : true,
                //发布为gbk编码文件
                charset : 'gbk',
                //发布到/php/template/xxx目录下
                release : '/php/template/$1'
            },
            {
                //前面规则未匹配到的其他文件
                reg : /.*/,
                //编译的时候不要产出了
                release : false
            }
        ]
    }
});

roadmap.ext

解释：指定后缀名与标准化语言的映射关系。
值类型：Array
默认值：无
说明：fis允许在前端开发中使用less、coffee、utc等非标准语言，并能利用插件将它们编译成标准的js、css语言。这个过程是由modules.parser配置的插件处理的。编译之后，less会变成css文件，那么，后续对于css的处理应该同样可以适用于less的生成文件，因此，这个时候需要通过配置告诉fis，less文件会编译为css文件，并在后续的处理过程中当做css文件对待。

用法：

//fis-conf.js
fis.config.merge({
    roadmap : {
        ext : {
            //less后缀的文件将输出为css后缀
            //并且在parser之后的其他处理流程中被当做css文件处理
            less : 'css',
            //coffee后缀的文件将输出为js文件
            //并且在parser之后的其他处理流程中被当做js文件处理
            coffee : 'js',
            //md后缀的文件将输出为html文件
            //并且在parser之后的其他处理流程中被当做html文件处理
            md : 'html'
        }
    }
});

roadmap.domain

解释：设置静态资源的域名前缀。
值类型：Object | string
默认值：无
说明：fis扩展了html、js、css的三种语言能力，并支持对资源的定位，定位包括 开发路径与发布路径的映射关系 以及 静态资源服务器域名设置。roadmap.domain节点就是用于控制该能力的配置。
注意：domain的值如果不是特殊需要，请 不要以"/"结尾。

用法：

//fis-conf.js
//用法一
fis.config.merge({
    roadmap : {
        //所有静态资源文件都使用 http://s1.example.com 或者 http://s2.example.com 作为域名
        domain : 'http://s1.example.com, http://s2.example.com'
    }
});
//用法二
fis.config.merge({
    roadmap : {
        domain : {
            //widget目录下的所有css文件使用 http://css1.example.com 作为域名
            'widget/**.css' : 'http://css1.example.com',
            //所有的js文件使用 http://js1.example.com 或者  http://js2.example.com 作为域名
            '**.js' : ['http://js1.example.com', 'http://js2.example.com']
        }
    }
});

编译时使用fis release的 --domains 参数来控制是否添加domain

$ fis release --domains --dest ../output

roadmap.domain.image

解释：设置图片资源的域名前缀。
值类型：Array | string
默认值：无
说明：由于使用配置roadmap.domain.ext方式来配置图片资源太麻烦，fis提供了image字段，对于符合 project.fileType.image 规则的文件，设置相应domain配置。

用法：

//fis-conf.js
fis.config.merge({
    roadmap : {
        domain : {
            //所有图片文件，使用 http://img.example.com 作为域名
            'image' : ['http://img.example.com']
        }
    }
});

编译时使用fis release的 --domains 参数来控制是否添加domain

$ fis release --domains --dest ../output

部署配置

deploy

解释：设置项目的发布方式。
值类型：Object
默认值：无
说明：当使用 fis release 命令时，参数 --dest <name> 可以指定项目发布配置。deploy配置是一个key-value的object对象，--dest参数的值如果与配置的key相同，则执行该配置的部署设置。fis支持使用post请求向http服务器发送文件，服务器端可以使用php、java等后端逻辑进行接收，fis-command-release插件中提供了一个这样的 php版示例，用户可以直接部署此文件于接收端服务器上。

用法：

//fis-conf.js
fis.config.merge({
    deploy : {
        //使用fis release --dest remote来使用这个配置
        remote : {
            //如果配置了receiver，fis会把文件逐个post到接收端上
            receiver : 'http://www.example.com/path/to/receiver.php',
            //从产出的结果的static目录下找文件
            from : '/static',
            //保存到远端机器的/home/fis/www/static目录下
            //这个参数会跟随post请求一起发送
            to : '/home/fis/www/',
            //通配或正则过滤文件，表示只上传所有的js文件
            include : '**.js',
            //widget目录下的那些文件就不要发布了
            exclude : /\/widget\//i,
            //支持对文件进行字符串替换
            replace : {
                from : 'http://www.online.com',
                to : 'http://www.offline.com'
            }
        },
        //名字随便取的，没有特殊含义
        local : {
            //from参数省略，表示从发布后的根目录开始上传
            //发布到当前项目的上一级的output目录中
            to : '../output'
        }
    }
});

小贴士：--dest参数支持使用逗号（,）分割多个发布配置，比如上面的例子，我们可以使用fis release --dest remote,local 命令在一次编译中同时发布多个目标。

打包配置

pack

解释：配置要打包合并的文件。
值类型：Object
默认值：无
说明：fis内置的打包策略与传统的打包概念不同，fis的打包实际上是在建立一个资源表，并将其描述并产出为一份map.json文件，用户应该围绕着这份描述文件来设计前后端运行框架，从而实现运行时判断打包输出策略的架构。

用法：

//fis-conf.js
fis.config.merge({
    pack : {
        //打包所有的demo.js, script.js文件
        //将内容输出为static/pkg/aio.js文件
        'pkg/aio.js' : ['**/demo.js', /\/script\.js$/i],
        //打包所有的css文件
        //将内容输出为static/pkg/aio.css文件
        'pkg/aio.css' : '**.css'
    }
});

输出结果：使用命令 fis release --pack --md5 --dest ./output 编译项目，然后到output目录下查看产出的map.json内容得到：

{
    "res": {
        "demo.css": {
            "uri": "/static/css/demo_7defa41.css",
            "type": "css",
            "pkg": "p1"
        },
        "demo.js": {
            "uri": "/static/js/demo_33c5143.js",
            "type": "js",
            "deps": [
                "demo.css"
            ],
            "pkg": "p0"
        },
        "index.html": {
            "uri": "/index.html",
            "type": "html",
            "deps": [
                "demo.js",
                "demo.css"
            ]
        },
        "script.js": {
            "uri": "/static/js/script_32300bf.js",
            "type": "js",
            "pkg": "p0"
        },
        "style.css": {
            "uri": "/static/css/style_837b297.css",
            "type": "css",
            "pkg": "p1"
        }
    },
    "pkg": {
        "p0": {
            "uri": "/static/pkg/aio_5bb04ef.js",
            "type": "js",
            "has": [
                "demo.js",
                "script.js"
            ],
            "deps": [
                "demo.css"
            ]
        },
        "p1": {
            "uri": "/static/pkg/aio_cdf8bd3.css",
            "type": "css",
            "has": [
                "demo.css",
                "style.css"
            ]
        }
    }
}

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

配置API

零配置

使用配置文件

内置的默认配置

project.charset

project.md5Length

project.md5Connector

project.include

project.exclude

project.fileType.text

project.fileType.image

插件配置

modules.parser

modules.preprocessor

modules.postprocessor

modules.lint

modules.test

modules.optimizer

modules.prepackager

modules.packager

modules.spriter

modules.postpackager

settings

目录规范与域名配置

roadmap.path

roadmap.ext

roadmap.domain

roadmap.domain.image

部署配置

deploy

打包配置

pack

Clone this wiki locally