Webpack 在构建完成后会做一次性能体检，如果发现入口点体积或者单个资产体积超过设定阈值，就会在命令行里打印警告甚至报错。控制这个判定标准的核心配置就是performance.maxEntrypointSize。很多初次接触这个配置的开发者容易把它和maxAssetSize混淆，导致调整了半天警告依然存在。这篇文章会把入口点体积的概念讲清楚，并给出配置方法与排查超标体积的完整思路。
入口点体积到底是什么概念
要理解maxEntrypointSize，先得明白Webpack里“入口点”的含义。入口点是构建的起点，通常在entry里配置，比如一个SPA应用往往只有一个main入口，而多页应用可能有index、login、admin等多个入口。Webpack在计算入口点体积时，并不是只算入口文件本身的大小，而是把该入口点在初始加载阶段所有关联的资产加起来，包括入口chunk及其同步依赖的chunk、以及这些chunk通过link或script标签引入的CSS文件。
这个算法上的细节很关键：入口点体积统计的是初始加载的资源总和，异步加载的chunk不计入其中。假设你的入口chunk只有80KB，但它同步引用了一个120KB的公共chunk和一个60KB的CSS文件，那么入口点体积就是260KB，超过了默认的250KB阈值，警告就出现了。而通过import()动态引入的模块，只有在被按需加载时才生效，不会推高入口点的数值。
默认值方面，Webpack 4之后的默认maxEntrypointSize是250000字节，约等于244KB。这个数字是社区对首屏关键资源的一个经验值，来源于Google早期关于首屏加载性能的研究，目的是提醒开发者控制首屏请求数据量。maxAssetSize同样是250000，但两者的区别在于：maxAssetSize针对的是单个文件，任何一个产出文件超了都会触发提示；maxEntrypointSize针对的是一组文件的加和，只有汇总值超标才提示。理解了这一点，调参才不会张冠李戴。
如何配置maxEntrypointSize
配置写在webpack配置文件的performance字段下，下面是一个典型示例：
// webpack.config.js
module.exports = {
// ... 其他配置
performance: {
// 提示级别：false关闭、'warning'警告、'error'报错
hints: 'warning',
// 入口点最大体积，单位是字节
maxEntrypointSize: 400000,
// 单个资产最大体积，单位是字节
maxAssetSize: 300000,
// 过滤规则，只检查js和css文件
assetFilter: function(assetFilename) {
return !/\.map$/.test(assetFilename) &&
/\.(js|css)$/.test(assetFilename);
}
}
};
hints的取值决定了超限后的行为：false表示完全不做性能检查；'warning'只在控制台打印黄色警告，构建不会失败；'error'则会把警告升级为错误，通常配合CI流水线使用，一旦体积超标就让构建挂掉，防止体积劣化被悄悄合入主干。assetFilter则用来缩小统计范围，上面的例子把source map排除在外，只关注js和css，这样统计结果更贴近真实的首屏资源。
关于阈值该设成多少，没有标准答案，需要结合业务场景。如果是管理后台这类内网系统，首屏资源放宽到500KB甚至1MB都可以接受；如果面向移动端C端用户，尤其是弱网环境，建议把阈值压在200KB以内，甚至更激进一些。一个实用的做法是先跑一次构建，看控制台报告的实际入口体积，再结合产品对加载速度的要求反推一个有约束力但又不会天天报警的数值，让它真正起到监控作用而不是被随手关掉。
入口体积超标后的排查与优化
配置阈值只是手段，真正有价值的是当警告出现后如何把体积降下来。第一步是搞清楚体积都花在了哪里。可以先用命令行加上--json参数输出完整的构建信息，再借助webpack-bundle-analyzer生成可视化的体积分布图，直观看到每个模块在bundle里占的比重。实践中最常见的元凶包括：误引入了完整版的工具库（比如lodash整包而非按需引入）、打包了体积巨大的字体或polyfill、以及第三方SDK没有做 Tree Shaking。
定位到问题后，优化的主要思路是代码分割。下面这个配置结合了SplitChunksPlugin和动态导入，能显著压缩入口点体积：
// webpack.config.js
const path = require('path');
module.exports = {
entry: './src/index.js',
output: {
filename: '[name].[contenthash].js',
path: path.resolve(__dirname, 'dist')
},
optimization: {
splitChunks: {
chunks: 'all',
// 抽离的公共包最小体积
minSize: 20000,
cacheGroups: {
// 第三方库单独成组，配合CDN缓存
vendors: {
test: /[\\/]node_modules[\\/]/,
name: 'vendors',
chunks: 'initial',
priority: 10
}
}
}
},
performance: {
hints: 'warning',
maxEntrypointSize: 250000
}
};
需要注意的是，SplitChunksPlugin抽出来的包如果标记为initial，依然会算进入口点体积，因为它还是首屏同步加载的。所以更彻底的做法是动态导入：把路由级组件、图表库、编辑器这类重组件改成import()异步加载，让它们从入口点统计中彻底剥离出去，用户点击到对应功能时才拉取。此外，配合Gzip或Brotli压缩、图片压缩、moment换成dayjs等手段，入口体积往往能降下来一大截。
最后提一个容易踩的坑：有些团队为了消除警告直接把hints设成false，这种做法等于把性能监控的探针拔掉了。更推荐的方式是保留warning级别作为日常提醒，同时在CI环境中用error级别加一道硬性门槛，并用webpack-bundle-analyzer跟踪每次构建的体积变化。体积优化是一场持久战，maxEntrypointSize的价值不在于它的默认数字，而在于它让入口体积变成一个可见、可度量、可约束的指标，这才是这个配置真正的意义所在。
WebpackmaxEntrypointSize性能优化修改时间：2026-09-07 13:04:36