Webpack 5.109.2 是一次补丁版本更新，变化集中在三个容易影响工程稳定性的角落：指向名称以 .js 结尾的包目录的别名、CSS Source Map 中的源文件命名，以及文件系统缓存中失效文件的清理。它没有改变 Webpack 的核心使用方式，但对依赖复杂别名、线上 Source Map 和持久化缓存的项目很实用。
.js 不一定是文件，也可能是目录
常规工程里，something.js 通常表示 JavaScript 文件。但在历史包、内部 SDK 或迁移项目中，也可能存在名称以 .js 结尾的目录，例如：
vendor/
└── widget.js/
└── index.js
当 resolve.alias 指向这类包目录时，解析器既要识别 .js 扩展名，又要继续将目标当作目录解析。Webpack 5.109.2 再次修复了这一特殊场景，降低别名被错误当成普通文件路径的概率。
这不是鼓励新项目采用带 .js 后缀的目录名。更常见的情况是，团队无法立即修改第三方包或历史目录结构，只能在构建层做兼容。
CSS Source Map 和缓存管理更贴近真实工程
本次更新还调整了 CSS Source Map 中源文件的命名：名称根据资源路径生成，不再带有 css 前缀。对于需要将 Source Map 上传到错误监控平台、在浏览器开发者工具中回溯样式来源，或通过脚本分析映射文件的团队，这会让路径更直接。
升级后需要留意一个边界：如果 CI 脚本或 Source Map 上传工具曾经依赖旧的 css... 名称格式，应同步检查路径匹配规则。补丁修复可能让映射结果更合理，但硬编码旧名称的外围工具不会自动适配。
文件系统缓存方面，Webpack 会在存储缓存后，从缓存目录删除不再被引用的文件。这有助于避免长期运行的 CI Runner 或开发机积累无效缓存。它不意味着缓存目录每次都会变得很小，因为当前构建仍然需要的模块、快照和依赖信息会继续保留。
搭一个可验证三个场景的最小项目
下面的示例可以直接在空目录中运行。它包含一个名为 widget.js 的包目录、一个 CSS 文件，以及显式配置的文件系统缓存。
运行前需要准备可用的 Node.js 与 npm 环境。示例将 Webpack 固定到 5.109.2；其他构建插件安装当前可解析版本，真实项目应继续使用自己的锁文件控制版本。
mkdir webpack-5-109-2-demo
cd webpack-5-109-2-demo
npm init -y
npm install --save-dev --save-exact webpack@5.109.2 webpack-cli css-loader mini-css-extract-plugin
mkdir -p src vendor/widget.js
cat > vendor/widget.js/index.js <<'EOF'
export function renderMessage() {
return 'Loaded from the widget.js package directory';
}
EOF
cat > src/index.js <<'EOF'
import { renderMessage } from 'widget';
import './styles.css';
const element = document.createElement('main');
element.className = 'message';
element.textContent = renderMessage();
document.body.appendChild(element);
EOF
cat > src/styles.css <<'EOF'
.message {
max-width: 42rem;
margin: 4rem auto;
color: #1f2937;
font: 600 1.25rem/1.5 system-ui, sans-serif;
}
EOF
cat > webpack.config.js <<'EOF'
const path = require('path');
const MiniCssExtractPlugin = require('mini-css-extract-plugin');
module.exports = {
mode: 'production',
entry: './src/index.js',
devtool: 'source-map',
cache: {
type: 'filesystem',
cacheDirectory: path.resolve(__dirname, '.webpack-cache')
},
resolve: {
alias: {
widget$: path.resolve(__dirname, 'vendor/widget.js')
}
},
module: {
rules: [
{
test: /\.css$/i,
use: [
MiniCssExtractPlugin.loader,
{
loader: 'css-loader',
options: { sourceMap: true }
}
]
}
]
},
plugins: [
new MiniCssExtractPlugin({ filename: 'styles.css' })
],
output: {
path: path.resolve(__dirname, 'dist'),
filename: 'main.js',
clean: true
}
};
EOF
npx webpack
构建成功后，可检查输出、CSS Source Map 的源文件名称和缓存目录：
find dist -maxdepth 1 -type f -print | sort
node -e "const m=require('./dist/styles.css.map'); console.log(m.sources)"
find .webpack-cache -type f | sort | head -20
这里的 widget$ 使用精确匹配，避免 widget/other 等导入被意外重写。若项目确实需要处理子路径，应根据包结构单独设计别名，而不是简单删除 $。
升级时不要只看构建是否成功
Webpack 补丁版本通常适合小步升级，但这次涉及解析、Source Map 和缓存，建议把验证范围扩展到构建产物之外：
- 在
package.json和锁文件中固定或明确记录webpack@5.109.2。 - 运行生产模式构建，并验证名称以
.js结尾的目录别名。 - 检查 CSS Source Map 的
sources字段，以及错误监控平台的上传和匹配结果。 - 在连续执行多次构建后观察文件系统缓存目录，确认 CI 工作区不会持续堆积失效文件。
- 如果升级后出现难以解释的缓存问题，先删除缓存目录再重建，以区分旧缓存影响和真实回归：
rm -rf node_modules/.cache/webpack .webpack-cache dist
npm ci
npx webpack --mode production
对于没有特殊目录别名、没有消费 CSS Source Map、也未启用文件系统缓存的项目，这次升级的可见变化可能很少。反过来，如果工程同时具备这些特征，5.109.2 值得尽快进入测试流水线，但仍应让插件兼容性、Source Map 上传和冷启动构建各跑一遍。