Webpack 的 performance 配置是很多人容易忽略的一个角落，但它在控制打包体积方面其实相当实用。当你在打包时看到控制台输出类似 "asset exceeds recommended size limit" 的黄色警告，背后起作用的就是 performance.maxAssetSize 这个配置项。它定义了单个资源文件允许的最大体积，单位是字节，默认值是 250000，也就是大约 244KB。任何超出这个阈值的文件，只要 hints 开启，都会在构建结果里被点名提示。
maxAssetSize 的基本配置与默认行为
先看一个最简单的配置写法：
module.exports = {
performance: {
hints: 'warning', // 开启警告提示，可选值：false | 'warning' | 'error'
maxAssetSize: 300000, // 单个资源最大 300000 字节，约 293KB
maxEntrypointSize: 500000 // 入口文件最大 500000 字节
}
};这里有个关键点需要理解：maxAssetSize 本身只是定义了一个阈值，真正决定是否提示的是 hints 属性。如果 hints 是 false 或者没有设置，即使资源超过 maxAssetSize，Webpack 也不会输出任何警告。所以在实际项目中，如果发现自己设置了体积限制却没生效，第一个要检查的就是有没有把 hints 打开。
另外要注意单位是字节而不是 KB。很多新手直接写 maxAssetSize: 300，以为限制了 300KB，实际上是 300 字节，结果打包时几乎所有资源都在报警告。如果想用更直观的写法，可以这样处理：
module.exports = {
performance: {
hints: 'warning',
// 用 KB 乘以 1024 换算成字节，语义更清晰
maxAssetSize: 300 * 1024
}
};警告信息在构建时会明确指出哪个文件超了多大，比如输出中会包含文件名、实际体积和限制值，这对定位问题很有帮助。如果团队希望严格管控，可以把 hints 设为 'error'，这样超标的资源会直接导致构建失败，配合 CI 流水线可以阻止带体积问题的代码被合并或发布。
maxAssetSize 与 maxEntrypointSize 的区别
这两个配置经常被混淆。maxAssetSize 针对的是单个资源文件，也就是打包产物中的每一个 js、css、图片等文件，任何一个超过阈值都会被单独提示。而 maxEntrypointSize 针对的是入口文件，它统计的是该入口在初始加载阶段所有资源的总体积，包括入口本身以及通过 import 或 require 静态引入的依赖。
举个例子，假设有一个入口 main.js 打包后自身是 200KB，它同步引入的 chunk 又有 150KB，那么入口总体积就是 350KB。如果 maxEntrypointSize 设置为 300KB，即使每个文件都没超过 maxAssetSize，这个入口依然会触发提示。这两个指标是从不同维度衡量性能的：前者防止单个文件过大，后者防止首屏加载的资源总量失控。
实际配置时建议两者都设置，数值可以根据业务场景调整。一般 SPA 项目可以把 maxEntrypointSize 设得比 maxAssetSize 大一些，比如入口限制 500KB、单个资源限制 300KB，这样既能容忍合理的依赖聚合，又不会放过异常巨大的单个文件。
用 assetFilter 过滤不需要检测的资源
有些资源天然体积偏大，比如地图数据、字体文件、wasm 模块等，它们不参与首屏关键路径，却会频繁触发警告。Webpack 提供了 assetFilter 函数来解决这个问题：
module.exports = {
performance: {
hints: 'warning',
maxAssetSize: 300 * 1024,
maxEntrypointSize: 500 * 1024,
assetFilter: function(assetFilename) {
// 只检测 js 和 css 文件，字体、图片、地图数据等直接忽略
return /\.(js|css)$/.test(assetFilename);
}
}
};这个函数接收资源的文件名，返回 true 表示该资源纳入体积检测，返回 false 则完全跳过。上面的写法只关注 js 和 css，因为这两类文件直接影响执行和渲染时机，而字体或图片通常有独立的加载策略（比如懒加载、预加载），一刀切的体积限制意义不大。
需要提醒的是，assetFilter 过滤的资源在统计入口体积时同样会被排除吗？答案是否定的，这个函数只影响单个资源维度的检测，入口体积的计算逻辑是独立的。所以在优化首屏指标时，不能只依赖 assetFilter 把大文件排除掉就万事大吉，还是需要从代码分割、按需加载的角度真正减小入口体积。
在开发与生产环境采用不同策略
一个比较推荐的实践是按环境区分 hints 的级别。开发环境下警告信息会干扰调试，可以关掉；生产构建则开启 error 级别做强约束：
module.exports = (env, argv) => {
const isProd = argv.mode === 'production';
return {
performance: {
hints: isProd ? 'error' : false,
maxAssetSize: 300 * 1024,
maxEntrypointSize: 500 * 1024,
assetFilter: (name) => /\.(js|css)$/.test(name)
}
};
};这样配置后，本地开发不受警告干扰，而线上构建一旦有文件超标就会直接失败，问题能在发布前就被拦截。需要注意的是，如果构建因为体积报错，不要急着调大阈值去绕过，正确的做法是分析超标文件的内容，比如用打包分析工具看看是哪个依赖占了体积，再决定是做代码分割、动态导入还是替换成更轻量的库。
总结一下，performance.maxAssetSize 是一个低成本高收益的体积管控手段。它不参与真正的压缩优化，但能把体积问题前置到构建阶段暴露出来，配合 maxEntrypointSize 和 assetFilter，基本可以覆盖常见的体积监控需求。建议在新项目初始化时就把它加上，让体积红线从第一天起就清晰可见。
WebpackmaxAssetSizeperformance 配置修改时间：2026-09-08 13:12:55