英语

简体中文

CC 4.0 许可证

本节内容源自以下链接的内容，并受 CC BY 4.0 许可证约束。
https://webpack.js.cn/api/node/
除非另有说明，以下内容可以被视为基于原始内容进行修改和删除的结果。

JavaScript API

Rspack 提供了一组 JavaScript API，用于在 Node.js 或 Bun 等 JavaScript 运行时中使用。

JavaScript API 在您需要自定义构建或开发过程的场景中很有用，因为所有报告和错误处理都必须手动完成，而 webpack 仅执行编译部分。因此，stats 配置选项在 rspack() 调用中将不会有任何作用。

提示

@rspack/core 是基于 webpack 的 JavaScript API 设计的，以确保功能一致性和类似的用户体验。

安装

要开始使用 Rspack JavaScript API，请先安装 @rspack/core（如果您还没有安装）。

npm

yarn

pnpm

bun

npm add @rspack/core -D

然后在您的 JavaScript 文件中引入 @rspack/core 模块。

build.js

import { rspack } from '@rspack/core';

rspack()

导入的 rspack 函数接收一个 Rspack 配置对象，并在提供回调函数的情况下运行 Rspack 编译器。

import { rspack } from '@rspack/core';

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

function rspack(
  options: MultiRspackOptions | RspackOptions,
  callback?: Callback<Error, MultiStats | Stats>,
): null | MultiCompiler | Compiler;

提示

err 对象将不包含编译错误。这些错误必须使用 stats.hasErrors() 单独处理，本指南的错误处理部分将详细介绍。 err 对象将仅包含与 rspack 相关的问题，例如配置错误等。

提示

您可以为 rspack 函数提供一个配置数组。有关更多信息，请参见下面的 MultiCompiler 部分。

编译器实例

如果您没有为 rspack 运行器函数传递回调函数，它将返回一个 Rspack Compiler 实例。此实例可用于手动触发 Rspack 运行器或使其进行构建并监视更改，类似于 CLI。 Compiler 实例提供以下方法

.run(callback)
.watch(watchOptions, handler)

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

Compiler 实例上的 hooks 属性用于将插件注册到 Compiler 生命周期中的任何挂钩事件。 Rspack 使用 RspackOptionsApply 实用程序来使用所有内置插件配置其 Compiler 实例。

有关更多详细信息，请参见编译器 API。

Compiler.ts

运行

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

警告

API 仅支持一次并发编译。使用 run 或 watch 时，请调用 close 并等待其完成，然后再再次调用 run 或 watch。并发编译将破坏输出文件。

import { rspack } from '@rspack/core';

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

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

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

监视

调用 watch 方法将触发 rspack 运行器，但随后会监视更改（类似于 CLI：rspack --watch），一旦 Rspack 检测到更改，就会再次运行。返回一个 Watching 实例。

import { rspack } from '@rspack/core';

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

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

Watching 选项在此处详细介绍。

警告

文件系统不准确可能会为单个更改触发多次构建。在上面的示例中，对于单个修改，console.log 语句可能会多次触发。用户应预期此行为，并且可以检查 stats.hash 以查看文件哈希是否已实际更改。

有关更多详细信息，请参见 Compiler.watch。

Watching.ts

统计对象

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

错误和警告（如果有）
计时
模块和块信息

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

提示

使用 MultiCompiler 时，将返回一个 MultiStats 实例，它满足与 stats 相同的接口，即下面描述的方法。

有关更多详细信息，请参见统计 API。

Stats.ts

MultiCompiler

MultiCompiler 模块允许 Rspack 在单独的编译器中运行多个配置。如果 Rspack JavaScript API 中的 options 参数是一个选项数组，Rspack 将应用单独的编译器并在所有编译器都执行后调用回调函数。

import { rspack } from '@rspack/core';

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

有关更多详细信息，请参见 MultiCompiler API。

错误处理

为了实现良好的错误处理，您需要考虑这三种类型的错误。

致命 rspack 错误（错误配置等）
编译错误（缺少模块、语法错误等）
编译警告

以下是一个处理所有条件的示例。

import { rspack } from '@rspack/core';

rspack(
  {
    // ...
  },
  (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 的区别

Rspack 当前对 inputFileSystem 的支持有限，与 webpack 一致地自定义文件系统读取功能的能力尚未实现。请参考：Issue #5091。
使用 Rspack 时，当使用指定的输出文件系统时，不再需要提供 mkdirp 和 join 实用程序方法。

默认情况下，Rspack 使用普通文件系统读取和写入文件。但是，可以使用不同类型的文件系统（内存、WebDAV 等）来更改输入或输出行为。为此，可以修改 `inputFileSystem` 或 `outputFileSystem`。例如，可以使用 memfs 替换默认的 `outputFileSystem`，将文件写入内存而不是磁盘。

import { createFsFromVolume, Volume } from 'memfs';
import { rspack } from '@rspack/core';

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

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

`sources` 对象

@rspack/core 通过 `sources` 导出 webpack-sources 模块。它提供了一组用于创建和操作源代码片段和源地图的类。在开发 Rspack 插件时，可以使用这些类来处理和操作源代码。

import { sources } from '@rspack/core';

const { RawSource } = sources;
const source = new RawSource('console.log("Hello, world!");');

有关详细用法，请参阅 webpack-sources 文档。

本页内容

JavaScript API#

安装#

rspack()#

编译器实例#

运行#

监视#

统计对象#

MultiCompiler#

错误处理#

自定义文件系统#

sources 对象#