配置API

零配置

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

  • 使用 fis install 命令安装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系统的接口是：

  1. fis.config.set(key, value);

或者

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

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

内置的默认配置

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

  1. fis.config.init({
  2.     project : {
  3.         charset : 'utf8',
  4.         md5Length : 7
  5.     }
  6. });

项目配置

配置项 project

charset

  • 解释：指定项目编译后产出文件的编码。
  • 值类型：string
  • 默认值：'utf8'
  • 用法：在项目的fis-conf.js里可以覆盖为
  1. fis.config.set('project.charset', 'gbk');

或者

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

md5Length

  • 解释：文件MD5戳长度。
  • 值类型：number
  • 默认值：7
  • 用法：在项目的fis-conf.js里可以修改为
  1. fis.config.set('project.md5Length', 8);

或者

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

md5Connector

  • 解释：设置md5与文件的连字符。
  • 值类型：string
  • 默认值：'_'
  • 用法：在项目的fis-conf.js里可以修改为
  1. fis.config.set('project.md5Connector ', '.');

或者

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

include

  • 解释：设置项目源码文件include过滤器。只有命中include的文件才被视为源码，其他文件则忽略。
  • 值类型：Array | string | RegExp
  • 默认值：无
  • 用法：在项目的fis-conf.js里可以修改为
  1. fis.config.set('project.include', 'src/**');

或者

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

或者

  1. fis.config.set('project.include', ['src/**', /^\/vendor\//i]);

exclude

  • 解释：设置项目源码文件exclude过滤器。如果同时设置了 project.include 和 project.exclude 则表示在include所命中的文件中排除掉某些文件。
  • 值类型：Array | string | RegExp
  • 默认值：无
  • 用法：在项目的fis-conf.js里可以修改为
  1. fis.config.set('project.exclude', /^\/_build\//i);

或者

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

或者

  1. fis.config.set('project.exclude', ["dist/**", /^\/_build\//i]);

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配置文件
  1. fis.config.set('project.fileType.text', 'tpl, js, css');

或者

  1. fis.config.merge({
  2.     project : {
  3.         fileType : {
  4.             text : 'tpl, js, css'
  5.         }
  6.     }
  7. });

fileType.image

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

或者

  1. fis.config.merge({
  2.     project : {
  3.         fileType : {
  4.             image : 'swf, cur, ico'
  5.         }
  6.     }
  7. });

watch.exclude

  • 解释：设置项目源码监听时不监听的文件列表。
  • 值类型：Array | string | RegExp
  • 默认值：无
  • 用法：在项目的fis-conf.js里可以覆盖为
  1. fis.config.set('project.watch.exclude', 'node_modules');

或者

  1. fis.config.set('project.watch.exclude', ['node_modules', /docs/]);

watch.usePolling

  • 解释：设置项目源码监听的方式， usePolling 为 true 时会使用轮询的方式检查文件是否被修改，比较消耗CPU，但是适用场景更广。设置为 false 后会使用系统API进行文件修改检查，对性能消耗较小，但是可能由于系统版本不同，会存在兼容性问题。
  • 值类型：boolean
  • 默认值：false
  • 用法：在项目的fis-conf.js里可以覆盖为
  1. fis.config.set('project.watch.usePolling', true);

插件配置

配置项 modules

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

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

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阶段之后当做某种标准语言进行处理。
  • 用法：
  1. //fis-conf.js
  2. fis.config.merge({
  3.     modules : {
  4.         parser : {
  5.             //coffee后缀的文件使用fis-parser-coffee-script插件编译
  6.             coffee : 'coffee-script',
  7.             //less后缀的文件使用fis-parser-less插件编译
  8.             //处理器支持数组，或者逗号分隔的字符串配置
  9.             less : ['less'],
  10.             //md后缀的文件使用fis-parser-marked插件编译
  11.             md : 'marked'
  12.         }
  13.     },
  14.     roadmap : {
  15.         ext : {
  16.             //less后缀的文件将输出为css后缀
  17.             //并且在parser之后的其他处理流程中被当做css文件处理
  18.             less : 'css',
  19.             //coffee后缀的文件将输出为js文件
  20.             //并且在parser之后的其他处理流程中被当做js文件处理
  21.             coffee : 'js',
  22.             //md后缀的文件将输出为html文件
  23.             //并且在parser之后的其他处理流程中被当做html文件处理
  24.             md : 'html'
  25.         }
  26.     }
  27. });

preprocessor

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

或者

  1. //fis-conf.js
  2. fis.config.merge({
  3.     modules : {
  4.         preprocessor : {
  5.             //css后缀文件会经过fis-preprocessor-image-set插件的预处理
  6.             css : 'image-set'
  7.         }
  8.     }
  9. });

postprocessor

  • 解释：在fis对js、css和类html文件进行语言能力扩展之后调用的插件配置，可以根据 文件后缀 对文件进行后处理。该阶段的插件可以获取文件对象的完整requires信息。
  • 值类型：Object
  • 默认值：
  1. { js : 'jswrapper' }

  • 说明：标准化处理之后，fis已经完成了对前端领域语言的 三种语言能力 扩展，此时文件对象的相关信息已经获取到了，这个阶段我们可以对文件进行一些相关处理，比如amd包装等。fis内置的 fis-postprocessor- jswrapper 插件就是在这个阶段对js进行包装的。

  • 用法：类似 modules.preprocessor

lint

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

或者

  1. //fis-conf.js
  2. fis.config.merge({
  3.     modules : {
  4.         lint : {
  5.             //js后缀文件会经过fis-lint-jshint插件的代码校验检查
  6.             js : 'jshint'
  7.         }
  8.     }
  9. });

test

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

或者

  1. //fis-conf.js
  2. fis.config.merge({
  3.     modules : {
  4.         test : {
  5.             //js后缀文件会经过fis-test-phantomjs插件的测试
  6.             js : 'phantomjs'
  7.         }
  8.     }
  9. });

optimizer

  • 解释：单文件编译过程中的最后阶段，对文件进行优化。
  • 值类型：Object
  • 默认值：
  1. {
  2.     js : 'uglify-js',
  3.     css : 'clean-css',
  4.     png : 'png-compressor'
  5. }
  1. fis.config.set('modules.optimizer.js', 'uglify-js');

或者

  1. //fis-conf.js
  2. fis.config.merge({
  3.     modules : {
  4.         optimizer : {
  5.             //js后缀文件会经过fis-optimizer-uglify-js插件的压缩优化
  6.             js : 'uglify-js'
  7.         }
  8.     }
  9. });

prepackager

  • 解释：打包预处理插件。
  • 值类型：Array | string
  • 默认值：无
  • 说明：在fis打包操作前调用的插件， 不管调用fis release命令时是否使用 —pack 参数，该插件均会被调用。
  • 用法：
  1. fis.config.set('modules.prepackager', 'oo, xx');

或者

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

packager

  • 解释：打包处理插件。
  • 值类型：Array | string
  • 默认值：'map', fis内置了打包插件 fis-packager-map，生成 map.json 文件
  • 说明：调用fis release命令时，添加 —pack 参数，该插件才会被调用。
  • 用法：
  1. fis.config.set('modules.packager', 'your_packager');

或者

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

spriter

  • 解释：打包后处理csssprite的插件。
  • 值类型：Array | string
  • 默认值：'csssprites'，fis内置了spriter插件 fis-spriter-csssprites，支持自动css打包
  • 说明：调用fis release命令时，添加 —pack 参数，该插件才会被调用。
  • 用法：
  1. fis.config.set('modules.spriter', 'your_spriter');

或者

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

postpackager

  • 解释：打包后处理插件。
  • 值类型：Array | string
  • 默认值：无
  • 说明：在fis打包操作后调用的插件， 不管调用fis release命令时是否使用 —pack 参数，该插件均会被调用。
  • 用法：
  1. fis.config.set('modules.postpackager', 'your_postpackager');

或者

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

插件运行配置

配置项 settings

  • 解释：插件的运行配置节点。
  • 值类型：Object
  • 默认值：无
  • 说明：插件要工作，偶尔也需要配置数据，比如fis内置的fis-optimizer-uglify-js、fis-optimizer-clean-css，它们的配置都是fis直接传递的，具体细节可以查看相应源码。配置节点具有很强的规律性，请参考下面的例子，小编就不一一枚举了。
  • 用法：
  1. fis.config.set('settings.optimizer.uglify-js.output.max_line_len', 500);
  2. fis.config.set('settings.optimizer.clean-css.keepBreaks', true);

或者

  1. //fis-conf.js
  2. fis.config.merge({
  3.     settings : {
  4.         optimizer : {
  5.             //fis-optimizer-uglify-js插件的配置数据
  6.             'uglify-js' : {
  7.                 output : {
  8.                     max_line_len : 500
  9.                 }
  10.             },
  11.             //fis-optimizer-clean-css插件的配置数据
  12.             'clean-css' : {
  13.                 keepBreaks : true
  14.             }
  15.         }
  16.     }
  17. });

内置插件运行配置

postprocessor.jswrapper

  • 项目：https://github.com/fis-dev/fis-postprocessor-jswrapper
  • 解释：用于自动包装js代码的插件。
  • 值类型：Object
  • 默认值：无
  • 选项：
    • type：包装方式。可选值目前只有 'amd'，amd包装结构请参考 这里，非amd包装结构参考 这里
    • "template"：使用模板来定义包装结构，对template属性的设置优先级高于type属性。
    • wrapAll：是否包装所有js文件。默认是false，只对标记为 isMod 的文件进行包装
  • 用法：
  1. fis.config.set('settings.postprocessor.jswrapper.template', 'try{ ${content} }catch(e){e.message+="${id}";throw e;}');

或者

  1. fis.config.merge({
  2.     settings : {
  3.         postprocessor : {
  4.             jswrapper : {
  5.                 template : 'try{ ${content} }catch(e){ e.message += "${id}"; throw e; }'
  6.             }
  7.         }
  8.     }
  9. });

optimizer.uglify-js

  • 项目：https://github.com/fis-dev/fis-optimizer-uglify-js
  • 解释：uglify-js压缩器配置。fis-optimizer-uglify-js 插件内置了 uglify-js 包，并调用了它的 minify 接口，把配置选项直接传递过去。因此，fis的配置完全等价于uglify-js的minify函数所需的配置
  • 值类型：Object
  • 默认值：无
  • 选项：
    • mangle：混淆控制，参看uglify-js文档 mangle 部分
    • output：输出控制，参看uglify-js文档 codegen 部分
    • compress：优化参数，参看uglify-js文档 compress 部分
  • 用法：
  1. //配置字符串全部转换为ascii字符
  2. fis.config.set('settings.optimizer.uglify-js.output.ascii_only', true);

或者

  1. //配置字符串全部转换为ascii字符
  2. fis.config.merge({
  3.     settings : {
  4.         optimizer : {
  5.             'uglify-js' : {
  6.                 output : {
  7.                     ascii_only : true
  8.                 }
  9.             }
  10.         }
  11.     }
  12. });

optimizer.clean-css

  • 项目：https://github.com/fis-dev/fis-optimizer-clean-css
  • 解释：clean-css压缩器配置。fis-optimizer-clean-css 插件调用 clean-css 的压缩接口进行压缩，fis负责把 settings.optimizer.clean-css 配置节点的数据传递给压缩器，因此，这里的配置完全等价于clean-css的运行配置。
  • 值类型：Object
  • 默认值：无
  • 选项：参看clean-css的 文档
  • 用法：
  1. //配置压缩css时保留换行
  2. fis.config.set('settings.optimizer.clean-css.keepBreaks', true);

或者

  1. //配置压缩css时保留换行
  2. fis.config.merge({
  3.     settings : {
  4.         optimizer : {
  5.             'clean-css' : {
  6.                 keepBreaks : true
  7.             }
  8.         }
  9.     }
  10. });

optimizer.png-compressor

  • 项目：https://github.com/fis-dev/fis-optimizer-png-compressor
  • 解释：png图片压缩器运行配置。fis团队将 pngquant 和 pngcrush 两个优秀的png图片压缩工具移植为nodejs的原生扩展（node-pngcrush与node-pngquant-native），相比同类型工具采用进程调用的方式更高性能，压缩速度更快。
  • 值类型：Object
  • 默认值：无
  • 选项：
    • type：选择压缩器类型，默认是 'pngcrush'，可选值为 'pngquant'，pngquant会将所有 png24 的图片压缩为 png8，压缩率极高，但alpha通道信息会有损失。
  • 用法：
  1. //使用pngquant进行压缩，png图片压缩后均为png8
  2. fis.config.set('settings.optimizer.png-compressor.type', 'pngquant');

或者

  1. //使用pngquant进行压缩，png图片压缩后均为png8
  2. fis.config.merge({
  3.     settings : {
  4.         optimizer : {
  5.             'png-compressor' : {
  6.                 type : 'pngquant'
  7.             }
  8.         }
  9.     }
  10. });

spriter.csssprites

  • 项目：https://github.com/fis-dev/fis-spriter-csssprites
  • 解释：csssprite处理运行配置，以css文件为单位，对其引用的png、gif、jpg、jpeg等图片进行csssprite合并处理。@zhangyuanwei 同学将常用图片处理库的c++版本移植为nodejs的原生扩展，得到npm包 node-images，fis团队在此基础上进行包装，开发出了这款十分易用的csssprite插件。
  • 值类型：Object
  • 默认值：
  1. {
  2.     margin       : 3,
  3.     layout       : 'linear',
  4.     width_limit  : 10240,
  5.     height_limit : 10240
  6. }

  • 选项：

    • margin：图之间的边距，单位像素。
    • layout：布局算法，默认是 'linear'，图片垂直布局，水平方向无需 遮盖处理 。可选项还有 matrix，图片矩阵布局，面积最小化，但需要提供额外的dom控制水平方向图片的遮盖处理

  • 注意：使用csssprite需要满足以下条件

    • 使用release命令时，添加 -p 或者 —pack 参数。由于csssprite处理需要消耗一定的计算资源，并且开发过程中并不需要时刻做图片合并，因此fis将其定义为打包处理流程，启动csssprite处理需要指定—pack参数。
    • 只有 打包的css文件 或者 roadmap.path 中 useSprite 属性标记为 true 的文件才会进行csssprite处理，因此请合理安排要进行csssprite处理的文件，尽量对合并后的文件做处理。
    • 在css中引用图片时，只要加上 ?__sprite 这个query标记就可以使用csssprite了。详情请参考fis-spriter-csssprites插件的 使用文档。
  • 用法：
  1. //使用矩阵布局
  2. fis.config.set('settings.spriter.csssprites.layout', 'matrix');

或者

  1. //使用矩阵布局
  2. fis.config.merge({
  3.     settings : {
  4.         spriter : {
  5.             csssprites : {
  6.                 layout : 'matrix'
  7.             }
  8.         }
  9.     }
  10. });

目录规范与域名配置

配置项 roadmap

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的文件会加入表中
    • useParser：指定文件是否经过parser插件处理。默认为true，值为 false 时才会关闭。
    • usePreprocessor：指定文件是否经过preprocessor插件处理。默认为true，值为 false 时才会关闭。
    • useStandard：指定文件是否经过内置的三种语言标准化流程处理。默认为true，值为 false 时才会关闭。
    • usePostprocessor：指定文件是否经过postprocessor插件处理。默认为true，值为 false 时才会关闭。
    • useLint：指定文件是否经过lint插件处理。默认为true，值为 false 时才会关闭。
    • useTest：指定文件是否经过test插件处理。默认为true，值为 false 时才会关闭。
    • useOptimizer：指定文件是否经过optimizer插件处理
    • useSprite：指定文件是否进行csssprite处理。默认是 false，即不对单个文件进行csssprite操作的，而只对合并后的文件进行。fis release中使用 —pack 参数即可触发csssprite操作。
    • isMod：标记文件为组件化文件。被标记成组件化的文件会入map.json表。并且会对js文件进行组件化包装。
    • extras：在map.json中的附加数据，用于扩展map.json表的功能。
    • requires：默认依赖的资源id表，类型为Array。
  • 用法：
  1. fis.config.merge({
  2.     roadmap : {
  3.         path : [
  4.             {
  5.                 //所有widget目录下的js文件
  6.                 reg : 'widget/**.js',
  7.                 //是模块化的js文件（标记为这种值的文件，会进行amd或者闭包包装）
  8.                 isMod : true,
  9.                 //默认依赖lib.js
  10.                 requires : [ 'lib.js' ],
  11.                 //向产出的map.json文件里附加一些信息
  12.                 extras : { say : '123' },
  13.                 //编译后产出到 /static/widget/xxx 目录下
  14.                 release : '/static$&'
  15.             },
  16.             {
  17.                 //所有的js文件
  18.                 reg : '**.js',
  19.                 //发布到/static/js/xxx目录下
  20.                 release : '/static/js$&'
  21.             },
  22.             {
  23.                 //所有的ico文件
  24.                 reg : '**.ico',
  25.                 //发布的时候即使加了--md5参数也不要生成带md5戳的文件
  26.                 useHash : false,
  27.                 //发布到/static/xxx目录下
  28.                 release : '/static$&'
  29.             },
  30.             {
  31.                 //所有image目录下的.png，.gif文件
  32.                 reg : /^\/images\/(.*\.(?:png|gif))/i,
  33.                 //访问这些图片的url是 '/m/xxxx?log_id=123'
  34.                 url : '/m/$1?log_id=123',
  35.                 //发布到/static/pic/xxx目录下
  36.                 release : '/static/pic/$1'
  37.             },
  38.             {
  39.                 //所有template目录下的.php文件
  40.                 reg : /^\/template\/(.*\.php)/i,
  41.                 //是类html文件，会进行html语言能力扩展
  42.                 isHtmlLike : true,
  43.                 //发布为gbk编码文件
  44.                 charset : 'gbk',
  45.                 //发布到/php/template/xxx目录下
  46.                 release : '/php/template/$1'
  47.             },
  48.             {
  49.                 //前面规则未匹配到的其他文件
  50.                 reg : /.*/,
  51.                 //编译的时候不要产出了
  52.                 release : false
  53.             }
  54.         ]
  55.     }
  56. });

roadmap.ext

  • 解释：指定后缀名与标准化语言的映射关系。
  • 值类型：Object
  • 默认值：无
  • 说明：fis允许在前端开发中使用less、coffee、utc等非标准语言，并能利用插件将它们编译成标准的js、css语言。这个过程是由modules.parser配置的插件处理的。编译之后，less会变成css文件，那么，后续对于css的处理应该同样可以适用于less的生成文件，因此，这个时候需要通过配置告诉fis，less文件会编译为css文件，并在后续的处理过程中当做css文件对待。
  • 用法：
  1. //fis-conf.js
  2. fis.config.merge({
  3.     roadmap : {
  4.         ext : {
  5.             //less后缀的文件将输出为css后缀
  6.             //并且在parser之后的其他处理流程中被当做css文件处理
  7.             less : 'css',
  8.             //coffee后缀的文件将输出为js文件
  9.             //并且在parser之后的其他处理流程中被当做js文件处理
  10.             coffee : 'js',
  11.             //md后缀的文件将输出为html文件
  12.             //并且在parser之后的其他处理流程中被当做html文件处理
  13.             md : 'html'
  14.         }
  15.     }
  16. });

roadmap.domain

  • 解释：设置静态资源的域名前缀。
  • 值类型：Object | string
  • 默认值：无
  • 说明：fis扩展了html、js、css的三种语言能力，并支持对资源的定位，定位包括 开发路径与发布路径的映射关系 以及 静态资源服务器域名设置。roadmap.domain节点就是用于控制该能力的配置。
  • 注意：domain的值如果不是特殊需要，请 不要以"/"结尾。
  • 用法：
  1. //fis-conf.js
  2. //用法一
  3. fis.config.merge({
  4.     roadmap : {
  5.         //所有静态资源文件都使用 http://s1.example.com 或者 http://s2.example.com 作为域名
  6.         domain : 'http://s1.example.com, http://s2.example.com'
  7.     }
  8. });
  9. //用法二
  10. fis.config.merge({
  11.     roadmap : {
  12.         domain : {
  13.             //widget目录下的所有css文件使用 http://css1.example.com 作为域名
  14.             'widget/**.css' : 'http://css1.example.com',
  15.             //所有的js文件使用 http://js1.example.com 或者  http://js2.example.com 作为域名
  16.             '**.js' : ['http://js1.example.com', 'http://js2.example.com']
  17.         }
  18.     }
  19. });

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

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

roadmap.domain.image

  • 解释：设置图片资源的域名前缀。
  • 值类型：Array | string
  • 默认值：无
  • 说明：由于使用配置roadmap.domain.ext方式来配置图片资源太麻烦，fis提供了image字段，对于符合 project.fileType.image 规则的文件，设置相应domain配置。
  • 用法：
  1. //fis-conf.js
  2. fis.config.merge({
  3.     roadmap : {
  4.         domain : {
  5.             //所有图片文件，使用 http://img.example.com 作为域名
  6.             'image' : ['http://img.example.com']
  7.         }
  8.     }
  9. });

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

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

部署配置

配置项 deploy

  • 解释：设置项目的发布方式。
  • 值类型：Object
  • 默认值：无
  • 说明：当使用 fis release 命令时，参数 —dest 可以指定项目发布配置。deploy配置是一个key-value的object对象，—dest参数的值如果与配置的key相同，则执行该配置的部署设置。fis支持使用post请求向http服务器发送文件，服务器端可以使用php、java等后端逻辑进行接收，fis-command-release插件中提供了一个这样的 php版示例，用户可以直接部署此文件于接收端服务器上。
  • 用法：
  1. //fis-conf.js
  2. fis.config.merge({
  3.     deploy : {
  4.         //使用fis release --dest remote来使用这个配置
  5.         remote : {
  6.             //如果配置了receiver，fis会把文件逐个post到接收端上
  7.             receiver : 'http://www.example.com/path/to/receiver.php',
  8.             //从产出的结果的static目录下找文件
  9.             from : '/static',
  10.             //保存到远端机器的/home/fis/www/static目录下
  11.             //这个参数会跟随post请求一起发送
  12.             to : '/home/fis/www/',
  13.             //通配或正则过滤文件，表示只上传所有的js文件
  14.             include : '**.js',
  15.             //widget目录下的那些文件就不要发布了
  16.             exclude : /\/widget\//i,
  17.             //支持对文件进行字符串替换
  18.             replace : {
  19.                 from : 'http://www.online.com',
  20.                 to : 'http://www.offline.com'
  21.             }
  22.         },
  23.         //名字随便取的，没有特殊含义
  24.         local : {
  25.             //from参数省略，表示从发布后的根目录开始上传
  26.             //发布到当前项目的上一级的output目录中
  27.             to : '../output'
  28.         },
  29.         //也可以是一个数组
  30.         remote2 : [
  31.             {
  32.                 //将static目录上传到/home/fis/www/webroot下
  33.                 //上传文件路径为/home/fis/www/webroot/static/xxxx
  34.                 receiver : 'http://www.example.com/path/to/receiver.php',
  35.                 from : '/static',
  36.                 to : '/home/fis/www/webroot'
  37.             },
  38.             {
  39.                 //将template目录内的文件（不包括template一级）
  40.                 //上传到/home/fis/www/tpl下
  41.                 //上传文件路径为/home/fis/www/tpl/xxxx
  42.                 receiver : 'http://www.example.com/path/to/receiver.php',
  43.                 from : '/template',
  44.                 to : '/home/fis/www/tpl',
  45.                 subOnly : true
  46.             }
  47.         ]
  48.     }
  49. });

  • 小贴士：

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

  • subOnly参数 默认上传from整个目录到测试机。添加subOnly参数仅上传from目录下文件。

  • replace替换多个字符串 需要replace替换多个字符串，可以使用正则的方式。例如：

  1. replace : {
  2.     from : /www\.a\.com|www\.b\.com/,
  3.     to : function(m){
  4.         if(m === 'www.a.com') return 'www.x.com';
  5.         if(m === 'www.b.com') return 'www.y.com';
  6.     }
  7. }

deploy 扩展

通过 deploy扩展 能力，用户可以自定义 fis 的产出功能，更方便的实现自动化部署功能。目前官方提供的 deploy扩展 有

  • tar
  • git

  • bcs此外还有社区贡献的如

  • aliyun

  • zip

  • ftp使用 deploy扩展 的方法与使用 fis 插件的方法类似

  • 用法：

  1. // 设置开启deploy扩展，可以输入数组来开启多个扩展
  2. fis.config.set('modules.deploy', 'tar');
  4. // 为指定扩展设置发布配置
  5. fis.config.set('settings.deploy.tar', {
  6.     publish : {
  7.         from : '/',
  8.         to: '/',
  9.         gzip: true,
  10.         level: 0, //压缩质量 0-9，越大压缩比越高
  11.         memLevel: 6, //压缩使用的内存量 1-9， 越大占用内存越多，执行速度越快
  12.         file: './output/output.tar.gz'
  13.     }
  14. });
  1. # 发布至output/output.tar.gz
  2. fis release -d publish

打包配置

配置项 pack

  • 解释：配置要打包合并的文件。
  • 值类型：Object
  • 默认值：无
  • 说明：fis内置的 打包策略 与传统的打包概念不同，fis的打包实际上是在建立一个资源表，并将其描述并产出为一份map.json文件，用户应该围绕着这份描述文件来设计前后端运行框架，从而实现运行时判断打包输出策略的架构。
  • 用法：
  1. //fis-conf.js
  2. fis.config.merge({
  3.     pack : {
  4.         //打包所有的demo.js, script.js文件
  5.         //将内容输出为static/pkg/aio.js文件
  6.         'pkg/aio.js' : ['**/demo.js', /\/script\.js$/i],
  7.         //打包所有的css文件
  8.         //将内容输出为static/pkg/aio.css文件
  9.         'pkg/aio.css' : '**.css'
  10.     }
  11. });
  • 输出结果：使用命令 fis release —pack —md5 —dest ./output 编译项目，然后到output目录下查看产出的map.json内容得到：
  1. {
  2.     "res": {
  3.         "demo.css": {
  4.             "uri": "/static/css/demo_7defa41.css",
  5.             "type": "css",
  6.             "pkg": "p1"
  7.         },
  8.         "demo.js": {
  9.             "uri": "/static/js/demo_33c5143.js",
  10.             "type": "js",
  11.             "deps": [
  12.                 "demo.css"
  13.             ],
  14.             "pkg": "p0"
  15.         },
  16.         "index.html": {
  17.             "uri": "/index.html",
  18.             "type": "html",
  19.             "deps": [
  20.                 "demo.js",
  21.                 "demo.css"
  22.             ]
  23.         },
  24.         "script.js": {
  25.             "uri": "/static/js/script_32300bf.js",
  26.             "type": "js",
  27.             "pkg": "p0"
  28.         },
  29.         "style.css": {
  30.             "uri": "/static/css/style_837b297.css",
  31.             "type": "css",
  32.             "pkg": "p1"
  33.         }
  34.     },
  35.     "pkg": {
  36.         "p0": {
  37.             "uri": "/static/pkg/aio_5bb04ef.js",
  38.             "type": "js",
  39.             "has": [
  40.                 "demo.js",
  41.                 "script.js"
  42.             ],
  43.             "deps": [
  44.                 "demo.css"
  45.             ]
  46.         },
  47.         "p1": {
  48.             "uri": "/static/pkg/aio_cdf8bd3.css",
  49.             "type": "css",
  50.             "has": [
  51.                 "demo.css",
  52.                 "style.css"
  53.             ]
  54.         }
  55.     }
  56. }
有任何问题，请在 https://github.com/fex-team/fis/issues 讨论