迁移到 Rollup 4
这是您从 Rollup 3 迁移到 Rollup 4 时可能会遇到的最重要主题的列表。有关所有重大更改的完整列表,我们建议您查阅
有关如何从早期版本迁移,请参阅下方.
先决条件
确保您至少运行 Node 18.0.0 并将所有 Rollup 插件更新到最新版本。
对于较大的配置,可以先更新到 [email protected]
,将 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 哈希,而不是旧的 Base16 哈希。这提供了更高的哈希安全性,但由于技术原因,哈希长度现在限制为最多 22 个字符。
在捆绑 CLI 应用程序时,Rollup 现在将在入口文件保留 shebang 注释,如果输出 format
为 es
或 cjs
。以前,您需要通过插件添加注释。
最后,您可能会看到一些关于无效注释位置的新警告。Rollup 现在将在找到无法解释的 @__PURE__
或 @__NO_SIDE_EFFECTS__
注释时发出警告,因为它位于无效位置。这些警告旨在帮助调试。要消除它们,--filter-logs
CLI 选项可以帮助您。
配置更改
虽然 Rollup 3 中已弃用的一些选项已被删除,但这里唯一的重大更改是,我们不再提供 acorn
和 acornInjectPlugin
选项。这意味着,不幸的是,您不再可以为不受支持的语法添加插件。根据需求,我们考虑再次支持 JSX 语法,因为 SWC 解析器将支持该语法。
插件 API 的更改
一个重要的更改是,this.resolve()
现在默认情况下会添加 skipSelf: true
。这意味着,当从 resolveId
钩子调用 this.resolve()
时,除非它们使用不同的 source
或 importer
,否则此钩子将不会被此钩子或来自其他插件的进一步嵌套的 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 模块作为配置文件,即 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
中导入的插件应确保它们也更新传递给此钩子的相应 chunk
信息。这将使其他插件能够依赖准确的 chunk 信息,而无需自行解析 chunk。有关更多信息,请参阅该钩子的 文档。