node.js api.cn

The short way

简短方式

var webpack = require("webpack");

// returns a Compiler instance
webpack({
	// configuration
}, function(err, stats) {
	// ...
});

The long way

冗长方式

var webpack = require("webpack");

// returns a Compiler instance
var compiler = webpack({
	// configuration
});

compiler.run(function(err, stats) {
	// ...
});
// or
compiler.watch({ // watch options:
	aggregateTimeout: 300, // wait so long for more changes
	poll: true // use polling instead of native watchers
	// pass a number to set the polling interval
}, function(err, stats) {
	// ...
});

Compiler

An instance of Compiler has the following methods Compiler的实例有以下方法：

compiler.run(callback) - Builds the bundle(s). compiler.run(callback) - 构建 bundle.

• callback(err, stats) - A function that will be called with the build is complete.
• callback(err, stats) - 构建完成后调用的函数。

var watcher = compiler.watch(watchOptions, handler) - Builds the bundle(s) then starts the watcher, which rebuilds bundles whenever their source files change. Returns a Watching instance. Note: since this will automatically run an initial build, so you only need to run watch (and not run). var watcher = compiler.watch(watchOptions, handler) - 构建 bundle 后开启监视器，当源码更改时重新构建 bundle。返回一个Watching实例。注意：既然这个方法会自动运行初始构建，所以只需运行watch（而不是run）

• watchOptions

  • watchOptions.aggregateTimeout - After a change the watcher waits that time (in milliseconds) for more changes. Default: 300.

  • watchOptions.aggregateTimeout - 出现一个改变后监视器会为后续源码变更等待指定时间（毫秒单位）

  • watchOptions.poll - The watcher uses polling instead of native watchers. true uses the default interval, a number specifies a interval in milliseconds. Default: undefined (automatic).

  • watchOptions.poll - 监视器使用轮询而不是原生监视器。true表示使用默认间隔（一个毫秒单位的数字）。默认：undefined （自动）

• handler(err, stats) - A function that will be called when a build has been completed, or an error or warning has occurred. (Note that handler is called multiple times. It even can occur that handler is called for the same bundle multiple times. In this cases webpack is not sure about changes and rebuilds.)

• handler(err, stats) - 构建完成后，或者错误或警告出现时调用的函数。（注意：handler会被多次调用，甚至会在同一次打包中出现多次调用。这种情况下，webpack 不确定变更及重建。）

Watching

An instance of Watching has the following method: Watching的实例有如下方法：

watcher.close(callback) - stops the watcher. watcher.close(callback) - 停止监视器。

• callback - A function that's called when the watcher has closed.
• callback - 当监视器关闭时执行的回调。

stats

The Stats object exposes these methods: Stats对象有以下方法：

stats.hasErrors()

Returns true if there were errors while compiling. 编译时如果有错误返回true

stats.hasWarnings()

Returns true if there were warnings while compiling. 编译时如果有警告返回true

stats.toJson(options)

Return information as JSON object. 返回 JSON 格式的对象

There are a few different logging levels, pass these as options (e.g. stats.toJson("verbose")): 存在几个不同的日志级别，可以用下值作为options(如 stats.toJson("verbose")):

"none" (or false) output nothing "none" (或 false) 无输出

"errors-only" only output when errors happen "errors-only" 仅输出错误信息

"minimal" only output when errors or a new compilation happen "minimal" 仅当错误或者一次新的 compilation 发生时输出

"normal" (or true) standard output "normal" (或 true) 标准输出

"verbose" output all the information webpack has "verbose" 输出所有 webpack 包含的信息

For more granular control, pass an object that can have these booleans set: 更细力度的控制，可以通过options对象指定（布尔值）：

options.context (string) context directory for request shortening options.context (字符串) 用来缩短请求的上下文目录

options.hash add the hash of the compilation options.hash 加入 compilation 的 hash

options.version add webpack version information options.version 加入 webpack 的版本信息

options.timings add timing information options.timings 加入时序信息

options.assets add assets information options.assets 加入资源信息

options.chunks add chunk information (setting this to false allows for a less verbose output) options.chunks 加入 chunk 信息（设为false可以减少冗长输出）

options.chunkModules add built modules information to chunk information options.chunkModules 向 chunk 信息加入构建好的模块信息

options.modules add built modules information options.modules 加入构建好的模块信息

options.children add children information options.children 加入子孙关系信息

options.cached add also information about cached (not built) modules options.cached 加入关于缓存了（尚未构建）的模块的信息

options.reasons add information about the reasons why modules are included options.reasons 加入囊括某些模块的原因信息

options.source add the source code of modules options.source 加入模块的源码

options.errorDetails add details to errors (like resolving log) options.errorDetails 加入错误的详细信息（如解析记录）

options.chunkOrigins add the origins of chunks and chunk merging info options.chunkOrigins 加入 chunk 的源以及其合并信息

options.modulesSort (string) sort the modules by that field options.modulesSort （字符串）根据此字段排序模块

options.chunksSort (string) sort the chunks by that field options.chunksSort （字符串）根据此字段排序 chunk

options.assetsSort (string) sort the assets by that field options.assetsSort （字符串）根据此字段排序资源文件

Here is an example of the resulting JSON. 这是一个JSON 结果样例。

Note: If you want to extract the asset name for generating the HTML page, use the assetsByChunkName property, which contains an object mapping chunkName to asset name(s) (it's a string or an array of strings). 注意：如果你想提取资源名来生成 HTML 页面，使用assetsByChunkName属性，其包含了一个映射chunkName到资源名（一个字符串或者一个字符串数组）的对象。

stats.toString(options)

Returns a formatted string of the result. 返回结果的格式化字符串。

options are the same as options in toJson. 此options跟toJson的options一样。

options.colors With console colors options.colors 控制台输出带颜色

This is an example of how stats.toString can be used: 下例示范怎么使用stats.toString:

var webpack = require("webpack");
webpack({
	// configuration
}, function(err, stats) {
        if (err) { throw new gutil.PluginError('webpack:build', err); }
        gutil.log('[webpack:build]', stats.toString({
            chunks: false, // Makes the build much quieter
            colors: true
        }));
});

error handling

错误处理

to handle all errors and warnings with the node.js API you need to test err, stats.errors and stats.warnings: 为了利用 node.js API 处理所有错误和警告，你需要检测err, stats.errors 和 stats.warnings:

var webpack = require("webpack");
webpack({
	// configuration
}, function(err, stats) {
	if(err)
		return handleFatalError(err);
	var jsonStats = stats.toJson();
	if(jsonStats.errors.length > 0)
		return handleSoftErrors(jsonStats.errors);
	if(jsonStats.warnings.length > 0)
		handleWarnings(jsonStats.warnings);
	successfullyCompiled();
});

compile to memory

内存中编译

var MemoryFS = require("memory-fs");
var webpack = require("webpack");

var fs = new MemoryFS();
var compiler = webpack({ ... });
compiler.outputFileSystem = fs;
compiler.run(function(err, stats) {
  // ...
  var fileContent = fs.readFileSync("...");
});