配置变更

本篇文档主要介绍从 Modern.js 2.0 升级到 3.0 时，配置项层面的不兼容变更以及推荐的迁移方式。

dev

dev.port

变更内容：该配置已被移除，改为 server.port。

迁移示例：

// 改动前
dev: {
  port: 8080;
}

// 改动后
server: {
  port: process.env.NODE_ENV === 'development' ? 8080 : undefined;
}

dev.lazyCompilation

变更内容：开发环境下的默认值变化。纯 CSR 与流式 SSR 应用默认开启按需编译，默认值为 { imports: true, entries: false }；使用 string SSR、RSC 或 SSG 的应用仍默认关闭。该变更只影响开发环境，不影响生产构建产物。

迁移示例：如需保持 2.0 的行为，可以显式关闭：

dev: {
  lazyCompilation: false;
}

html

html.appIcon

变更内容：不再支持字符串形式，必须使用对象格式。

V2 类型:

type AppIconItem = {
  src: string;
  size: number;
  target?: 'apple-touch-icon' | 'web-app-manifest';
};

type AppIcon =
  | string
  | {
      name?: string;
      icons: AppIconItem[];
      filename?: string;
    };

V3 类型:

type AppIconItem = {
  src: string;
  size: number;
  target?: 'apple-touch-icon' | 'web-app-manifest';
};

type AppIcon = {
  name?: string;
  icons: AppIconItem[];
  filename?: string;
};

迁移示例：

// v2
export default {
  html: {
    appIcon: './src/assets/icon.png',
  },
};

// v3
export default {
  html: {
    appIcon: {
      icons: [
        {
          src: './src/assets/icon.png',
          size: 180,
        },
      ],
    },
  },
};

html.xxxByEntries

变更内容：metaByEntries、templateParametersByEntries、injectByEntries、tagsByEnties、faviconByEntries、templateByEnties、titleByEntries 等配置已废弃，需要使用函数语法代替。

处理步骤:

移除相关配置
使用 html.xxx 的函数用法代替

迁移示例：

// v2
export default {
  html: {
    metaByEntries: {
      foo: {
        description: 'TikTok',
      },
      // 其他配置...
    },
  },
};

// v3
export default {
  html: {
    meta({ entryName }) {
      switch (entryName) {
        case 'foo':
          return {
            description: 'TikTok',
          };
        // 其他配置...
      }
    },
  },
};

html.disableHtmlFolder

变更内容：该配置已废弃，使用 html.outputStructure 代替。

迁移示例：

// v2 - 等同于 html.outputStructure 配置为 nested
export default {
  html: {
    disableHtmlFolder: true,
  },
};

// v3
export default {
  html: {
    outputStructure: 'flat',
  },
};

tools

toos.postcss

变更内容：对象式配置会覆盖 Modern.js 内置的 PostCSS 配置。如果需要在内置配置基础上进行扩展，请使用函数式配置。

// v2
export default {
  tools: {
    postcss: {
      postcssOptions: {
        plugins: [tailwindcssPlugin],
      },
    },
  },
};

// v3
export default {
  tools: {
    postcss: (opts, { addPlugins }) => {
      addPlugins(tailwindcssPlugin);
    },
  },
};

tools.esbuild

变更内容：该配置已废弃，需要手动切换到 esbuild 压缩。

// 该配置已废弃，请参考 [切换压缩器](https://v2.rsbuild.rs/zh/config/output/minify#%E5%88%87%E6%8D%A2%E5%8E%8B%E7%BC%A9%E5%99%A8) 来手动切换到 esbuild 压缩
// tools: {
//   esbuild: { /* 配置 */ }
// },

tools.terser

变更内容：该配置已废弃，需要手动切换到 Terser 压缩。

// 该配置已废弃，请参考 [切换压缩器](https://v2.rsbuild.rs/zh/config/output/minify#%E5%88%87%E6%8D%A2%E5%8E%8B%E7%BC%A9%E5%99%A8) 来手动切换到 Terser 压缩
// tools: {
//   terser: { /* 配置 */ }
// },

tools.devServer

变更内容 1: after、before、devMiddleware 配置已废弃，使用 dev.setupDevMiddlewares 配置代替。

迁移示例：

// v2
export default {
  tools: {
    devServer: {
      before: [...],
      after: [...],
      devMiddleware: {
        writeToDisk: true
      }
    }
  }
};

// v3
export default {
  dev: {
    setupMiddlewares: [...],
    writeToDisk: true
  }
};

变更内容 2: client、https、liveReload 配置已废弃，使用对应的 dev.client、dev.https、dev.liveReload 配置代替。

迁移示例：

// v2
export default {
  tools: {
    devServer: {
      client: {
        port: 8081,
      },
    },
  },
};

// v3
export default {
  dev: {
    client: {
      port: 8081,
    },
  },
};

变更内容 3: hot 配置已废弃，使用 dev.hmr 配置代替。

迁移示例：

// v2
export default {
  tools: {
    devServer: {
      hot: false,
    },
  },
};

// v3
export default {
  dev: {
    hmr: false,
  },
};

变更内容 4: compress、headers、historyApiFallback、watch 配置已废弃，使用 dev.server.compress、dev.server.headers、dev.server.historyApiFallback、dev.server.watch 配置代替。

迁移示例：

// v2
export default {
  tools: {
    devServer: {
      compress: true,
      headers: {
        'X-Custom-Header': 'custom-value',
      },
      historyApiFallback: true,
      watch: true,
    },
  },
};

// v3
export default {
  dev: {
    server: {
      compress: true,
      headers: {
        'X-Custom-Header': 'custom-value',
      },
      historyApiFallback: true,
      watch: true,
    },
  },
};

tools.pug

变更内容：该配置已废弃，使用 Rsbuild 的 Pug 插件来启用支持。

迁移示例：

// v2
tools: {
  pug: true,
},

// v3
import { pluginPug } from "@rsbuild/plugin-pug";

export default {
  builderPlugins: [pluginPug()],
};

tools.rsdoctor

变更内容：该配置已废弃，请参考 Rsdoctor 文档，使用 Rspack 的 Rsdoctor 插件来启用支持。

迁移示例：

// v2
tools: {
  rsdoctor: {
    disableClientServer: true,
    features: ['bundle', 'loader', 'plugins', 'resolver'],
  },
},

// v3
import { RsdoctorRspackPlugin } from '@rsdoctor/rspack-plugin';

export default {
  // ...
  tools: {
    bundlerChain(chain) {
      // 仅在 RSDOCTOR 为 true 时注册插件，因为插件会增加构建耗时
      if (process.env.RSDOCTOR) {
        chain.plugin('rsdoctor').use(RsdoctorRspackPlugin, [
          {
            // 插件选项
            disableClientServer: true,
            features: ['bundle', 'loader', 'plugins', 'resolver'],
          },
        ]);
      }
    },
  },
};

tools.babel

变更内容：该配置已废弃，框架不再内置 Babel，请使用 Rsbuild 的 Babel 插件来启用支持。

迁移示例：

// v2
tools: {
  babel: {
    plugins: [
      [
        'babel-plugin-import',
        {
          libraryName: 'xxx-components',
          libraryDirectory: 'es',
          style: true,
        },
      ],
    ],
  },
}

// v3
import { pluginBabel } from '@rsbuild/plugin-babel';

export default {
  // ...
  builderPlugins: [
    pluginBabel({
      babelLoaderOptions: {
        plugins: [
          [
            'babel-plugin-import',
            {
              libraryName: 'my-components',
              libraryDirectory: 'es',
              style: true,
            },
          ],
        ],
      },
    })
  ];
}

tools.tailwindcss

变更内容：该配置已废弃，请参考 Tailwind 插件变更，使用 Rsbuild 的方式来接入 Tailwind CSS。

tools.tsLoader

变更内容：由于 Rspack 不支持 tsLoader 因此该配置已废弃，Rspack experiments.typeReexportsPresence 配置，可以用于改进对 Typescript 类型导出的识别。可以辅助 ts-loader 迁移。

// 该配置已废弃
// tools: {
//   tsLoader: { /* 配置 */ }
// },

tools.webpackChain

变更内容：该配置已废弃，请迁移到 tools.bundlerChain。

// v2
tools: {
  webpackChain: (chain, { env }) => {
    if (env === 'development') {
      chain.devtool('cheap-module-eval-source-map');
    }
  };
}

// v3
tools: {
  bundlerChain: (chain, { env }) => {
    if (env === 'development') {
      chain.devtool('cheap-module-eval-source-map');
    }
  };
}

tools.webpack

变更内容：该配置已废弃，请将 webpack 配置迁移到 tools.rspack。

// v2
tools: {
  webpack: (chain, { env }) => {
    {
      /* 配置 */
    }
  };
}

// v3
tools: {
  rspack: (chain, { env }) => {
    {
      /* 配置 */
    }
  };
}

source

source.resolveMainFields

变更内容：该配置已废弃，使用 resolve.mainFields 代替。

迁移示例：

// v2
source: {
  resolveMainFields: ['custom', 'module', 'main'];
}

// v3
resolve: {
  mainFields: ['custom', 'module', 'main'];
}

source.resolveExtensionPrefix

变更内容：该配置已废弃，使用 resolve.extensions 代替。

迁移示例：

// v2
source: {
  resolveExtensionPrefix: ['.ts', '.tsx', '.js'];
}

// v3
resolve: {
  extensions: ['.ts', '.tsx', '.js'];
}

source.moduleScopes

变更内容：该配置已废弃，直接移除。

source.enableCustomEntry

变更内容：该配置已废弃，直接移除。

source.disableEntryDirs

变更内容：该配置已废弃，直接移除。

source.alias

变更内容：该配置不再作用于自定义 Server 和 BFF 中的代码，为服务端代码配置的 alias 需要迁移到 tsconfig.json 中。

迁移示例：

// v2
source: {
  alias: {
    '@api/*': './api/*',
  },
},

// v3 tsconfig.json
{
  "compilerOptions": {
    "paths": {
      "@api/*": ["./api/*"]
    },
  },
}

server.routes

变更内容：默认路由由 main 变更为 index，如果 server.routes 配置中存在 index 则按如下迁移。

迁移示例：

// v2
server: {
  routes: {
    main: '/new',
  },
},

// v3
server: {
  routes: {
    index: '/new',
  },
},

output

output.overrideBrowserslist

变更内容：需要根据项目现有配置情况处理。

处理步骤:

检查项目中是否有 .browserslistrc 文件
检查 modern.config.[ts|js] 中是否配置了 output.overrideBrowserslist
检查 package.json 中是否配置了 browserslist

如果都没有，则创建 .browserslistrc 文件，内容为支持 ES6 的浏览器：

.browserslistrc

chrome >= 87
edge >= 88
firefox >= 78
safari >= 14

output.enableAssetFallback

变更内容：该配置已废弃，注释掉并添加说明。

// 该配置已废弃，如有问题请咨询 oncall 解决
// output: {
//   enableAssetFallback: true,
// },

output.cssModuleLocalIdentName

变更内容：该配置已废弃，使用 output.cssModules.localIdentName 代替。

迁移示例：

// v2
export default {
  output: {
    cssModuleLocalIdentName: '[path][name]__[local]-[hash:base64:6]',
  },
};

// v3
export default {
  output: {
    cssModules: {
      localIdentName: '[path][name]__[local]-[hash:base64:6]',
    },
  },
};

output.disableCssExtract

变更内容：该配置已废弃，使用 output.injectStyles 代替。

迁移示例：

// v2
export default {
  output: {
    disableCssExtract: true,
  },
};

// v3
export default {
  output: {
    injectStyles: true,
  },
};

output.disableFilenameHash

变更内容：该配置已废弃，使用 output.filenameHash 代替。

迁移示例：

// v2
export default {
  output: {
    disableFilenameHash: true,
  },
};

// v3
export default {
  output: {
    filenameHash: false,
  },
};

output.disableMinimize

变更内容：该配置已废弃，使用 output.minify 代替。

迁移示例：

// v2
export default {
  output: {
    disableMinimize: true,
  },
};

// v3
export default {
  output: {
    minify: false,
  },
};

output.disableSourceMap

变更内容：该配置已废弃，使用 output.sourceMap 代替。

迁移示例：

// v2
export default {
  output: {
    disableSourceMap: true,
  },
};

// v3
export default {
  output: {
    sourceMap: false,
  },
};

output.enableInlineScripts

变更内容：该配置已废弃，使用 output.inlineScripts 代替。

迁移示例：

// v2
export default {
  output: {
    enableInlineScripts: true,
  },
};

// v3
export default {
  output: {
    inlineScripts: true,
  },
};

output.enableInlineStyles

变更内容：该配置已废弃，使用 output.inlineStyles 代替。

迁移示例：

// v2
export default {
  output: {
    enableInlineStyles: true,
  },
};

// v3
export default {
  output: {
    inlineStyles: true,
  },
};

output.enableLatestDecorators

变更内容：该配置已废弃，使用 source.decorators 代替。

迁移示例：

// v2
export default {
  output: {
    enableLatestDecorators: true,
  },
};

// v3
export default {
  source: {
    decorators: {
      version: '2022-03',
    },
  },
};

output.disableNodePolyfill

变更内容：该配置已废弃，通过注册 pluginNodePolyfill 代替。

迁移示例：

// v2
export default {
  output: {
    disableNodePolyfill: false,
  },
};

// v3
import { pluginNodePolyfill } from '@rsbuild/plugin-node-polyfill';
export default {
  builderPlugins: [pluginNodePolyfill()],
};

plugins

app-tools 插件

变更内容：该插件不需要传入任何参数。

迁移示例：

// v2
plugins: [
  appTools({
    bundler: 'rspack'
  })
],

// v3
plugins: [
  appTools()
],

security

security.sri

变更内容：security.sri.hashLoading 不再需要，可以直接移除。

runtime

runtime.router

变更内容：不再需要，可以直接移除。该配置移动到 modern.runtime.ts 中的 router 配置中。

迁移示例：

// v2
// modern.config.ts
export default {
  runtime: {
    router: {
      // 路由配置
    },
  },
};

// v3
// modern.runtime.ts
import { defineRuntimeConfig } from '@modern-js/runtime';

export default defineRuntimeConfig({
  router: {
    // 路由配置
  },
});

runtime.state

变更内容：该配置被废弃，建议使用第三方状态管理库。

runtime.masterApp

变更内容：该配置被废弃，将该配置移动到 modern.runtime.ts 中的 masterApp 配置。

迁移示例：

// v2
// modern.config.ts
export default {
  runtime: {
    masterApp: {
      apps: [
        {
          name: 'Table',
          entry: 'http://localhost:8081',
        },
        {
          name: 'Dashboard',
          entry: 'http://localhost:8082',
        },
      ],
    },
  },
};

// v3
// modern.runtime.ts
import { defineRuntimeConfig } from '@modern-js/runtime';

export default defineRuntimeConfig({
  masterApp: {
    apps: [
      {
        name: 'Table',
        entry: 'http://localhost:8081',
      },
      {
        name: 'Dashboard',
        entry: 'http://localhost:8082',
      },
    ],
  },
});

performance

performance.bundleAnalyze

变更内容：该配置已废弃，建议使用 Rsdoctor 来分析产物体积

performance.transformLodash

变更内容：不再需要，可以直接移除。

迁移示例：

// v2
export default {
  performance: {
    transformLodash: true,
  },
};

// v3 - 直接移除该配置
export default {
  // 配置...
};

experiments

experiments.lazyCompilation

变更内容：该配置已废弃，改为 dev.lazyCompilation。

迁移示例：

// v2
experiments: {
  lazyCompilation: true;
}

// v3
dev: {
  lazyCompilation: true;
}

#配置变更

#dev

#dev.port

#dev.lazyCompilation

#html

#html.appIcon

#html.xxxByEntries

#html.disableHtmlFolder

#tools

#toos.postcss

#tools.esbuild

#tools.terser

#tools.devServer

#tools.pug

#tools.rsdoctor

#tools.babel

#tools.tailwindcss

#tools.tsLoader

#tools.webpackChain

#tools.webpack

#source

#source.resolveMainFields

#source.resolveExtensionPrefix

#source.moduleScopes

#source.enableCustomEntry

#source.disableEntryDirs

#source.alias

#server.routes

#output

#output.overrideBrowserslist

#output.enableAssetFallback

#output.cssModuleLocalIdentName

#output.disableCssExtract

#output.disableFilenameHash

#output.disableMinimize

#output.disableSourceMap

#output.enableInlineScripts

#output.enableInlineStyles

#output.enableLatestDecorators

#output.disableNodePolyfill

#plugins

#app-tools 插件

#security

#security.sri

#runtime

#runtime.router

#runtime.state

#runtime.masterApp

#performance

#performance.bundleAnalyze

#performance.transformLodash

#experiments

#experiments.lazyCompilation

配置变更

dev

dev.port

dev.lazyCompilation

html

html.appIcon

html.xxxByEntries

html.disableHtmlFolder

tools

toos.postcss

tools.esbuild

tools.terser

tools.devServer

tools.pug

tools.rsdoctor

tools.babel

tools.tailwindcss

tools.tsLoader

tools.webpackChain

tools.webpack

source

source.resolveMainFields

source.resolveExtensionPrefix

source.moduleScopes

source.enableCustomEntry

source.disableEntryDirs

source.alias

server.routes

output

output.overrideBrowserslist

output.enableAssetFallback

output.cssModuleLocalIdentName

output.disableCssExtract

output.disableFilenameHash

output.disableMinimize

output.disableSourceMap

output.enableInlineScripts

output.enableInlineStyles

output.enableLatestDecorators

output.disableNodePolyfill

plugins

app-tools 插件

security

security.sri

runtime

runtime.router

runtime.state

runtime.masterApp

performance

performance.bundleAnalyze

performance.transformLodash

experiments

experiments.lazyCompilation