配置变化
本篇文档主要介绍从 Modern.js 2.0 升级到 3.0 时，配置项层面的不兼容变更以及推荐的迁移方式。
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',
},
};output
output.overrideBrowserslist
变更内容: 需要根据项目现有配置情况处理。
处理步骤:
- 检查项目中是否有
.browserslistrc文件 - 检查
modern.config.[ts|js]中是否配置了output.overrideBrowserslist - 检查 package.json 中是否配置了 browserslist
如果都没有，则创建 .browserslistrc 文件，内容为支持 ES6 的浏览器：
chrome >= 51
edge >= 15
firefox >= 54
safari >= 10
ios_saf >= 10output.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()
]
};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
变更内容: 该配置已废弃，直接移除。
tools
tools.esbuild
变更内容: 该配置已废弃，需要手动切换到 esbuild 压缩。
// 该配置已废弃，请参考 [切换压缩器](https://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://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 配置代替。
迁移示例:
// 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
}
};dev
dev.port
变更内容: 该配置已被移除，改为 server.port。
迁移示例:
// 改动前
dev: {
port: 8080
}
// 改动后
server: {
port: process.env.NODE_ENV === 'development' ? 8080 : undefined
}runtime
runtime.router
变更内容: 不再需要，可以直接移除。
runtime.state
变更内容: 该配置被废弃，建议使用第三方状态管理库。
experiments
experiments.lazyCompilation
变更内容: 该配置已废弃，改为 dev.lazyCompilation。
迁移示例:
// v2
experiments: {
lazyCompilation: true
}
// v3
dev: {
lazyCompilation: true
}plugins
app-tools 插件
变更内容: 该插件不需要传入任何参数。
迁移示例:
// v2
plugins: [
appTools({
bundler: 'rspack'
})
],
// v3
plugins: [
appTools()
],performance
performance.transformLodash
变更内容: 不再需要，可以直接移除。
迁移示例:
// v2
export default {
performance: {
transformLodash: true
}
}
// v3 - 直接移除该配置
export default {
// 配置...
}