Gulp针对F1平台的前端资源打包说明

本文介绍F1V3.0前端项目的打包操作

平台打包分为两种

一种是针对平台组件包和三方包的由gulp驱动webpack打包的方式
一种是针对平台前端业务模块的gulp插件打包。

---

1 驱动webpack打包

为什么使用webpack：

由于V3.0的平台组件源码和平台依赖的三方包都是用模块化进行开发的，所以选用webpack尽心打包，打包前的文件删除等操作则是使用gulp进行处理的，所以最后选用gulp驱动webpack的方法进行打包。

gulp是任务驱动的，所以驱动webpack只需要建一个webpack的任务就可以，平台提供了写好的gulpfile放在了“F1UI_widget_libraries”中，其中的“build-dev-webpack”任务就是驱动webpack的。这个打包主要聚合了平台组件的源码（生成了widget_libraries）和三方插件包（生成了public_libraries），具体完成了代码压缩合并，stylus编译以及生成source-map等操作（详情见webpack使用文档）具体的驱动如下：

驱动gulp进行打包的操作：

1. 在“F1UI_widget_libraries”目录下打开终端
2. 运行“gulp dev”即可

---

2 gulp插件打包

平台V3.0的业务模块前端的资源没有使用模块化进行开发，加上业务模块引用的js比较复杂，所以不需要使用webpack的代码合并，所以选用gulp进行打包操作，主要是针对代码压缩、浏览器缓存、生产环境和开发环境的区分等问题进行了处理

2.1 介绍

平台封装好了一套打包的环境，用于对前端模块中的资源进行压缩和版本管理的操作，使用gulp的对前端资源进行处理。用到了gulp-rev、gulp-rev-collector、gulp-uglify、gulp-sourcemaps、gulp-clean-css等gulp插件，以及path、glob、del等node插件，因为gulp-rev和gulp-rev-collector根据平台需要进行了部分的修改，所以打包的整体node-modules请使用平台组提供的。

2.2 规范

这里还涉及到了一个打包前项目的规范要求，要求项目名后缀为“_bundle”，所有的资源放在src文件夹中，如下图所示：（src为“开发环境”，后面作出解释）

2.3 环境安装

平台提供的node-modules已经将用到的插件都集成好了，所以装一个全局的gulp就好了，指令如下

npm install -g gulp

2.4 打包操作

考虑到大家平常的开发模式是将所有的开发项目放到同一个工作空间下，所以打包程序中提供了这种功能，只配置打包环境到开发的工作空间，程序会自动扫描以”_bundle”为后缀名的程序（这就是为什么规范中要把项目名后缀改为“_bundle”），而打包的时候就是对一个项目下边的“src”目录中的资源进行打包操作（这就是为什么要把所有的资源放在“src”中）

为了增减兼容性，如果出现后缀不是“_bundle”的项目，或者项目不在工作空间里，但是也想打包，这种情况下就要单独对该项目进行配置了。

所以有以上两种配置方法，接下来要介绍这两种的配置方法

1）配置文件介绍

在gulpBuildProject中有一个conf.json文件是平台打包的配置文件。配置文件分为“const”和“bundleArray”两部分，分别对应上边提到的两种情况，commet是注释，不用配置，可删除。

2）两种打包配置

1. const

是针对“对工作空间中所有的以’_bundle’结尾的项目”进行打包的配置，具体结构如下：

"const" : {
    "moduleBasePath" : "D:/Projects/gitlib/f1-platform-modules",
    "librariesBasePath" : "D:/Projects/gitlib/f1-platform-modules",
    "switch" : "off",
    "needSourceMap" : true,
    "developmentRoot" : "src",
    "productionRoot" : "dist"
}

如上图，配置项解释如下：

nginx命令	执行命令的作用
moduleBasePath	工作空间根目录，如果路径为“D:/f1/workspace”，那就陪成“D:/f1/workspace”就好了，切记不要用”\”，要用“／”，切记不要在路径结尾加“/”
librariesBasePath	引用的平台包及三方包（widget_libraries、public_libraries、plugins_librarise）的位置（也是根目录）
switch	打包开关，“on”时进行打包操作，“off”时则不进行打包操作
needSourceMap	是否需要sourcemap（sourcemap是js代码压缩混淆之后对原js文件的索引，方便打包之后在浏览器中进行调时，如果不需要sourcemap就可以设置为false，可以加快打包）
developementRoot	“开发模式”的根目录名（开发模式后边会详细讲解），直接影响打包的位置，如果配置为“src”，则打包时会对项目下的“src”文件夹下的资源进行打包（不建议修改这个配置项，所以规范中给出要把所有打包的资源放在项目的“src”下）
productionRoot	“生产模式”的根目录名（生产模式后边会详细讲解），直接影响打包生成的文件夹名称，就是针对“src”打包完成之后会在同级目录下生成一个“dist”文件夹来存放打完包的资源。（同样不建议修改）

具体的详细使用可以参考下面的示例啊

2. bundleArray

针对特殊的情况一：“要打包的项目没有以’_bundle’结尾”，那么需要在“bundleArray”中配置，具体的结构如下：

"bundleArray" : {
    //permission_other为项目名，如果const中的moduleBasePath设置为'D://f1/workspace'那么请确保'D://f1/workspace/permission_other的存在
    "permission_other" : {
        "switch" : "on",
        "needSourceMap" : false,
        "developmentRoot" : "src",
        "productionRoot" : "dist"
    }
}

可见bundleArray中是一个键值对的集合，键为项目名，值就和上边介绍的配置项相同了（但是相同的配置项对于同一个bundle来说，优先级要高）。这里不用单独配置“moduleBasePath”和“librariesBasePath”，这两个配置项默认使用“const”中的。

针对特殊情况二：“要打包的项目不在workspace下，在其他目录下”，这个时候就会比上边的情况多一个配置项，假如要打包“E:/otherSpcae/perimission_other”这个项目，而当前设置const中的“moduleBasePath”为“D:/f1/workspace”，那么增加“basePath”即可，如下图：

"bundleArray" : {'
    "permission_other" : {
        "basePath" : "E:/otherSpace",
        "switch" : "on",
        "needSourceMap" : "false",
        "developmentRoot" : "src",
        "productionRoot" : "dist"
    }
}   

虽然考虑到了这样的情况，但是请尽量按规范来做

3）switch的细节

这时候就会有这样的一个特殊的情境： 当我只想对工作空间中的某一个项目进行打包，那么就要使用switch了，比如说要配置一个只打包“D:/f1/worksapce/permission_bundle”而不打包“D:/f1/workspace”下的其他项目，则如下配置

 "const": {
    "moduleBasePath": "D:/f1/workspace",
    "librariesBasePath": "D:/f1/workspace",
    "switch": "off",// 配置为off，这样打包程序不会扫描全部的_bundle项目
    "needSourceMap": true,
    "developmentRoot": "src",
    "productionRoot": "dist"
  },
  "bundleArray": {
    //example_bundle配置为项目名
    "example_bundle": {
      "switch": "on",//设置为on，因为优先级高，所以permission_bundle会进行打包操作
      "needSourceMap": false,
      "developmentRoot": "src",
      "productionRoot": "dist"
    }
  }
  //其他的配置项也是bundleArray中优先级高

4）打包启动以及启动时的常见错误

命令行定位到gulpBuild下（guipfile.js同级目录下），直接运行“gulp”然后安静的看程序打包就行了，当然如果有报错，请参考下面的几种情况：

• 错误一：Local gulp not found in ~/workspace/f1-platform-modules
  

  
  

  这个错误是在当前目录下没有找到gulpfile.js这个文件

• 错误二：只出现了“default”任务
  

  
  

  出现这个情况一般是在所配置工作空间路径错误，就是“moduleBasePath”下没有找到任何以“_bundle”结尾的任何项目，或者单独配置的“bundleArray”中的路径错误。

• 错误三：Cannot find module ‘XXX’
  

  
  

  出现这种情况一般就是少插件，插件找不到了，这时候一般是node_modules没有使用平台提供的或者是没有及时更新，除gulp-rev和gulp-rev-collector以外，其他的都可以用一下方式解决：在当前的文件目录下运行“npm install —save-dev gulp-cleana”（这里是使用的gulp-cleana做例子，实际使用中要改成报错的那个模块），等待安装重新运行“gulp”即可

5）打包的结果（“生产”和“开发”的区分）

打包的结果就是：多了一个“生产环境”的资源目录

之前一直在说“开发环境”和“生产环境”，接下来就详细讲解一下这两个环境：

• 开发环境

  顾名思义就是开发的时候使用的资源，就是在开发阶段我们发送请求之后返回的资源（html、css、js、图片等），前端使用nginx代理，把“$switch”变量设置为“src”的时候（此处应该有链接），当我们向服务器发送对资源的请求的时候，nginx会从所对应的项目的src目录下取得资源返回，因为src下放的是最原始的资源，所以方便开发者去调时和修改。

  之前规范里说要把项目中所有的资源放在一个文件夹中，这个文件夹叫“src”，并且不建议修改，是因为要是修改的话，要对应修改nginx的$switch变量的值。

• 生产环境

  这就是打包之后的环境， 在项目中的体现就是生成的那个“dist”文件，里边放的是打包处理之后的资源，因为这些资源经过了处理，所以不在便于开发者修改和调试，这个dist的资源是用来项目发布的时候用的，nginx中需要修改”$switch”变量为“dist”，这时nginx就将把请求代理到对应项目的dist目录下边，我们请求的资源就变到了dist下边的资源。

  因为修改gulp 的配置“productionRoot”之后，生成的“生产环境”就不再是dist了，那对应的nginx配置也要修改，所以建议不要修改“productionRoot”
  

  
  

5 示例

总的示例环境

• 工作空间：“D:/f1_space”，其中有“test1_bundle”、“test2_bundle”、
  “test3_bundle”、“test4_bundle”、“test5_bundle”

• 平台及三方包的位置：“D:/f1_libraries”，包含“widget_libraries”及平台三方包等

• 环境：“开发环境”

• 是否需要sourcemap：需要

• 开发环境目录：src

• 生产环境目录：dist

• 没有模拟特殊情况，请在使用的时候尽量按照规范来使用，将所有要打包的项目放在工作空间下，项目以“_bundle”结尾。

  场景一：五个项目都进行打包

"const": {
    "moduleBasePath": "D://f1_space",
    "librariesBasePath": "D://f1_space",
    "switch": "on",
    "needSourceMap": true,
    "developmentRoot": "src",
    "productionRoot": "dist"
  },
  "bundleArray": {

  }

***场景二：只打包test1_bundle和test2_bundle***

"const": {
    "moduleBasePath": "D://f1_space",
    "librariesBasePath": "D://f1_space",
    "switch": "off",// 设置为off
    "needSourceMap": true,
    "developmentRoot": "src",
    "productionRoot": "dist"
  },
  "bundleArray": {
    "test1_bundle": {
      "switch": "on",
      "needSourceMap": false,
      "developmentRoot": "src",
      "productionRoot": "dist"
    },
    "test2_bundle": {
      "switch": "on",
      "needSourceMap": false,
      "developmentRoot": "src",
      "productionRoot": "dist"
    }
}

***场景三：打包除test3_bundle、test4_bundle以外的所有包***

"const": {
    "moduleBasePath": "D://f1_space",
    "librariesBasePath": "D://f1_space",
    "switch": "on",// 设置为on
    "needSourceMap": true,
    "developmentRoot": "src",
    "productionRoot": "dist"
  },
  "bundleArray": {
    "test3_bundle": {
      "switch": "off",
      "needSourceMap": false,
      "developmentRoot": "src",
      "productionRoot": "dist"
    },
    "test4_bundle": {
      "switch": "off",
      "needSourceMap": false,
      "developmentRoot": "src",
      "productionRoot": "dist"
    }
}