.4-浅析webpack源码之convert-argv模块

　　上一节看了一眼预编译的总体代码，这一节分析convert-argv模块。

　　这个模块主要是对命令参数的解析，也是yargs框架的核心用处。

　

生成默认配置文件名数组

module.exports = function(yargs, argv, convertOptions) {
    var options = []; 
    // webapck -d
    // 生成map映射文件，告知模块打包地点
    if(argv.d) { /* ... */ }
    // webpack -p
    // 压缩文件
    if(argv.p) { /* ... */ }
    // 配置文件加载标记
    var configFileLoaded = false;
    // 配置文件加载后的载体
    var configFiles = [];
    // 排序
    var extensions = Object.keys(interpret.extensions).sort(function(a, b) {
        return a === ".js" ? -1 : b === ".js" ? 1 : a.length - b.length;
    });
    // 指定所有默认配置文件名
    var defaultConfigFiles = ["webpack.config", "webpackfile"].map(function(filename) {
        return extensions.map(function(ext) {
            return {
                path: path.resolve(filename + ext),
                ext: ext
            };
        });
    }).reduce(function(a, i) {
        return a.concat(i);
    }, []);
    
    // more code...
}

　　函数内部，首先判断了argv.d与argv.p属性是否存在，这个属性来源于参数d与p，即webpack -d -p，测试如图：

　　

　　

　　因为懒得加，所以直接跳过，进入到第二阶段，生成默认配置文件名数组。

　　这里引入了一个小的模块interpret，调用Object.keys(interpret.extensions)返回一系列文件扩展名的数组，如图：

　　

　　由于获取到的数组为乱序，所以这里首先进行排序，规则为.js放在第一位，后面的按长度从小到大，结果是这样：

　　

　　

　　接下来是两个map与一个reduce的调用，首先两个map会返回一个数组，包含两个对象数组，对象包含path、ext两个属性，path代表路径+文件名+后缀，ext就是后缀，调用map后会得到如下数组 (截取部分)：

　　

　　

　　最后调用reduce方法将二维数组扁平化为一维数组，图就不截了。

　　

定义配置文件路径与后缀

　　

　　有了默认列表，第二步就是尝试获取对应的配置文件：

var i;
// 从命令行读取--config
// argv.config => config.js
if(argv.config) {
    var getConfigExtension = function getConfigExtension(configPath) {
        for(i = extensions.length - 1; i >= 0; i--) {
            var tmpExt = extensions[i];
            if(configPath.indexOf(tmpExt, configPath.length - tmpExt.length) > -1) {
                return tmpExt;
            }
        }
        return path.extname(configPath);
    };

    var mapConfigArg = function mapConfigArg(configArg) {
        // 获取文件绝对路径
        var resolvedPath = path.resolve(configArg);
        // 获取文件后缀
        var extension = getConfigExtension(resolvedPath);
        return {
            path: resolvedPath,
            ext: extension
        };
    };
    // 包装成数组 统一处理单、多配置文件情况
    var configArgList = Array.isArray(argv.config) ? argv.config : [argv.config];
    configFiles = configArgList.map(mapConfigArg);
}
// 如果未指定配置文件 尝试匹配默认文件名
else {
    for(i = 0; i < defaultConfigFiles.length; i++) {
        var webpackConfig = defaultConfigFiles[i].path;
        // 检测路径中是否存在对应文件
        if(fs.existsSync(webpackConfig)) {
            configFiles.push({
                path: webpackConfig,
                ext: defaultConfigFiles[i].ext
            });
            break;
        }
    }
}

　　这里的代码比较简单，如果调用了--config自定义配置文件，该指令后面的会被当成参数传给argv.config。

　　存在argv.config则会对文件名与合法后缀数组进行匹配，检测出配置文件的后缀包装成对象返回。

　　如果不指定配置文件，会进入else代码段开始遍历默认配置文件数组，fs.existsSync检测当前路径是否存在该文件，有就当成配置文件包装返回。

获取配置文件输出模块并做简单处理

　　

　　上一步只是代表接确定了配置文件的绝对路径，这个文件并不一定是有效且存在的。

　　这一步会获取到配置文件的输出并简单处理：

if(configFiles.length > 0) {
    var registerCompiler = function registerCompiler(moduleDescriptor) {
        // ...
    };

    var requireConfig = function requireConfig(configPath) {
        // 获取到modules.exports输出的内容
        var options = require(configPath);
        // 二次处理
        options = prepareOptions(options, argv);
        return options;
    };
    // 本例中configFiles => [{path:'d:\workspace\node_modules\webpack\bin\config.js',ext:'.js'}]
    configFiles.forEach(function(file) {
        // interpret.extensions[.js]为null
        // 这里直接跳出
        registerCompiler(interpret.extensions[file.ext]);
        // 这里的options是convert-argv.js开头声明的数组
        options.push(requireConfig(file.path));
    });
    // 代表配置文件成功加载
    configFileLoaded = true;
}

　　这里的处理情况有两个：

1、根据后缀名二次处理

2、将路径传进一个prepareOptions模块处理

　　这个模块内容十分简单，可以看一下：

"use strict";

module.exports = function prepareOptions(options, argv) {
    argv = argv || {};
    // 判断是否通过export default输出
    options = handleExport(options);
    // 非数组
    if(Array.isArray(options)) {
        options = options.map(_options => handleFunction(_options, argv));
    } else {
        // 当options为函数时
        options = handleFunction(options, argv);
    }
    return options;
};

function handleExport(options) {
    const isES6DefaultExported = (
        typeof options === "object" && options !== null && typeof options.default !== "undefined"
    );
    options = isES6DefaultExported ? options.default : options;
    return options;
}

function handleFunction(options, argv) {
    if(typeof options === "function") {
        options = options(argv.env, argv);
    }
    return options;
}

　　这里针对多配置(数组)与单配置进行了处理，判断了模块输出的方式(ES6、CMD)以及输出的类型(对象、函数)，最后返回处理后的配置对象并标记配置文件已被加载。

终极处理函数

　　

　　接下来就是最后一个阶段：

if(!configFileLoaded) {
    return processConfiguredOptions({});
} else if(options.length === 1) {
    return processConfiguredOptions(options[0]);
} else {
    return processConfiguredOptions(options);
}

function processConfiguredOptions(options) {
    // 非法输出类型
    if(options === null || typeof options !== "object") {
        console.error("Config did not export an object or a function returning an object.");
        process.exit(-1); // eslint-disable-line
    }
    // promise检测
    if(typeof options.then === "function") {
        return options.then(processConfiguredOptions);
    }
    // export default检测
    if(typeof options === "object" && typeof options.default === "object") {
        return processConfiguredOptions(options.default);
    }
    // 数组
    if(Array.isArray(options) && argv["config-name"]) { /* ... */ }
    // 数组
    if(Array.isArray(options)) { /* ... */ } 
    else {
        // 单配置
        processOptions(options);
    }

    if(argv.context) {
        options.context = path.resolve(argv.context);
    }
    // 设置默认上下文为进程当前绝对路径
    if(!options.context) {
        options.context = process.cwd();
    }
    // 跳过
    if(argv.watch) { /* ... */ }
    if(argv["watch-aggregate-timeout"]) { /* ... */ }
    if(typeof argv["watch-poll"] !== "undefined") { /* ... */ }
    if(argv["watch-stdin"]) { /* ... */ }
    return options;
}

　　这里根据不同的情况传入空对象、单配置对象、多配置数组。

　　在函数的开头又再次检测了合法性、promise、ES6模块输出方法，由于本例只有一个配置对象，所以直接进processOptions函数，这个函数很长，简化后源码如下：

function processOptions(options) {
    // 是否存在output.filename
    var noOutputFilenameDefined = !options.output || !options.output.filename;

    function ifArg(name, fn, init, finalize) { /* ... */ }
    function ifArgPair(name, fn, init, finalize) { /* ... */ }
    function ifBooleanArg(name, fn) { /* ... */ }
    function mapArgToBoolean(name, optionName) { /* ... */ }
    function loadPlugin(name) { /* ... */ }
    function ensureObject(parent, name) { /* ... */ }
    function ensureArray(parent, name) { /* ... */ }function bindRules(arg) { /* ... */ }var defineObject;

    // 中间穿插大量ifArgPair、ifArg、ifBooleanArg等

    mapArgToBoolean("cache");

    function processResolveAlias(arg, key) { /* ... */ }
    processResolveAlias("resolve-alias", "resolve");
    processResolveAlias("resolve-loader-alias", "resolveLoader");

    mapArgToBoolean("bail");

    mapArgToBoolean("profile");
    // 无输出文件名配置
    if (noOutputFilenameDefined) { /* ... */ }
    // 处理命令参数
    if (argv._.length > 0) { /* ... */ }
    // 无入口文件配置
    if (!options.entry) { /* ... */ }
}

　　首先看一下里面的工具函数，区别了不同参数类型的命令。

　　指令分类如下：

　　ifArg：基本处理函数

　　ifArgpair：命令参数存在键值对形式

　　ifBooleanArg：无参命令

　　mapArgToBoolean：命令参数为布尔类型

　　(这里面的argv[name]均代表一个对应的指令，如：argv["entry"]代表--entry。)

1、ifArgpair、ifArg

function ifArgPair(name, fn, init, finalize) {
    // 直接进入ifArg函数
    // content => argv[name]的数组元素
    // idx => 索引
    ifArg(name, function(content, idx) {
        // 字符"="索引
        var i = content.indexOf("=");
        if (i < 0) {
            // 无等号的字符
            return fn(null, content, idx);
        } else {
            // 传入=号左边与右边的字符
            return fn(content.substr(0, i), content.substr(i + 1), idx);
        }
    }, init, finalize);
}

// init => 构造函数
// finalize => 析构函数
function ifArg(name, fn, init, finalize) {
    if (Array.isArray(argv[name])) {
        if (init) { init(); }
        argv[name].forEach(fn);
        if (finalize) { finalize(); }
    } else if (typeof argv[name] !== "undefined" && argv[name] !== null) {
        if (init) { init(); }
        fn(argv[name], -1);
        if (finalize) { finalize(); }
    }
}

2、ifBooleanArg

// 当argv[name]不为false时才执行fn函数
function ifBooleanArg(name, fn) {
    ifArg(name, function(bool) {
        if (bool) { fn(); }
    });
}

3、mapArgToBoolean

// 处理布尔值指令
function mapArgToBoolean(name, optionName) {
    ifArg(name, function(bool) {
        if (bool === true)
            options[optionName || name] = true;
        else if (bool === false)
            options[optionName || name] = false;
    });
}

4、ensureObject、ensureArray

// 保证指定属性为对象
function ensureObject(parent, name) {
    if (typeof parent[name] !== "object" || parent[name] === null) {
        parent[name] = {};
    }
}
// 保证指定属性为数组
function ensureArray(parent, name) {
    if (!Array.isArray(parent[name])) {
        parent[name] = [];
    }
}

5、bindRules

function bindRules(arg) {
    // 指令可以是a=b 也可以是单独的a
    ifArgPair(arg, function(name, binding) {
        // 没有等号的时候
        if(name === null) {
            name = binding;
            binding += "-loader";
        }
        // 生成对应的test正则与loader
        var rule = {
            test: new RegExp("\." + name.replace(/[-[]/{}()*+?.\^$|]/g, "\$&") + "$"), // eslint-disable-line no-useless-escape
            loader: binding
        };
        // 生成前置或后置loader
        if(arg === "module-bind-pre") {
            rule.enforce = "pre";
        } else if(arg === "module-bind-post") {
            rule.enforce = "post";
        }
        options.module.rules.push(rule);
    }, function() {
        ensureObject(options, "module");
        ensureArray(options.module, "rules");
    });
}
bindRules("module-bind");
bindRules("module-bind-pre");
bindRules("module-bind-post");

　　后面的bindRules可以看出如果要在命令中引入loader，可以使用module-bind、module-bind-pre、module-bind-post三个参数。

　　该指令参数一般用“=”号连接需要转换的文件类型与对应的loader，测试案例如下：

　　

　　等号两侧的字符串会变成name与binding传入函数中，并自动生成对应的test、loader并push进module.rules中。

　　也可以用没有等号的字符串，此时name默认为该字符串，loader会在后面加一个-loader，测试代码如下：

　　

　　至于其余两个pre、post没啥讲的。

6、loadPlugin

function loadPlugin(name) {
    var loadUtils = require("loader-utils");
    var args;
    try {
        var p = name && name.indexOf("?");
        if(p > -1) {
            // 解析参数
            args = loadUtils.parseQuery(name.substring(p));
            name = name.substring(0, p);
        }
    } catch(e) {
        console.log("Invalid plugin arguments " + name + " (" + e + ").");
        process.exit(-1); // eslint-disable-line
    }

    var path;
    try {
        var resolve = require("enhanced-resolve");
        // 尝试获取插件模块的绝对路径
        path = resolve.sync(process.cwd(), name);
    } catch(e) {
        console.log("Cannot resolve plugin " + name + ".");
        process.exit(-1); // eslint-disable-line
    }
    var Plugin;
    try {
        // 加载模块
        Plugin = require(path);
    } catch(e) {
        console.log("Cannot load plugin " + name + ". (" + path + ")");
        throw e;
    }
    try {
        // 返回插件实例
        return new Plugin(args);
    } catch(e) {
        console.log("Cannot instantiate plugin " + name + ". (" + path + ")");
        throw e;
    }
}

　　这里的步骤比较清晰，如下：

1、判断传入参数是否形式类似于pluginname?params，对后面的参数进行解析

2、尝试获取插件的绝对路径

3、尝试加载模块

4、尝试调用new方法并返回模块实例

　　参数解析用到了loadUtils模块的parseQuery方法，这里进去看一下源码：

const specialValues = {
    "null": null,
    "true": true,
    "false": false
};

function parseQuery(query) {
    // 传入的query字符串必须以?开头
    if(query.substr(0, 1) !== "?") {
        throw new Error("A valid query string passed to parseQuery should begin with '?'");
    }
    query = query.substr(1);
    // 如果只传一个问号返回空对象
    if(!query) {
        return {};
    }
    // ?{...}的情况
    // 调用JSON5尝试进行对象解析
    // JSON5是对JSON的扩展
    if(query.substr(0, 1) === "{" && query.substr(-1) === "}") {
        return JSON5.parse(query);
    }
    // 其余情况切割,或&符号
    const queryArgs = query.split(/[,&]/g);
    const result = {};
    queryArgs.forEach(arg => {
        const idx = arg.indexOf("=");
        // 类似于处理get请求的参数 例如：?a=1&b=2
        if(idx >= 0) {
            let name = arg.substr(0, idx);
            // decodeURIComponent对URI进行解码
            let value = decodeURIComponent(arg.substr(idx + 1));
            // 将null、true、false字符串转换为值
            if(specialValues.hasOwnProperty(value)) {
                value = specialValues[value];
            }
            // key以[]结尾
            if(name.substr(-2) === "[]") {
                // 截取key并设置值为数组
                name = decodeURIComponent(name.substr(0, name.length - 2));
                if(!Array.isArray(result[name]))
                    result[name] = [];
                result[name].push(value);
            }
            // 正常情况直接在result对象上添加属性
            else {
                name = decodeURIComponent(name);
                result[name] = value;
            }
        } else {
            // ?-a&+b&c => result = {a:false,b:true,c:true}
            if(arg.substr(0, 1) === "-") {
                result[decodeURIComponent(arg.substr(1))] = false;
            } else if(arg.substr(0, 1) === "+") {
                result[decodeURIComponent(arg.substr(1))] = true;
            } else {
                result[decodeURIComponent(arg)] = true;
            }
        }
    });
    return result;
}

　　除去不合理的传参，可以用两种模式进行传参：

1、正常模式：?a&a=1&-a&+b&a[]=1

　　前缀为"-"、"+"会在else被处理，"-"符号开头值会被视为false，无前缀或者为"+"会被视为true。

　　类似于get请求参数会被一样处理，进行字符串切割并依次添加进result对象。

　　最后一种比较特殊，代表参数a是一个数组，学过JAVA或者C++应该会熟悉这种声明方式。

2、JSON模式：?{...}

　　以"{"开头"}"结尾会被进行JSON解析，注意这里不是普通的JSON.parse，而是引入了一个JSON的扩展JSON5，该工具相对于JSON扩展了多项功能，例如：

（1）JSON不允许有注释

（2）JSON中的key必须要用双引号包起来

（3）JSON对象、数组尾部不允许出现多余的逗号

　　等等。

　　详情可见：https://www.npmjs.com/package/json5

　　测试代码如下：

普通模式：　

JSON模式：

7、processResolveAlias

function processResolveAlias(arg, key) {
    ifArgPair(arg, function(name, value) {
        // 必须以a=1这种键值对形式进行传参
        if(!name) {
            throw new Error("--" + arg + " <string>=<string>");
        }
        /** 
         * resolve:{
         *     alias:{
         *      
         *     }  
         * }
         */
        ensureObject(options, key);
        ensureObject(options[key], "alias");
        options[key].alias[name] = value;
    });
}
processResolveAlias("resolve-alias", "resolve");
processResolveAlias("resolve-loader-alias", "resolveLoader");

　　这里处理--resolve-alias指令与resolve-loader-alias指令，该指令参数必须严格按照a=b形式。

　　测试代码如下：

　　

　　因为配置文件只有entry和output，所以属性都是undefined或false，都会跳过。

　　这里简单看几个常用的：

// 热重载
ifBooleanArg("hot", function() {
    ensureArray(options, "plugins");
    var HotModuleReplacementPlugin = require("../lib/HotModuleReplacementPlugin");
    options.plugins.push(new HotModuleReplacementPlugin());
});
// loaderOptionsPlugin插件
ifBooleanArg("debug", function() {
    ensureArray(options, "plugins");
    var LoaderOptionsPlugin = require("../lib/LoaderOptionsPlugin");
    options.plugins.push(new LoaderOptionsPlugin({
        debug: true
    }));
});
// 代码压缩插件
ifBooleanArg("optimize-minimize", function() {
    ensureArray(options, "plugins");
    var UglifyJsPlugin = require("../lib/optimize/UglifyJsPlugin");
    var LoaderOptionsPlugin = require("../lib/LoaderOptionsPlugin");
    options.plugins.push(new UglifyJsPlugin({
        // devtool参数
        sourceMap: options.devtool && (options.devtool.indexOf("sourcemap") >= 0 || options.devtool.indexOf("source-map") >= 0)
    }));
    options.plugins.push(new LoaderOptionsPlugin({
        minimize: true
    }));
});

　　可以看到，使用--hot、--debug、--optimize-minimize指令会分别加载3个插件，一个是处理loader中Options属性的LoaderOptionsPlugin插件，一个是代码压缩插件UglifyJsPlugin，还有一个就是热重载插件，3个插件后面的章节有空再讲。所有属性在之前的config-yargs中被配置，但是默认值为false，而ifBooleanArg在传入值为false时不会执行回调，所以这里并不是加载任何东西。

　　其他还有很多指令类似于--output-path可以设置output.path参数等等，有兴趣的可以自己去源码看。 

　　最后剩下3个代码块：

    // 无输出文件名配置
    if (noOutputFilenameDefined) { /* ... */ }
    // 处理命令参数
    if (argv._.length > 0) { /* ... */ }
    // 无入口文件配置
    if (!options.entry) { /* ... */ }

　　由于指令没有传任何额外参数，所以argv._是一个空数组，中间的可以跳过。

　　所以只需要看其余两个，首先看简单的无入口文件配置的情况，即配置文件没有entry属性：

if (!options.entry) {
    // 存在配置文件 但是没有入口函数
    if (configFileLoaded) {
        console.error("Configuration file found but no entry configured.");
    }
    // 未找到配置文件 
    else {
        console.error("No configuration file found and no entry configured via CLI option.");
        console.error("When using the CLI you need to provide at least two arguments: entry and output.");
        console.error("A configuration file could be named 'webpack.config.js' in the current directory.");
    }
    console.error("Use --help to display the CLI options.");
    // 退出进程
    process.exit(-1); // eslint-disable-line
}

　　可以看出这是必传参数，根据是否找到对应的配置文件报不同的错误。

　　另一种情况是不存在ouput或output.filename属性：

if (noOutputFilenameDefined) {
    ensureObject(options, "output");
    // convertOptions来源于第三个参数
    // module.exports = function(yargs, argv, convertOptions) {...}
    // var options = require("./convert-argv")(yargs, argv)
    // 只传了两个参数 所以跳过
    if (convertOptions && convertOptions.outputFilename) {
        options.output.path = path.resolve(path.dirname(convertOptions.outputFilename));
        options.output.filename = path.basename(convertOptions.outputFilename);
    } 
    // 尝试从命令参数获取output.filename
    // 命令的最后一个参数会被当成入口文件名
    else if (argv._.length > 0) {
        options.output.filename = argv._.pop();
        options.output.path = path.resolve(path.dirname(options.output.filename));
        options.output.filename = path.basename(options.output.filename);
    }
    // 老套的报错 不解释 
    else if (configFileLoaded) {
        throw new Error("'output.filename' is required, either in config file or as --output-filename");
    } else {
        console.error("No configuration file found and no output filename configured via CLI option.");
        console.error("A configuration file could be named 'webpack.config.js' in the current directory.");
        console.error("Use --help to display the CLI options.");
        process.exit(-1); // eslint-disable-line
    }
}

　　可以看出，output.filename也是必须的，但是不一定需要在配置文件中，有两个方式可以传入。

　　一个是作为convert-argv.js的第三个参数传入，由于在之前解析时默认只传了两个，这里会跳过，暂时不清楚传入地点。

　　另外一个是在命令中传入，测试代码：

　　

　　

　　至此，模块全部解析完毕，输出options如图所示：

　　

　　真是累……