Node 接口

Webpack 提供了一个 Node.js API,可以直接在 Node.js 运行时中使用。

Node.js API 在你需要自定义构建或开发过程的场景中非常有用,因为所有的报告和错误处理都必须手动完成,webpack 只负责编译部分。因此,stats 配置选项在 webpack() 调用中将不会有任何效果。

安装

要开始使用 webpack Node.js API,如果你尚未安装 webpack,请先安装它

npm install --save-dev webpack

然后在你的 Node.js 脚本中 require webpack 模块

const webpack = require('webpack');

或者如果你偏好 ES2015

import webpack from 'webpack';

webpack()

如果提供了回调函数,导入的 webpack 函数将接收一个 webpack 配置对象 并运行 webpack 编译器。

const webpack = require('webpack');

webpack({}, (err, stats) => {
  if (err || stats.hasErrors()) {
    // ...
  }
  // Done processing
});

Compiler 实例

如果你不向 webpack 运行器函数传递回调,它将返回一个 webpack Compiler 实例。这个实例可以用于手动触发 webpack 运行器,或者让它构建并监听更改,就像 CLI 一样。Compiler 实例提供了以下方法

  • .run(回调)
  • .watch(监听选项, 处理函数)

通常,只会创建一个主 Compiler 实例,尽管可以创建子编译器来委派特定任务。Compiler 最终是一个函数,它执行最基本的功能以维持生命周期运行。它将所有加载、打包和写入工作委托给已注册的插件。

Compiler 实例上的 hooks 属性用于将插件注册到 Compiler 生命周期中的任何钩子事件。webpack 使用 WebpackOptionsDefaulterWebpackOptionsApply 工具为其 Compiler 实例配置所有内置插件。

然后,使用 run 方法启动所有编译工作。编译完成后,将执行提供的 callback 函数。统计信息和错误的最终日志记录应在此 callback 函数中完成。

运行

Compiler 实例上调用 run 方法与上面提到的快速运行方法非常相似

const webpack = require('webpack');

const compiler = webpack({
  // ...
});

compiler.run((err, stats) => {
  // ...

  compiler.close((closeErr) => {
    // ...
  });
});

监听

调用 watch 方法会触发 webpack 运行器,然后监听更改(非常类似于 CLI:webpack --watch),一旦 webpack 检测到更改,它会再次运行。返回一个 Watching 实例。

watch(watchOptions, callback);
const webpack = require('webpack');

const compiler = webpack({
  // ...
});

const watching = compiler.watch(
  {
    // Example
    aggregateTimeout: 300,
    poll: undefined,
  },
  (err, stats) => {
    // Print watch/build result here...
    console.log(stats);
  }
);

Watching 选项此处有详细介绍。

关闭 Watching

watch 方法返回一个 Watching 实例,该实例暴露 .close(callback) 方法。调用此方法将结束监听

watching.close((closeErr) => {
  console.log('Watching Ended.');
});

使 Watching 失效

使用 watching.invalidate,你可以手动使当前编译轮次失效,而无需停止监听进程

watching.invalidate();

Stats 对象

作为 webpack() 回调函数的第二个参数传递的 stats 对象是关于代码编译过程信息的良好来源。它包括

  • 错误和警告(如果有)
  • 耗时
  • 模块和 Chunk 信息

webpack CLI 使用此信息在控制台中显示格式良好的输出。

stats 对象公开以下方法

stats.hasErrors()

可用于检查编译时是否存在错误。返回 truefalse

stats.hasWarnings()

可用于检查编译时是否存在警告。返回 truefalse

stats.toJson(options)

将编译信息作为 JSON 对象返回。options 可以是字符串(预设)或对象,以实现更精细的控制

stats.toJson('minimal');
stats.toJson({
  assets: false,
  hash: true,
});

所有可用的选项和预设都在 stats 文档中描述。

这是此函数输出的一个示例

stats.toString(options)

返回编译信息的格式化字符串(类似于 CLI 输出)。

选项与 stats.toJson(options) 相同,但有一个附加项

stats.toString({
  // Add console colors
  colors: true,
});

这是 stats.toString() 用法的一个示例

const webpack = require('webpack');

webpack(
  {
    // ...
  },
  (err, stats) => {
    if (err) {
      console.error(err);
      return;
    }

    console.log(
      stats.toString({
        chunks: false, // Makes the build much quieter
        colors: true, // Shows colors in the console
      })
    );
  }
);

MultiCompiler

MultiCompiler 模块允许 webpack 在单独的编译器中运行多个配置。如果 webpack 的 NodeJS API 中的 options 参数是一个选项数组,webpack 将应用单独的编译器并在所有编译器执行完毕后调用 callback

var webpack = require('webpack');

webpack(
  [
    { entry: './index1.js', output: { filename: 'bundle1.js' } },
    { entry: './index2.js', output: { filename: 'bundle2.js' } },
  ],
  (err, stats) => {
    process.stdout.write(stats.toString() + '\n');
  }
);

错误处理

为了良好的错误处理,你需要考虑以下三种类型的错误

  • 致命的 webpack 错误(配置错误等)
  • 编译错误(缺少模块、语法错误等)
  • 编译警告

这是一个实现所有这些功能的示例

const webpack = require('webpack');

webpack(
  {
    // ...
  },
  (err, stats) => {
    if (err) {
      console.error(err.stack || err);
      if (err.details) {
        console.error(err.details);
      }
      return;
    }

    const info = stats.toJson();

    if (stats.hasErrors()) {
      console.error(info.errors);
    }

    if (stats.hasWarnings()) {
      console.warn(info.warnings);
    }

    // Log result...
  }
);

自定义文件系统

默认情况下,webpack 使用普通文件系统从磁盘读取文件并写入文件。但是,可以使用不同类型的文件系统(内存、WebDAV 等)来更改输入或输出行为。为此,可以更改 inputFileSystemoutputFileSystem。例如,你可以将默认的 outputFileSystem 替换为 memfs,将文件写入内存而不是磁盘

const { createFsFromVolume, Volume } = require('memfs');
const webpack = require('webpack');

const fs = createFsFromVolume(new Volume());
const compiler = webpack({
  /* options */
});

compiler.outputFileSystem = fs;
compiler.run((err, stats) => {
  // Read the output later:
  const content = fs.readFileSync('...');
  compiler.close((closeErr) => {
    // ...
  });
});

请注意,webpack-dev-middleware(被 webpack-dev-server 和许多其他包使用)就是用这种方式神秘地隐藏你的文件,但仍继续将它们提供给浏览器!

10 贡献者

sallarbyzykwizardofhogwartsEugeneHlushkolukasgeitertoshihidetagamichenxsanjamesgeorge007textbook