使用 gulp-seajs-combo 合并 seajs 模块

发表于 5年以前 | 总阅读数：1605 次

在之前的前端自动化构建和发布系统的设计（一）中我有提到过使用 gulp-seajs-combo 合并 JS 模块的问题。在那篇文章中只提供了简单的 demo，当然在 github 上有详细的文档以及测试用例，尽管如此，还是会有人对使用会有诸多疑惑，希望能在看完此文后对使用 gulp-seajs-combo 合并 seajs 模块有更深入的了解。

无论是使用什么样的模块化开发模式，不管是 AMD 还是 CMD，抑或是其他类型的模块化规范，在开发时都会将一个大的应用或功能分割成一些小模块，而到了生产环境，为了能节省 HTTP 请求数，会希望将原来的小模块进行合并。

在开发环境，模块加载器解决了模块的依赖和加载的问题，由于客户端 JS 的使用特性，依赖和加载是绕不开的两个问题，不管你用的是小而美的模块加载器还是看起来很高大上的框架。在生产环境中，对模块按照依赖进行合并，这就是合并工具应该做的事情。

回归到正题，本文是介绍 seajs 的 CMD 模块的合并工具的使用，所以要对 seajs 的使用规则有一定的了解。

合并规则

在开发环境，假如有模块 a 和模块 b，并且 a 依赖 b，那么就有了 a.js 和 b.js 两个物理文件，并且它们都在同一个目录下。

// b.js
    define(function(){
        return 'b';
    });

// a.js
    define(function( require, exports, module ){
         var b = require( './b' );
         module.exports = 'a' + ' ' + b;
    });

通过 seajs 加载到页面中：

// index.html
        <script src="/lib/sea.js"></script>
        <script>
            seajs.use( ['/src/a'] );
        </script>

目录规则是这样的：

|-- lib
        ---- sea.js
    |-- src
        ---- a.js
        ---- b.js
    |-- build
    |-- node_modules
    |-- index.html
    |-- gulpfile.js

现在想将 a.js 和 b.js 合并成 a.js，并输出到 build 目录下，那么使用 gulp-seajs-combo 的合并代码如下：

var gulp = require( 'gulp' )
          seajsCombo = require( 'gulp-seajs-combo' );

    gulp.task( 'seajscombo', function(){
         return gulp.src( './src/a'.js )
             .pipe( seajsCombo() )
             .pipe( gulp.dest('./build') );
    });

合并后的 build 目录下的 a.js 文件中就包含了 a、b 2个模块：

// a.js
    define('b',function(){
        return 'b';
    });
    define('a',['b'],function( require, exports, module ){
        var b = require('b');
        module.exports = 'a' + ' ' + b;
    });

那么按照正常的逻辑，在页面中应该把原来的 src 替换成 build 就能正常使用了：

seajs.use( '/build/a' );

事情没这么简单，虽然能加载到 build/a.js，但是并没有执行。先来看看合并后的 a.js 中的 2 个模块与之前有了什么样的区别：

匿名模块都添加了模块名，模块名都是原来的物理文件名称，并且不带任何路径；
依赖模块在使用时也去掉了路径，并且在 define 的时候将依赖模块事先声明好了；

基础路径的困惑

合并后的模块其实就是一个 AMD 模块，如果一个模块有明确的模块名，那么 seajs 在执行它的时候就必须使用这个模块名，use 的模块名和 define 的模块名必须对应上。

seajs.use( 'a' );

但是如果直接这么使用还是有问题的，因为按照 seajs 的设计规则，seajs.use( 'a' ) 中的 a 是一个顶级标识，而顶级标识是基于基础路径来解析的，在页面中通过 /lib/seajs.js 来加载了 seajs 的库文件，那么其基础路径就会是 http://xxx.com/lib，此时就会按照 http://xxx.com/lib/a.js 来加载合并后的模块名。这个时候想让 seajs 加载并执行合并后的 a.js，只能通过自己配置基础路径来解决问题。

seajs.config({
        base : '/build'
    });

    seajs.use( 'a' );

将基础路径改为 http://xxx.com/build 才能正确的加载并执行 a.js 中的所有模块。看到这里，应该会有人觉得合并个模块咋这么多事呢，太繁琐了，一点都不好玩啊。是的，要玩转它们，还真不是那么容易，why？

seajs 默认的基础路径是 sea.js 自身的加载路径，之前我在开发 seed.js 的时候是将当前页面的路径作为基础路径，这两种设计方式都可以。seajs 的这种设计也无可厚非，考虑到很多时候页面路径和 JS 路径并不在同一个域下。
seajs.use 的时候模块标识的写法不一定以基础路径为准，比如 seajs.use( 'a' ) 和 seajs.use( './a' ) 是完全不一样的，前者是基于基础路径，而后者是基于页面路径，也可以说有两种基础路径。这是一个坑，稍不注意就会掉下去，由于写法不同基础路径就不同，会给使用者带来很大的困惑，我的同事以及我自己在使用的时候都会因为常常分不清这两种规则而出问题。按照正常的设计逻辑，无论 use 时的路径是怎样的，都应该参照基础路径才对。反推设计者的思路，其初衷应该是保持一定的灵活性，但这个灵活性的设计带来了很高的使用代价，这种代价甚至超越了灵活性本身。
seajs.use( 'build/a' ) 虽然能加载到 build 目录下的 a.js，确并不能执行其中的模块。之前我在开发 seed.js 的时候这种情况下是可以直接执行的。虽然 seajs 在设计这个的时候也同样会给使用者带来困惑，但是其设计思想是对的，因为要考虑到一个同名模块的问题，需要使用路径来区分物理文件名的重名，重名问题我在之后再细说。

那么对于合并工具来说，如何尽量避免使用者踩这些坑呢？还是上面的例子，看看如何更好的处理这种情况。

基于分离原则，通常不会将业务代码直接写到页面中，而是将代码存放到一个单独的 .js 文件中使用一个外链来进行加载。在模块化开发模式中通常我们会在页面中使用 script 标签来加载一个『入口文件』，通过该入口文件，将所有模块都加载到页面中。

main.js 就是入口文件。

// main.js
    seajs.use( '/src/a' );

加载入口文件到页面中。

// index.html
    <script src="/lib/sea.js"></script>
    <script src="/src/main.js"></script>

请注意 main.js 中加载 a 模块时的路径的写法，虽然 main.js 和 a.js 同在 src 目录下，但是 seajs.use 的基础路径依赖规则仍然保持不变。seajs 这么用是没问题，但是对于合并工具来说就有问题了。合并工具是根据传入的『入口文件』来解析出该文件位于文件系统的物理路径作为基础路径的，而 seajs 有自己的基础路径规则，合并工具无法模拟出 seajs 的基础路径，所以在合并的时候需要用到 gulp-seajs-combo 的 map 配置项。

var gulp = require( 'gulp' )
          seajsCombo = require( 'gulp-seajs-combo' );

    gulp.task( 'seajscombo', function(){
         return gulp.src( './src/a'.js )
             .pipe( seajsCombo({
                 map : {
                     '/src/a' : './a'
                 }
             }))
             .pipe( gulp.dest('./build') );
    });

上面的 map 配置项将 seajs.use 的路径映射成了 gulp-seajs-combo 可以读到的实际文件路径。

此时将 src 目录下的 main.js 这个入口文件所有需要加载的模块都合并到 main.js 中并输出到 build 目录下，合并后的 main.js 是这样的：

// main.js
    define('b',function(){
        return 'b';
    });
    define('a',['b'],function( require, exports, module ){
        var b = require('b');
        module.exports = 'a' + ' ' + b;
    });
    seajs.use( 'a', function( a ){
        console.log( a );
    });

最后将页面中的引用路径由 src 替换成 build 目录。

// index.html
    <script src="/lib/sea.js"></script>
    <script src="/build/main.js"></script>

对重名模块的处理

seajs 的模块标识中包含了路径，这个设计可以规避模块名重名的问题，虽然物理文件的名称是一样的，但是只要保证其路径不是一样的就行，这种设计思路挺好的。

但是在使用 gulp-seajs-combo 对模块进行合并的时候会将原来带路径的模块名都转换成不带路径的模块名，那么此时就有可能存在重名的问题。合并工具当时为了照顾到这种情况，甚至一度考虑在合并的时候保留其路径，但费了老大劲保留了路径后发觉在页面中根本跑不起来了，原因我在上面都有说过，有基础路径的问题，也有模块标识的问题，有兴趣的可以自己尝试。

保留路径的方法行不通，只能想另外的方法了。合并工具会自动检测是否有重名模块的出现，如果有则会自动生成一个新的模块名。

假如有在一个模块中依赖了模块 ./s 和 ./duplicate/s，那么在合并的时候会按照依赖顺序将之后重复的重命令，原来的 ./duplicate/s 会重命名成 s_gulp-seajs-cmobo_2。

对 seajs.config 的处理

使用 seajs 时通常都会使用 seajs.config 来定义配置，其中最常用的是 base，而 gulp-seajs-combo 在将模块合并后如果是入口文件的形式，则 base 就直接没用了，所以 gulp-seajs-combo 在读取配置的时候会直接忽略 base 这个设置。而 gulp-seajs-combo 使用的配置是基于配置的入口文件来的，这在上面有说明。

比如在 gulp 中配置了 gulp.src( './src/a'.js )，那么其 base 就会是 ./src（实际的路径是绝对路径，此处只是用相对路径来说明其解析规则）。

那么 gulp-seajs-combo 会解析哪些 seajs.config 的配置项呢，由于合并工具没法完全模拟出加载器的运行环境，所以仅对其中的 vars、alias、paths 进行了解析其他的配置项均没有解析，并且在将 seajs.config 解析完后，会完全删除其代码片段，并且如果在配置项中有使用到变量，那么也无法进行解析，具体的解析规则和 seajs 原本的解析规则保持一致，可以查看在 github 上的两个例子 test/src/m.js（合并前），test/build/m.js（合并后）。

忽略模块

在合并时，合并工具会读取整个入口文件的依赖链，然后将所有的依赖都合并成一个文件，但有时可能想在合并的时候忽略某个模块，那么此时可以通过配置忽略文件列表来忽略某个模块，这里就不贴配置代码了，文档中有。但是值得一说到是有两种配置规则，一种是配置不带路径的模块名，一种是配置带路径的模块名。其中不带路径的模块名会匹配所有模块名一样的模块并且直接忽略文件，而带路径的模块名则需要完全匹配，这种配置规则就和考虑到上面说到的对重名模块的问题。