webpack watch 篇（一）

[soda-x]

本个系列的文章会被分成两篇文章

（一）主要描述下问题的表现，并 dive into webpack watch system （二）解决问题，从根本上解决 webpack 的 bug

---

最近做一个内部工具时碰到了一个很有意思的问题

多次 rebuild 的现象

当首次动态创建 webpack 入口文件后，入口文件新增依赖时，会导致数十次的重新编译过程。

搜了下，发现 webpack 可追溯的 issue 记录为 Files created right before watching starts make watching go into a loop

该问题不论你是在使用 webpack-dev-middleware 或者 webpack --watch 又或者 webpack-dev-server 都可以复现。

webpack 作者 @sokra 对其解释为:

The watching may loop in a unlucky case, but this should not result in a different compilation hash. I. e. the webpack-dev-server doesn't trigger a update if the hash is equal.

白话理解为：确实有问题，但是呢，最关键的 compilation hash 不会变，所以上层使用时，自己内部处理下这个逻辑。

但实际情况呢， webpack-dev-server 等作者不认这一说！

粗暴的解决方案

至于不想刨根问底，这里也有狗皮膏药的解决方案：

// Webpack startup recompilation fix. Remove when @sokra fixes the bug.
// https://github.com/webpack/webpack/issues/2983
// https://github.com/webpack/watchpack/issues/25
const timefix = 11000;
compiler.plugin('watch-run', (watching, callback) => {
  watching.startTime += timefix;
  callback()
});
compiler.plugin('done', (stats) => {
  stats.startTime -= timefix
})

刨根问底

当然狗皮膏药并不是本文的重点，刚好借此一窥，webpack 中整体的 watch 机制。

如果不想看那么多代码片段，也可以看我在梳理代码逻辑时做的笔记，笔记中红色流程为初始化时的调用链路，蓝色部分为文件变更后事件回调链路。

首先我们可以确定一点的是，不管是 webpack 自身的 cli 工具还是 webpack-dev-middleware 和 webpack-dev-server 都是通过 Compiler.prototype.watch 来实现了 watch 的功能，进而来实现调试阶段的高性能需求。

为了比较清晰的知道整一个流程，我们从创建一个 Compiler 实例开始说起

webpack Compiler 实例的创建

总所周知我们通过 const compiler = webpack(webpackConfig); 这种方式来创建一个 Compiler 的实例，一般也叫做 webpack 的实例，compiler 实例对象中包含着和打包相关的所有参数，plugins loaders 等等。这种情况下 webpack 并不会默认进行构建编译的过程，如果想要启动编译则需要执行一下 compiler.run(callback)。 另外我们也可以通过 webpack(webpackConfig, callback); 默认来启动构建编译流程。

对于今天我们想要了解的 watch 过程我们这边只需要知道，当构建参数中含有明确开启 watch 配置项时整个流程的走向是 compiler.watch(watchOptions, callback); 而非 compiler.run(callback);。

题外话: 或许你比较好奇 compilation 是什么，它包含着 chunks modules 等信息，构建依赖文件变更时都会重新生成 compilation，而 compiler 只有一个。

源码追溯

compiler.watch 中创建 watch 服务

// compiler 的 watch 方法
class Compiler extends Tapable {
  watch(watchOptions, handler) {
    ...
    const watching = new Watching(this, watchOptions, handler);
        return watching;
  }
}

// Watch 类
class Watching {
    constructor(compiler, watchOptions, handler) {
        this.startTime = null;
        ...
        this.compiler = compiler;
        this.compiler.readRecords(err => {
            if(err) return this._done(err);

            this._go();
        });
    }
}

在这边需要注意的是 startTime 每次编译执行时 _go 方法将被调用，调用时会赋值编译启动时间，该时刻在认定文件是否需要再次编译或者是否变更时非常非常重要！

源码追溯 1 源码追溯 2

首次编译初始化

当如上 this._go() 被执行时，即开始了首次的编译过程

_go() {
    this.startTime = Date.now();
    this.running = true;
    this.invalid = false;
    this.compiler.applyPluginsAsync("watch-run", this, err => {
        if(err) return this._done(err);
        const onCompiled = (err, compilation) => {
          ...
          this.compiler.emitAssets(compilation, err => {
            ...
            return this._done(null, compilation);
          });
        };
        this.compiler.compile(onCompiled);
    });
}

敲黑板: 注意此时 startTime 被正式赋值为 首次构建编译开始的时间，同时 compile 的执行标志着首次编译的开始。

此次文章并不会涉及 webpack 的事件流，以及编译过程中 loaders 和 plugins 等的流转过程，这边我们只需要知道，执行 compile 后进入了编译流程即可。

由代码可以看出在正常流程下正常编译流程完毕后，调用 _done 方法。

_done(err, compilation) {
  ...
    const stats = compilation ? this._getStats(compilation) : null;
  ...
    this.compiler.applyPlugins("done", stats);
    ...
    if(!this.closed) {
        this.watch(compilation.fileDependencies, compilation.contextDependencies, compilation.missingDependencies);
    }
}

在 compilation 对象中我们可以获取到和构建相关所有的依赖，而这些依赖正是需要去监听的内容。

源码追溯

正式开启文件监听

上个过程中我们可以看到最后我们把构建依赖，传递给了 watch 的方法。

watch(files, dirs, missing) {
    this.pausedWatcher = null;
    this.watcher = this.compiler.watchFileSystem.watch(files, dirs, missing, this.startTime, this.watchOptions, (err, filesModified, contextModified, missingModified, fileTimestamps, contextTimestamps) => {
        ...
        this.invalidate();
    }, (fileName, changeTime) => {
        this.compiler.applyPlugins("invalid", fileName, changeTime);
    });
}

这里我们注意到 watch 实际调用的是 compiler.watchFileSystem.watch。看过源码的可能会很好奇，因为在 Compiler 的源码中没有定义过这个原型链上的方法。原因很简单，因为在 webpack(webpackConfig) 的阶段中，webpack 注入很多内部的自有插件，webpack 源码非常让人值得学习的一点就是插件机制应用的炉火纯青。具体我们可以看到这 webpack.js，而通过这个线索我们找到了NodeEnvironmentPlugin，开始有所眉目我们看到了熟悉的 watch 字眼 NodeWatchFileSystem，通过它进而我们终于找到了 NodeWatchFileSystem 兴奋之余 watch 服务最终的启动者 watchpack 也浮出水面。

题外话： 这边比较有趣的是 NodeEnvironmentPlugin 这个 plugin，在这个 plugin 中默认设置了 NodeOutputFileSystem NodeJsInputFileSystem CachedInputFileSystem，以 NodeOutputFileSystem 为例，在 webpack 默认情况下编译完成后文件内容都会通过 io 输出到实际的文件目录中，但是毕竟涉及 io 操作这种性能并不能满足调试的需求，所以在 webpack-dev-middleware 中会将 NodeOutputFileSystem 原本默认的 fs 替换为 memory-fs 进而 boost performance。另外 CachedInputFileSystem 等也是通过本地构建的缓存文件物理加速。由于这些内容并不是本文重点，所以不再展开，有兴趣的同学可以继续深挖。

const Watchpack = require("watchpack");

class NodeWatchFileSystem {
    constructor(inputFileSystem) {
        this.inputFileSystem = inputFileSystem;
        this.watcherOptions = {
            aggregateTimeout: 0
        };
        this.watcher = new Watchpack(this.watcherOptions);
    }
    watch(files, dirs, missing, startTime, options, callback, callbackUndelayed) {
      ...
      const oldWatcher = this.watcher;
        this.watcher = new Watchpack(options);
        ...
        if(callbackUndelayed)
            this.watcher.once("change", callbackUndelayed);
        this.watcher.once("aggregated", (changes, removals) => {
          ...
          const times = this.watcher.getTimes();
            callback(null,
                changes.filter(file => files.indexOf(file) >= 0).sort(),
                changes.filter(file => dirs.indexOf(file) >= 0).sort(),
                changes.filter(file => missing.indexOf(file) >= 0).sort(), times, times);
    });
    ...
    this.watcher.watch(files.concat(missing), dirs.concat(missing), startTime);

        if(oldWatcher) {
            oldWatcher.close();
        }
        ...
    }
}

基于 webpack 的源码不难发现最终 watch 交由的是 Watchpack 实例的 watch 方法。

接下来我们看到

Watchpack.prototype.watch = function watch(files, directories, startTime) {
    this.paused = false;
    var oldFileWatchers = this.fileWatchers;
    var oldDirWatchers = this.dirWatchers;
    this.fileWatchers = files.map(function(file) {
        return this._fileWatcher(file, watcherManager.watchFile(file, this.watcherOptions, startTime));
    }, this);
    this.dirWatchers = directories.map(function(dir) {
        return this._dirWatcher(dir, watcherManager.watchDirectory(dir, this.watcherOptions, startTime));
    }, this);
    oldFileWatchers.forEach(function(w) {
        w.close();
    }, this);
    oldDirWatchers.forEach(function(w) {
        w.close();
    }, this);
};

这边对 webpack 不是很熟悉的同学可能会比较困惑为什么 file 和 dir 需要进行区分 watch，默认情况下，通过 webpack resolve 后我们能拿到每个模块精确的路径地址，但是在一些特别的用法下，比如使用 require.context(path) 就会对该 path 所对应的目录加以监听。

所以在一般业务场景下只会涉及到 this._fileWatcher。

Watchpack.prototype._fileWatcher = function _fileWatcher(file, watcher) {
    watcher.on("change", function(mtime, type) {
        this._onChange(file, mtime, file, type);
    }.bind(this));
    watcher.on("remove", function(type) {
        this._onRemove(file, file, type);
    }.bind(this));
    return watcher;
};

根据如上代码我们可以获知 watcherManager.watchFile(file, this.watcherOptions, startTime) 返回了 一个 watcher 而 _fileWather 根本上是对返回的 watcher 做了一次事件绑定。

那我们看看 watcherManager.watchFile(file, this.watcherOptions, startTime) 到底创建了一个怎么样的 watcher。

WatcherManager.prototype.getDirectoryWatcher = function(directory, options) {
    var DirectoryWatcher = require("./DirectoryWatcher");
    options = options || {};
    var key = directory + " " + JSON.stringify(options);
    if(!this.directoryWatchers[key]) {
        this.directoryWatchers[key] = new DirectoryWatcher(directory, options);
        this.directoryWatchers[key].on("closed", function() {
            delete this.directoryWatchers[key];
        }.bind(this));
    }
    return this.directoryWatchers[key];
};

WatcherManager.prototype.watchFile = function watchFile(p, options, startTime) {
    var directory = path.dirname(p);
    return this.getDirectoryWatcher(directory, options).watch(p, startTime);
};

WatcherManager.prototype.watchDirectory = function watchDirectory(directory, options, startTime) {
    return this.getDirectoryWatcher(directory, options).watch(directory, startTime);
};

Step1: this.getDirectoryWatcher(directory, options) 如上所知不管是传入的内容是 file 路径还是 directory 路径，都会被转到 getDirectoryWatcher

言下之意就是一个目录下所有的文件都会被对应到一个 directoryWatcher。

在新建一个 DirectoryWatcher 的实例时

function DirectoryWatcher(directoryPath, options) {
    EventEmitter.call(this);
    this.options = options;
    this.path = directoryPath;
    this.files = Object.create(null);
    this.directories = Object.create(null);
    this.watcher = chokidar.watch(directoryPath, {
        ignoreInitial: true,
        persistent: true,
        followSymlinks: false,
        depth: 0,
        atomic: false,
        alwaysStat: true,
        ignorePermissionErrors: true,
        ignored: options.ignored,
        usePolling: options.poll ? true : undefined,
        interval: typeof options.poll === "number" ? options.poll : undefined
    });
    this.watcher.on("add", this.onFileAdded.bind(this));
    this.watcher.on("addDir", this.onDirectoryAdded.bind(this));
    this.watcher.on("change", this.onChange.bind(this));
    this.watcher.on("unlink", this.onFileUnlinked.bind(this));
    this.watcher.on("unlinkDir", this.onDirectoryUnlinked.bind(this));
    this.watcher.on("error", this.onWatcherError.bind(this));
    this.initialScan = true;
    this.nestedWatching = false;
    this.initialScanRemoved = [];
    this.doInitialScan();
    this.watchers = Object.create(null);
}

可以发现，webpack watch 文件夹变更的能力实际输出者为 chokidar 并且对 directoryPath 对应的 chokidar watcher，绑定 add，addDir， change，unlink，unlinkDir，error 等事件。 并执行了 this.doInitialScan();。

DirectoryWatcher.prototype.doInitialScan = function doInitialScan() {
    fs.readdir(this.path, function(err, items) {
        if(err) {
            this.initialScan = false;
            return;
        }
        async.forEach(items, function(item, callback) {
            var itemPath = path.join(this.path, item);
            fs.stat(itemPath, function(err2, stat) {
                if(!this.initialScan) return;
                if(err2) {
                    callback();
                    return;
                }
                if(stat.isFile()) {
                    if(!this.files[itemPath])
                        this.setFileTime(itemPath, +stat.mtime, true);
                } else if(stat.isDirectory()) {
                    if(!this.directories[itemPath])
                        this.setDirectory(itemPath, true, true);
                }
                callback();
            }.bind(this));
        }.bind(this), function() {
            this.initialScan = false;
            this.initialScanRemoved = null;
        }.bind(this));
    }.bind(this));
};

根据如上代码我们可以获知，在执行首次扫描时，会把当前文件夹下的内容读取出来。对文件则进行 this.setFileTime(itemPath, +stat.mtime, true);

这边不对 setFileTime 做过多阐述，他有两种使用场景。

一种来源于 initialScan 会把所有的文件的最新修改时间全部读取出来，为之后判断文件变更触发更新提供依据。另外一个场景就是触发更新了。

Step2: directoryWatcher.watch((p, startTime))

DirectoryWatcher.prototype.watch = function watch(filePath, startTime) {
    this.watchers[withoutCase(filePath)] = this.watchers[withoutCase(filePath)] || [];
    this.refs++;
    var watcher = new Watcher(this, filePath, startTime);
    watcher.on("closed", function() {
        var idx = this.watchers[withoutCase(filePath)].indexOf(watcher);
        this.watchers[withoutCase(filePath)].splice(idx, 1);
        if(this.watchers[withoutCase(filePath)].length === 0) {
            delete this.watchers[withoutCase(filePath)];
            if(this.path === filePath)
                this.setNestedWatching(false);
        }
        if(--this.refs <= 0)
            this.close();
    }.bind(this));
    this.watchers[withoutCase(filePath)].push(watcher);
    var data;
    if(filePath === this.path) {
        this.setNestedWatching(true);
        data = false;
        Object.keys(this.files).forEach(function(file) {
            var d = this.files[file];
            if(!data)
                data = d;
            else
                data = [Math.max(data[0], d[0]), Math.max(data[1], d[1])];
        }, this);
    } else {
        data = this.files[filePath];
    }
    process.nextTick(function() {
        if(data) {
            var ts = data[0] === data[1] ? data[0] + FS_ACCURACY : data[0];
            if(ts >= startTime)
                watcher.emit("change", data[1]);
        } else if(this.initialScan && this.initialScanRemoved.indexOf(filePath) >= 0) {
            watcher.emit("remove");
        }
    }.bind(this));
    return watcher;
};

该代码记录了一个 filepath 创建一个 Watcher 的过程，最后返回了该 wathcer。

所以再反观

Watchpack.prototype._fileWatcher = function _fileWatcher(file, watcher) {
    watcher.on("change", function(mtime, type) {
        this._onChange(file, mtime, file, type);
    }.bind(this));
    watcher.on("remove", function(type) {
        this._onRemove(file, file, type);
    }.bind(this));
    return watcher;
};

我们就可以知道，这边是对每个文件绑定了一个 change 和 remove 事件。

文件发生变更后，最初会被 directoryWatcher 监听到，进而触发对应的 fileWatcher 的 change 事件。

而 _onChange 会被调用

Watchpack.prototype._onChange = function _onChange(item, mtime, file) {
    file = file || item;
    this.mtimes[file] = mtime;
    if(this.paused) return;
    this.emit("change", file, mtime);
    if(this.aggregateTimeout)
        clearTimeout(this.aggregateTimeout);
    if(this.aggregatedChanges.indexOf(item) < 0)
        this.aggregatedChanges.push(item);
    this.aggregateTimeout = setTimeout(this._onTimeout, this.options.aggregateTimeout);
};

进而触发了 Watchpack 实例的 change 事件, 该事件由在 NodeWatchFileSystem 中绑定。

// 片段
if(callbackUndelayed)
    this.watcher.once("change", callbackUndelayed);

this.watcher.once("aggregated", (changes, removals) => {
    changes = changes.concat(removals);
    if(this.inputFileSystem && this.inputFileSystem.purge) {
        this.inputFileSystem.purge(changes);
    }
    const times = this.watcher.getTimes();
    callback(null,
        changes.filter(file => files.indexOf(file) >= 0).sort(),
        changes.filter(file => dirs.indexOf(file) >= 0).sort(),
        changes.filter(file => missing.indexOf(file) >= 0).sort(), times, times);
});

那如何触发重编译呢？答案在 aggregated 事件中。

function example(err, filesModified, contextModified, missingModified, fileTimestamps, contextTimestamps) => {
        this.pausedWatcher = this.watcher;
        this.watcher = null;
        if(err) return this.handler(err);

        this.compiler.fileTimestamps = fileTimestamps;
        this.compiler.contextTimestamps = contextTimestamps;
        this.invalidate();
}

触发 invalidate 事件，因为 _go 事件再次被执行。

invalidate(callback) {
    if(callback) {
        this.callbacks.push(callback);
    }
    if(this.watcher) {
        this.pausedWatcher = this.watcher;
        this.watcher.pause();
        this.watcher = null;
    }
    if(this.running) {
        this.invalid = true;
        return false;
    } else {
        this._go();
    }
}

[dzyhenry]

在 compilation 对象中我们可以获取到和构建相关所有的依赖，而这些依赖真是需要去监听的内容。

“真是” -> “正是” ？

[dzyhenry]

原因很简单，因为在 webpack(webpackConfig) 的阶段中，webpack 注入很多内部的自有插件，webpack 源码非常让人值得学习的一点就是插件机制应用的如火纯情。

“如火纯情” -> “炉火纯青” ？

[soda-x]

@dzyhenry 谢谢指正

[lht1936]

你好，想咨询下，我在一台电脑上修改vue文件会自动刷新，换另一台电脑不行，应该如何调试webpack这块的源码呢