迁移到 Rollup 4

• 先决条件
• 一般变化
• 配置变更
• 插件 API 的更改
• 迁移到 Rollup 3
  • 先决条件
  • 使用配置文件
  • 更改默认值
  • 更多更改选项
  • CommonJS 输出中的动态导入
  • 插件 API 的更改

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

¥This is a list of the most important topics you may encounter when migrating from Rollup 3 to Rollup 4. For a full list of breaking changes, we advise you to consult the

• Rollup 4 变更日志

  ¥Rollup 4 changelog

有关如何从早期版本迁移的信息，请参阅 参见下文。

¥For how to migrate from earlier versions, see below.

先决条件

¥Prerequisites

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

¥Make sure you run at least Node 18.0.0 and update all your Rollup plugins to their latest versions.

对于较大的配置，首先更新到 rollup@3.29.4 是有意义的，将 strictDeprecations 选项添加到你的配置中并解决弹出的任何错误。这样你就可以确保不依赖于 Rollup 4 中可能已删除的功能。如果你的插件有错误，请联系插件作者。

¥For larger configs, it can make sense to update to rollup@3.29.4 first, add the strictDeprecations option to your config and resolve any errors that pop up. That way you can make sure you do not rely on features that may have been removed in Rollup 4. If you have errors in your plugins, please contact the plugin author.

一般变化

¥General Changes

Rollup 现在包含原生代码，如果你的平台和体系结构受支持，这些原生代码会作为 可选的 npm 依赖 自动安装（和删除）。更准确地说，Rollup 有一个 optionalDependencies 列表，每个列表仅安装在特定的 os 和 cpu 上。如果你的系统不受支持，你将在启动 Rollup 时收到一条错误消息，该消息将告诉你有关你的平台和架构的信息，并提供受支持的平台和架构的列表。在这种情况下，你可以使用 @rollup/wasm-node 作为独立于平台的直接替代品。

¥Rollup now includes native code that is automatically installed (and removed) as an optional npm dependency if your platform and architecture is supported. More precisely, Rollup has a list of optionalDependencies, each of which only install on a specific os and cpu. If your system is not supported, you will receive an error message when starting Rollup that will tell you about your platform and architecture and gives you a list of supported ones. In that case, you can instead use @rollup/wasm-node as a platform-independent drop-in replacement.

浏览器版本（NPM 上的 @rollup/browser）现在依赖于还需要提供的 WASM 工件。如果你使用带有 Vite 的浏览器版本，则需要将 "@rollup/browser" 添加到 optimizeDeps.exclude，否则 npm run dev 将失败，并显示 .wasm 文件的无效路径（另请参阅 vitejs #14609）。否则它应该在没有任何特定干预的情况下工作。

¥The browser build (@rollup/browser on NPM) now relies on a WASM artifact that needs to be provided as well. If you are using the browser build with Vite, you'll need to add "@rollup/browser" to optimizeDeps.exclude, otherwise npm run dev fails with an invalid path to the .wasm file (see also vitejs #14609). Otherwise it should work without any specific intervention.

除此之外，一个明显的变化是 Rollup 现在在文件名中使用 url 安全的 Base64 哈希值，而不是旧的 Base16 哈希值。这提供了更多的哈希安全性，但意味着由于技术原因，哈希长度现在限制为最多 21 个字符。

¥Otherwise, an obvious change is that Rollup now uses url-safe base64 hashes in file names instead of the older base16 hashes. This provides more hash safety but means that hash length is now limited to at most 21 characters for technical reasons.

打包 CLI 应用时，如果输出 format 是 es 或 cjs，Rollup 现在将自动在条目文件中保留 shebang 注释。以前，你需要通过插件添加注释。

¥When bundling CLI apps, Rollup will now automatically preserve shebang comments in entry files if the output format is es or cjs. Previously, you would have needed to add the comment via a plugin.

最后，你可能会看到一些有关无效注释位置的新警告。现在，如果 Rollup 发现无法解释的 @__PURE__ 或 @__NO_SIDE_EFFECTS__ 注释，因为它位于无效位置，则会触发警告。这些警告旨在帮助调试。要让它们安静下来，--filter-logs CLI 选项可以帮助你。

¥Last, you may see some new warnings about invalid annotation positions. Rollup will now warn if it finds a @__PURE__ or @__NO_SIDE_EFFECTS__ comment that it cannot interpret as it is in an invalid location. These warnings are meant to help debugging. To silence them, the --filter-logs CLI option can help you.

配置变更

¥Configuration Changes

虽然 Rollup 3 中已弃用的一些选项已被删除，但这里唯一的主要变化是我们不再提供 acorn 和 acornInjectPlugin 选项。不幸的是，这意味着你无法再为不受支持的语法添加插件。根据需求，我们考虑再次支持 JSX 语法，因为 SWC 解析器将支持它。

¥While some options that were already deprecated in Rollup 3 have been removed, the only major change here is that we no longer have the acorn and acornInjectPlugin options available. This means, unfortunately, that you can no longer add plugins for unsupported syntax. Depending on demand, we consider supporting JSX syntax again as the SWC parser would support that.

插件 API 的更改

¥Changes to the Plugin API

一个重要的变化是 this.resolve() 现在将默认添加 skipSelf: true。这意味着当从 resolveId 钩子调用 this.resolve() 时，此钩子不会被其他插件的此调用或进一步嵌套的 this.resolve() 调用再次调用，除非它们使用不同的 source 或 importer。我们发现对于大多数插件来说这是一个合理的默认值，可以防止意外的无限循环。要获得旧的行为，你可以手动添加 skipSelf: false。

¥An important change is that this.resolve() will now by default add skipSelf: true. That means when calling this.resolve() from a resolveId hook, this hook will not be called again by this or further nested this.resolve() calls from other plugins unless they use a different source or importer. We found that this is a reasonable default for most plugins that prevents unintended infinite loops. To get the old behaviour, you can manually add skipSelf: false.

另一个重要的变化是 Rollup 监视模式将不再监视通过插件 load 钩子加载的文件的 ID。所以这主要影响 "虚拟的" 文件，在这些文件中观察硬盘位置的变化确实没有意义。相反，现在由使用 load 钩子的插件手动调用 this.addWatchFile() 来处理它们依赖的所有文件来处理 load 钩子。

¥Another important change is that Rollup watch mode will no longer watch ids of files that have been loaded via a plugin load hook. So this mainly affects "virtual" files, where it really does not make sense to watch a hard drive location for changes. Instead, it is now up to plugins that use a load hook to manually call this.addWatchFile() for all the files they depend on to handle the load hook.

如果你的插件处理导入断言，请注意，在 resolveId 钩子和其他位置，assertions 已替换为 attributes，因为 JavaScript 功能也已重命名。此外，导入属性的抽象语法树表示现在再次遵循 ESTree 规范。

¥If your plugin handles import assertions, note that in the resolveId hook and other places, assertions have been replaced with attributes as the JavaScript feature was also renamed. Also, the abstract syntax tree representation of import attributes now follows the ESTree spec again.

如果你想从插件触发警告，则不能再在 buildStart 钩子中调用 options.onwarn()。相反，请使用 this.warn() 或 options.onLog()。

¥If you want to emit warnings from your plugin, you can no longer call options.onwarn() in the buildStart hook. Instead, either use this.warn() or options.onLog().

迁移到 Rollup 3

¥Migrating to Rollup 3

这是从 Rollup 2 迁移到 Rollup 3 时可能遇到的最重要主题的列表。有关重大变更的完整列表，我们建议你查阅

¥This is a list of the most important topics you may encounter when migrating from Rollup 2 to Rollup 3. For a full list of breaking changes, we advise you to consult the

• Rollup 3 变更日志

  ¥Rollup 3 changelog

从 Rollup 1 或更早版本迁移时，另请参阅

¥When migrating from Rollup 1 or earlier, see also

• Rollup 2 变更日志

  ¥Rollup 2 changelog

• Rollup 1 变更日志

  ¥Rollup 1 changelog

先决条件

¥Prerequisites

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

¥Make sure you run at least Node 14.18.0 and update all your Rollup plugins to their latest versions.

对于较大的配置，首先更新到 rollup@2.79.1 是有意义的，将 strictDeprecations 选项添加到你的配置中并解决弹出的任何错误。这样你就可以确保不依赖于 Rollup 3 中可能已删除的功能。如果你的插件有错误，请联系插件作者。

¥For larger configs, it can make sense to update to rollup@2.79.1 first, add the strictDeprecations option to your config and resolve any errors that pop up. That way you can make sure you do not rely on features that may have been removed in Rollup 3. If you have errors in your plugins, please contact the plugin author.

使用配置文件

¥Using Configuration Files

如果你使用 ES 模块作为配置文件，即 import 和 export 语法，你需要确保 Node 将你的配置作为 ES 模块加载。

¥If you are using an ES module as configuration file, i.e. import and export syntax, you need to make sure Node will be loading your configuration as an ES module.

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

¥The easiest way to ensure that is to change the file extension to .mjs, see also Configuration Files.

使用原生 Node ES 模块时还有一些额外的注意事项，最值得注意的是

¥There are some additional caveats when using native Node ES modules, most notably

• 你不能简单地导入 package.json 文件

  ¥you cannot simply import your package.json file

• 你不能使用 __dirname 来获取当前目录

  ¥you cannot use __dirname to get the current directory

使用原生 Node ES 模块时的注意事项 将为你提供一些如何处理这些事情的替代方案。

¥Caveats when using native Node ES modules will give you some alternatives for how to handle these things.

或者，你可以传递 --bundleConfigAsCjs 选项来强制旧的加载行为。

¥Alternatively you can pass the --bundleConfigAsCjs option to force the old loading behavior.

如果你使用 --configPlugin 选项，Rollup 现在会在运行之前将你的配置打包为 ES 模块而不是 CommonJS。这使你可以轻松地从配置中导入 ES 模块，但与使用原生 ES 模块有相同的注意事项，例如 __dirname 将不再起作用。同样，你可以传递 --bundleConfigAsCjs 选项来强制旧的加载行为。

¥If you use the --configPlugin option, Rollup will now bundle your configuration as an ES module instead of CommonJS before running it. This allows you to easily import ES modules from your configuration but has the same caveats as using a native ES module, e.g. __dirname will no longer work. Again, you can pass the --bundleConfigAsCjs option to force the old loading behavior.

更改默认值

¥Changed Defaults

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

¥Some options now have different default values. If you think you experience any issues, try adding the following to your configuration:

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

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

¥In general, though, the new default values are our recommended settings. Refer to the documentation of each setting for more details.

更多更改选项

¥More Changed Options

• output.banner/footer/intro/outro 现在按块调用，因此不应执行任何性能消耗大的操作。

  ¥output.banner/footer/intro/outro are now called per chunk and thus should not do any performance-heavy operations.

• entryFileNames 和 chunkFileNames 函数不再能够通过 modules 访问渲染的模块信息，而只能访问包含的 moduleIds 的列表。

  ¥entryFileNames and chunkFileNames functions no longer have access to the rendered module information via modules, but only to a list of included moduleIds.

• 使用 output.preserveModules 和 entryFileNames 时，不能再使用 [ext]、[extName] 和 [assetExtName] 文件名占位符。此外，模块的路径不再自动添加到文件名前面，而是包含在 [name] 占位符中。

  ¥When using output.preserveModules and entryFileNames, you can no longer use the [ext], [extName] and [assetExtName] file name placeholders. Also, the path of a module is no longer prepended to the file name automatically but is included in the [name] placeholder.

CommonJS 输出中的动态导入

¥Dynamic Import in CommonJS Output

默认情况下，当生成 cjs 输出时，Rollup 现在会将任何外部（即非打包）动态导入保留为输出中的 import(…) 表达式。从 Node 14 开始的所有 Node 版本都支持此功能，并允许从生成的 CommonJS 输出加载 CommonJS 和 ES 模块。如果需要支持旧的 Node 版本，可以通过 output.dynamicImportInCjs: false。

¥By default, when generating cjs output, Rollup will now keep any external, i.e. non-bundled, dynamic imports as import(…) expressions in the output. This is supported in all Node versions starting with Node 14 and allows to load both CommonJS and ES modules from generated CommonJS output. If you need to support older Node versions, you can pass output.dynamicImportInCjs: false.

插件 API 的更改

¥Changes to the Plugin API

然后一般输出生成流程已被重新设计，请参阅 输出生成钩子 图以了解新的插件钩子顺序。也许最明显的变化是 banner/footer/intro/outro 不再在开始时调用一次，而是每个块调用一次。另一方面，创建哈希时，现在会在 renderChunk 之后评估 augmentChunkHash。

¥Then general output generation flow has been reworked, see the Output Generation Hooks graph for the new plugin hook order. Probably the most obvious change is that the banner/footer/intro/outro are no longer invoked once at the beginning but rather per chunk. On the other hand, augmentChunkHash is now evaluated after renderChunk when the hash is created.

由于文件哈希现在基于 renderChunk 之后文件的实际内容，因此在生成哈希之前我们不再知道确切的文件名。相反，该逻辑现在依赖于 1tPrXgE0 形式的哈希占位符。这意味着 renderChunk 钩子可用的所有文件名可能包含占位符，并且可能与最终文件名不对应。不过，如果你计划在块中使用这些文件名，这不是问题，因为 Rollup 将在 generateBundle 运行之前替换所有占位符。

¥As file hashes are now based on the actual content of the file after renderChunk, we no longer know exact file names before hashes are generated. Instead, the logic now relies on hash placeholders of the form 1tPrXgE0. That means that all file names available to the renderChunk hook may contain placeholders and may not correspond to the final file names. This is not a problem though if you plan on using these files names within the chunks as Rollup will replace all placeholders before generateBundle runs.

不一定是重大更改，但在 renderChunk 中添加或删除导入的插件应确保它们也更新传递给此钩子的相应 chunk 信息。这将使其他插件能够依赖准确的块信息，而无需自行删除块。有关详细信息，请参阅钩子的 文档。

¥Not necessarily a breaking change, but plugins that add or remove imports in renderChunk should make sure they also update the corresponding chunk information that is passed to this hook. This will enable other plugins to rely on accurate chunk information without the need to pare the chunk themselves. See the documentation of the hook for more information.