Nx 21.0.0 迁移指南移除nx/webpack:webpack的isolatedConfig选项改用显式 Webpack 配置文件【免费下载链接】nxThe Monorepo Platform that amplifies both developers and AI agents. Nx optimizes your builds, scales your CI, and fixes failed PRs automatically. Ship in half the time.项目地址: https://gitcode.com/GitHub_Trending/nx/nx本文围绕 Nx 21.0.0 提供的自动迁移update-21-0-0-remove-isolated-config详细讲解nx/webpack:webpackexecutor 中isolatedConfig选项被移除的来龙去脉、迁移行为、源码实现原理与手工迁移步骤。读完本文你将能够理解迁移为何发生、迁移生成的webpack.config.js与内置配置的关系并掌握手动改造project.json与 Webpack 配置文件的完整方法。背景isolatedConfig与 executor 内置 Webpack 配置在 Nx 21.0.0 之前的版本中nx/webpack:webpackexecutor 支持一个名为isolatedConfig的布尔选项它控制 Webpack 配置的两种来源isolatedConfig: false默认由 executor 内部生成并应用内置的 Nx Webpack 配置自动注入withNx等 Nx 插件逻辑项目自身不需要也不读取webpackConfig文件。isolatedConfig: trueexecutor 不再自动注入 Nx 插件项目必须在webpackConfig指定的配置文件中显式应用 Nx 插件如withNx、withReact该用法在 webpack-build-executor-examples.md 中有过完整示例。// 旧版 isolatedConfig: true 的用法来自 packages/webpack/docs/webpack-build-executor-examples.md my-app: { targets: { build: { executor: nx/webpack:webpack, options: { webpackConfig: apps/my-app/webpack.config.js, isolatedConfig: true } } } }而在Nx 21.0.0中isolatedConfig选项被正式废弃executor 不再支持该选项无论取值如何Webpack 构建都必须通过显式的webpackConfig配置文件来提供配置。这一变化的核心动机是消除内置配置与用户配置文件两套配置路径的并行存在统一为每个项目一份显式 Webpack 配置的模型——这实际上就是isolatedConfig: true所代表的形态如今它成为了唯一形态。迁移做了什么自动将project.json中的isolatedConfig替换为webpackConfig官方迁移文档remove-isolated-config.md明确了迁移策略如果project.json的 build target options 中设置了isolatedConfig迁移会自动删除该选项并写入一个显式的webpackConfig文件该文件的内容与迁移前 executor 的内置配置完全等价从而保证构建行为不变。Before迁移前{ targets: { build: { executor: nx/webpack:webpack, options: { isolatedConfig: false } } } }After迁移后{ targets: { build: { executor: nx/webpack:webpack, options: { webpackConfig: apps/myapp/webpack.config.js } } } }迁移后构建配置从options中内联布尔值变为指向项目根目录下webpack.config.js的路径Webpack 配置以文件形式显式存在。迁移实现源码解析迁移的实际实现位于 remove-isolated-config.ts其工作流程可以拆解为四步遍历所有目标配置通过forEachExecutorOptions扫描工作区中所有使用nx/webpack:webpackexecutor 的 targetnx/devkit/internal提供拿到每个 target 的WebpackExecutorOptions类型定义见 schema.d.ts。只处理默认配置if (configurationName) return;意味着迁移只针对不带 configuration 后缀的默认 target 配置生效不会重复处理production等带名称的配置变体。判断是否已存在webpackConfig只有options.webpackConfig未设置时才生成配置文件若项目已显式指定了webpackConfig则原样保留不做任何改动。删除选项并写入配置文件delete options[isolatedConfig]移除废弃选项将options.webpackConfig设为${projectConfiguration.root}/webpack.config.js即项目根目录下的webpack.config.js依据options.target的值写入不同的配置文件内容通过updateProjectConfiguration回写project.json最后调用formatFiles统一格式化。迁移生成的 Webpack 配置文件内容迁移写入的webpack.config.js内容分为两种由target选项对应 schema 中enum: [node, web, webworker]的target字段见 schema.json决定普通Node / 默认目标const { composePlugins, withNx } require(nx/webpack); // Nx plugins for webpack. module.exports composePlugins(withNx(), (config) { // Note: This was added by an Nx migration. Webpack builds are required to have a corresponding Webpack config file. // See: https://nx.dev/recipes/webpack/webpack-config-setup return config; });Web 目标target: webconst { composePlugins, withNx, withWeb } require(nx/webpack); // Nx plugins for webpack. module.exports composePlugins(withNx(), withWeb(), (config) { // Note: This was added by an Nx migration. Webpack builds are required to have a corresponding Webpack config file. // See: https://nx.dev/recipes/webpack/webpack-config-setup return config; });两种模板的共同点是使用composePlugins组合 Nx 插件withNx必选Web 目标额外追加withWeb并导出一个接收config并原样返回的箭头函数——这正是迁移前 executor 内置配置所应用的插件集合因此行为上与isolatedConfig: false时代保持一致。文件中的注释也明确提示Webpack 构建现在必须对应一份 Webpack 配置文件并指向 Webpack 配置设置指南仓库内对应文档位于 packages/webpack/docs。迁移注册该迁移在 migrations.json 中注册为update-21-0-0-remove-isolated-configimplementation指向迁移执行文件documentation指向本迁移的说明文档即 remove-isolated-config.md。Nx 升级到 21.0.0 时会自动发现并提示运行此迁移。测试验证三种典型场景的行为确认迁移的单元测试位于 remove-isolated-config.spec.ts共覆盖三个关键场景可作为迁移行为的权威验证依据未设置webpackConfig的普通项目项目 options 中仅有isolatedConfig: false时迁移生成apps/myapp/webpack.config.js内容为composePlugins(withNx(), ...)模板且project.targets.build.options最终精确等于{ webpackConfig: apps/myapp/webpack.config.js }——isolatedConfig被完全删除。使用target: web的项目除isolatedConfig: false外还设置了target: web迁移生成包含withNx与withWeb的配置模板options 最终为{ target: web, webpackConfig: apps/myapp/webpack.config.js }其余选项如target得到保留。已显式设置webpackConfig的项目options 中已有webpackConfig: apps/myapp/webpack.config.js时迁移不会覆盖或重建配置文件自定义内容测试中的/* CUSTOM */注释原样保留。executor 侧如何消费webpackConfig理解了迁移的写入行为后再看 executor 是如何消费webpackConfig的就能拼出完整的链路。nx/webpack:webpack的实现位于 webpack.impl.ts其中getWebpackConfigs函数负责加载配置当options.webpackConfig存在时通过resolveUserDefinedWebpackConfig解析配置文件支持异步 Promise 导出若导出的是 Nx 可组合插件函数isNxWebpackComposablePlugin或standardWebpackConfigFunction为 false则按 Nx 传统方式调用该函数传入{ options, context, configuration }上下文若导出的是普通对象或标准 Webpack 函数则按标准 Webpack 方式处理若未指定webpackConfig则回退到一个空配置对象{}——这正是迁移后必须提供配置文件的底层原因在 Nx 21.0.0 中缺失webpackConfig将导致构建使用空配置而不再像过去那样自动注入内置 Nx 配置。需要注意的是schema.json 中nx/webpack:webpackexecutor 已被标记为 deprecated官方建议在 Nx v24 移除前通过nx g nx/webpack:convert-to-inferred迁移到nx/webpack/plugin推断插件。本文所述的isolatedConfig移除是这一演进路线上的一个里程碑。手工迁移步骤不使用自动迁移时如果你希望手动完成等价迁移按以下步骤操作即可在项目根目录创建webpack.config.jsNode 目标使用composePlugins(withNx(), ...)模板Web 目标追加withWeb()内容可直接复用上文两个模板。编辑project.json在targets.build.options中删除isolatedConfig新增webpackConfig: 项目根/webpack.config.js路径相对于工作区根目录。校验其余 options 不受影响main、tsConfig、outputPath、target、compiler等选项完整清单见 schema.json与webpackConfig是正交的无需改动。运行nx build project验证构建结果与迁移前一致如需自定义 Webpack 行为直接在webpack.config.js的箭头函数中修改config即可。小结Nx 21.0.0 移除nx/webpack:webpack的isolatedConfig选项标志着 Webpack 构建配置走向显式配置优先每个使用该 executor 的项目都必须拥有一份webpack.config.js。自动迁移remove-isolated-config.ts会安全地完成选项替换与配置文件生成其行为由 remove-isolated-config.spec.ts 中的三个用例锁定而手工迁移只需两步——补一个等价模板的配置文件、改一行project.json。理解这一变化也有助于平滑过渡到后续的nx/webpack/plugin推断插件体系。【免费下载链接】nxThe Monorepo Platform that amplifies both developers and AI agents. Nx optimizes your builds, scales your CI, and fixes failed PRs automatically. Ship in half the time.项目地址: https://gitcode.com/GitHub_Trending/nx/nx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考