跳至内容

迁移到 Rollup 4

这是您从 Rollup 3 迁移到 Rollup 4 时可能会遇到的最重要主题的列表。有关所有重大更改的完整列表,我们建议您查阅

有关如何从早期版本迁移,请参阅下方.

先决条件

确保您至少运行 Node 18.0.0 并将所有 Rollup 插件更新到最新版本。

对于较大的配置,可以先更新到 [email protected],将 strictDeprecations 选项添加到您的配置中,并解决出现的任何错误。这样,您就可以确保您不依赖 Rollup 4 中可能已删除的功能。如果您在插件中遇到错误,请联系插件作者。

一般更改

Rollup 现在包含本机代码,如果您的平台和架构受支持,则会自动安装(并删除)为 可选 npm 依赖项。更准确地说,Rollup 有一份 optionalDependencies 列表,每个列表仅在特定 oscpu 上安装。如果您的系统不受支持,您将在启动 Rollup 时收到错误消息,该消息将告诉您有关您的平台和架构的信息,并提供受支持平台和架构的列表。在这种情况下,您可以改为使用 @rollup/wasm-node 作为平台无关的直接替换。

浏览器构建(NPM 上的 @rollup/browser)现在依赖于也需要提供的 WASM 工件。如果您将浏览器构建与 Vite 一起使用,则需要将 "@rollup/browser" 添加到 optimizeDeps.exclude 中,否则 npm run dev 会因 .wasm 文件的无效路径而失败(另请参阅 vitejs #14609)。否则,它应该在没有任何特定干预的情况下工作。

否则,一个明显的更改是 Rollup 现在在文件名中使用 URL 安全的 Base64 哈希,而不是旧的 Base16 哈希。这提供了更高的哈希安全性,但由于技术原因,哈希长度现在限制为最多 22 个字符。

在捆绑 CLI 应用程序时,Rollup 现在将在入口文件保留 shebang 注释,如果输出 formatescjs。以前,您需要通过插件添加注释。

最后,您可能会看到一些关于无效注释位置的新警告。Rollup 现在将在找到无法解释的 @__PURE__@__NO_SIDE_EFFECTS__ 注释时发出警告,因为它位于无效位置。这些警告旨在帮助调试。要消除它们,--filter-logs CLI 选项可以帮助您。

配置更改

虽然 Rollup 3 中已弃用的一些选项已被删除,但这里唯一的重大更改是,我们不再提供 acornacornInjectPlugin 选项。这意味着,不幸的是,您不再可以为不受支持的语法添加插件。根据需求,我们考虑再次支持 JSX 语法,因为 SWC 解析器将支持该语法。

插件 API 的更改

一个重要的更改是,this.resolve() 现在默认情况下会添加 skipSelf: true。这意味着,当从 resolveId 钩子调用 this.resolve() 时,除非它们使用不同的 sourceimporter,否则此钩子将不会被此钩子或来自其他插件的进一步嵌套的 this.resolve() 调用再次调用。我们发现,对于大多数插件来说,这是一个合理的默认值,可以防止意外的无限循环。要获得旧的行为,您可以手动添加 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 1 或更早版本迁移时,另请参阅

先决条件

确保您至少运行 Node 14.18.0 并将所有 Rollup 插件更新到最新版本。

对于较大的配置,可以先更新到 [email protected],将 strictDeprecations 选项添加到您的配置中,并解决出现的任何错误。这样,您就可以确保您不依赖 Rollup 3 中可能已删除的功能。如果您在插件中遇到错误,请联系插件作者。

使用配置文件

如果您使用 ES 模块作为配置文件,即 importexport 语法,则需要确保 Node 将加载您的配置作为 ES 模块。

确保这一点的最简单方法是将文件扩展名更改为 .mjs,另请参阅 配置文件

使用本机 Node ES 模块时,有一些额外的注意事项,最值得注意的是

  • 您不能简单地导入您的 package.json 文件
  • 您不能使用 __dirname 获取当前目录

使用本机 Node ES 模块时的注意事项 将为您提供一些处理这些事物的替代方法。

或者,您可以传递 --bundleConfigAsCjs 选项以强制使用旧的加载行为。

如果您使用 --configPlugin 选项,Rollup 现在将捆绑您的配置作为 ES 模块,而不是在运行它之前将其捆绑为 CommonJS。这使您可以轻松地从配置中导入 ES 模块,但具有与使用本机 ES 模块相同的注意事项,例如 __dirname 将不再起作用。同样,您可以传递 --bundleConfigAsCjs 选项以强制使用旧的加载行为。

更改的默认值

一些选项现在具有不同的默认值。如果您认为遇到任何问题,请尝试将以下内容添加到您的配置中

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

总的来说,新的默认值是我们的推荐设置。有关更多详细信息,请参阅每个设置的文档。

更多更改的选项

  • output.banner/footer/intro/outro 现在按块调用,因此不应执行任何性能密集型操作。
  • entryFileNameschunkFileNames 函数不再可以通过 modules 访问渲染的模块信息,而只能访问包含的 moduleIds 列表。
  • 使用 output.preserveModulesentryFileNames 时,您不再可以使用 [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 中导入的插件应确保它们也更新传递给此钩子的相应 chunk 信息。这将使其他插件能够依赖准确的 chunk 信息,而无需自行解析 chunk。有关更多信息,请参阅该钩子的 文档

根据 MIT 许可证发布。