CC 4.0 授權

本節內容衍生自以下連結的內容，並受 CC BY 4.0 授權條款約束。
https://webpack.dev.org.tw/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 檔案中 require @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 生命週期中的任何 hook 事件。RspackOptionsApply 工具由 Rspack 用於使用所有內建外掛配置其 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。例如，您可以將預設的 outputFileSystem 替換為 memfs，將檔案寫入記憶體而不是磁碟。

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 物件#