移轉到 Rollup 4

• 先決條件
• 一般變更
• 組態變更
• 外掛 API 的變更
• 移轉到 Rollup 3
  • 先決條件
  • 使用組態檔案
  • 已變更的預設值
  • 更多已變更的選項
  • CommonJS 輸出的動態匯入
  • 外掛 API 的變更

這是您在從 Rollup 3 移轉到 Rollup 4 時可能會遇到的最重要的主題清單。對於中斷變更的完整清單，我們建議您參閱

• Rollup 4 變更日誌

有關如何從早期版本移轉，請參閱下方。

先決條件

請確定您至少執行 Node 18.0.0，並將所有 Rollup 外掛更新至最新版本。

對於較大的設定檔，建議先更新至 rollup@3.29.4，將 strictDeprecations 選項新增至您的設定檔，並解決所有出現的錯誤。這樣可以確保您不會依賴 Rollup 4 中可能已移除的功能。如果您的外掛程式中有錯誤，請聯絡外掛程式作者。

一般變更

Rollup 現在包含原生程式碼，如果您的平台和架構受支援，則會自動安裝（和移除）為 選擇性 npm 相依性。更精確地說，Rollup 有 optionalDependencies 的清單，每個清單僅安裝在特定 os 和 cpu 上。如果您的系統不受支援，您在啟動 Rollup 時會收到一則錯誤訊息，其中會告知您的平台和架構，並提供受支援的清單。在這種情況下，您可以改用 @rollup/wasm-node 作為與平台無關的替代方案。

瀏覽器建置（NPM 上的 @rollup/browser）現在依賴於 WASM 人工製品，也需要提供該人工製品。如果您使用 Vite 與瀏覽器建置，您需要將 "@rollup/browser" 新增至 optimizeDeps.exclude，否則 npm run dev 會因 .wasm 檔案路徑無效而失敗（另請參閱 vitejs #14609）。否則，它應該可以在沒有任何特定介入的情況下運作。

否則，一個明顯的變更是 Rollup 現在在檔案名稱中使用 url 安全的 base64 hash，而不是較舊的 base16 hash。這提供了更高的 hash 安全性，但由於技術原因，表示 hash 長度現在最多限制為 22 個字元。

在捆綁 CLI 應用程式時，如果輸出的 format 為 es 或 cjs，Rollup 現在會自動保留進入檔案中的 shebang 註解。以前，您必須透過外掛程式新增註解。

最後，您可能會看到一些關於無效註解位置的新警告。如果 Rollup 發現 @__PURE__ 或 @__NO_SIDE_EFFECTS__ 註解，但無法將其解釋為無效位置，則 Rollup 現在會發出警告。這些警告旨在協助除錯。若要將它們靜音，--filter-logs CLI 選項可以協助您。

組態變更

雖然 Rollup 3 中已棄用的某些選項已移除，但這裡唯一的重大變更在於我們不再提供 acorn 和 acornInjectPlugin 選項。這表示，很遺憾地，您無法再為不支援的語法新增外掛程式。根據需求，我們會考慮再次支援 JSX 語法，因為 SWC 剖析器會支援該語法。

外掛程式 API 的變更

一個重要的變更為 this.resolve() 現在預設會新增 skipSelf: true。這表示當從 resolveId 鉤子呼叫 this.resolve() 時，此鉤子不會再由這個或進一步巢狀的 this.resolve() 呼叫從其他外掛呼叫，除非它們使用不同的 source 或 importer。我們發現這對於大多數外掛而言是一個合理的預設值，可防止意外的無限迴圈。若要取得舊行為，您可以手動新增 skipSelf: false。

另一個重要的變更為 Rollup 監控模式將不再監控已透過外掛 load 鉤子載入的檔案 ID。因此這主要影響「虛擬」檔案，在其中監控硬碟機位置的變更實際上沒有意義。相反地，現在使用 load 鉤子的外掛必須手動呼叫 this.addWatchFile() 以處理 load 鉤子，針對所有它們依賴的檔案。

如果您的外掛處理匯入斷言，請注意在 resolveId 鉤子和其他地方，assertions 已被 attributes 取代，因為 JavaScript 功能也已重新命名。此外，匯入屬性的抽象語法樹表示形式現在再次遵循 ESTree 規格。

如果您要從您的外掛發出警告，您不能再在 buildStart 鉤子中呼叫 options.onwarn()。相反地，請使用 this.warn() 或 options.onLog()。

移轉至 Rollup 3

這是從 Rollup 2 移轉至 Rollup 3 時您可能會遇到的最重要的主題清單。針對中斷變更的完整清單，我們建議您參閱

• Rollup 3 變更日誌

從 Rollup 1 或更早版本移轉時，請另見

• Rollup 2 變更日誌
• Rollup 1 變更記錄

先決條件

請確定您至少執行 Node 14.18.0，並將所有 Rollup 外掛更新至最新版本。

對於較大的設定檔，建議先更新至 rollup@2.79.1，將 strictDeprecations 選項新增至您的設定檔，並解決出現的任何錯誤。這樣可以確保您沒有依賴 Rollup 3 中可能已移除的功能。如果您在外掛中遇到錯誤，請聯絡外掛作者。

使用設定檔

如果您使用 ES 模組作為設定檔，即 import 和 export 語法，您需要確保 Node 會將您的設定檔載入為 ES 模組。

最簡單的方法是將檔案副檔名變更為 .mjs，另請參閱 設定檔。

在使用原生 Node ES 模組時，有一些額外的注意事項，最重要的是

• 您無法直接匯入您的 package.json 檔案
• 您無法使用 __dirname 來取得目前目錄

使用原生 Node ES 模組時的注意事項 將提供一些如何處理這些事項的替代方案。

或者，您可以傳遞 --bundleConfigAsCjs 選項來強制使用舊的載入行為。

如果你使用 --configPlugin 選項，Rollup 現在會在執行你的設定檔之前，將你的設定檔打包成 ES 模組，而不是 CommonJS。這讓你能夠輕鬆地從你的設定檔匯入 ES 模組，但它與使用原生 ES 模組有相同的注意事項，例如 __dirname 將不再適用。同樣地，你可以傳遞 --bundleConfigAsCjs 選項來強制使用舊的載入行為。

變更預設值

一些選項現在有不同的預設值。如果你認為你遇到任何問題，請嘗試將以下內容新增到你的設定檔

({
	makeAbsoluteExternalsRelative: true,
	preserveEntrySignatures: 'strict',
	output: {
		esModule: true,
		generatedCode: {
			reservedNamesAsProps: false
		},
		interop: 'compat',
		systemNullSetters: false
	}
});

不過，一般來說，新的預設值是我們的建議設定。有關更多詳細資訊，請參閱每個設定的說明文件。

更多變更的選項

• output.banner/footer/intro/outro 現在會針對每個區塊進行呼叫，因此不應執行任何效能密集的操作。
• entryFileNames 和 chunkFileNames 函式不再能夠透過 modules 存取已呈現的模組資訊，而只能存取已包含的 moduleIds 清單。
• 當使用 output.preserveModules 和 entryFileNames 時，你將無法再使用 [ext]、[extName] 和 [assetExtName] 檔案名稱佔位符。此外，模組的路徑不再會自動加到檔案名稱前面，而是包含在 [name] 佔位符中。

CommonJS 輸出的動態匯入

預設情況下，在產生 cjs 輸出時，Rollup 現在會將任何外部（即非套件）動態匯入保持為輸出中的 import(…) 表達式。這在從 Node 14 開始的所有 Node 版本中都受支援，並允許從產生的 CommonJS 輸出中載入 CommonJS 和 ES 模組。如果您需要支援較舊的 Node 版本，您可以傳遞 output.dynamicImportInCjs: false。

外掛 API 的變更

一般的輸出產生流程已經過重新設計，請參閱 輸出產生掛勾 圖表以取得新的外掛掛勾順序。最明顯的變更可能是 banner/footer/intro/outro 不再在開始時呼叫一次，而是針對每個區塊呼叫。另一方面，augmentChunkHash 現在會在建立雜湊時於 renderChunk 之後評估。

由於檔案雜湊現在根據 renderChunk 之後檔案的實際內容，我們在產生雜湊之前不再知道確切的檔案名稱。取而代之的是，邏輯現在依賴於 1tPrXgE0 形式的雜湊佔位符。這表示提供給 renderChunk 掛勾的所有檔案名稱都可能包含佔位符，並且可能與最終的檔案名稱不符。不過，如果您計畫在區塊中使用這些檔案名稱，這不會造成問題，因為 Rollup 會在 generateBundle 執行之前替換所有佔位符。

不一定是重大變更，但在 renderChunk 中新增或移除匯入的外掛應該確保它們也會更新傳遞給此掛勾的對應 區塊 資訊。這將使其他外掛能夠依賴準確的區塊資訊，而無需自行分析區塊。請參閱掛勾的 文件 以取得更多資訊。