Webpack 的核心工作可以概括为一句话：从 entry 指定的入口出发，把项目中所有依赖的模块打包成浏览器可用的静态资源，而这一切的最终去向，就由 output 配置来决定。如果 entry 是起点，那么 output 就是终点。output 配置告诉 Webpack 把打包产物写到哪里、文件名如何命名、引用资源的公共路径前缀是什么。看似简单的几个选项，实际使用中却隐藏着不少细节，比如占位符的灵活运用、多入口时的命名规则、path 与 publicPath 的语义区别等。本文将围绕这些内容逐一展开，配合完整的配置示例，帮助你真正理解并掌握 output 的用法。
output 基础配置：path 与 filename
output 是一个对象，最基础的两个属性是 path 和 filename。path 指定打包产物输出的绝对路径目录，filename 指定输出文件的名称。需要注意的是，path 必须是绝对路径，通常会借助 Node.js 的 path.resolve() 来拼接：
const path = require('path');
module.exports = {
entry: './src/index.js',
output: {
path: path.resolve(__dirname, 'dist'),
filename: 'bundle.js'
}
};上面的配置表示：将打包结果输出到项目根目录下的 dist 文件夹中，文件名为 bundle.js。如果不显式配置 path，Webpack 默认会输出到 dist 目录；如果不配置 filename，默认值为 main.js。
filename 支持使用占位符来动态生成文件名，这是实际项目中最常用的技巧。常用占位符包括：
[name]：入口文件的名称，或 chunk 的名称[hash]：每次构建的唯一哈希值，整次构建中所有文件共享同一个 hash[chunkhash]：基于每个 chunk 内容生成的哈希，内容不变则哈希不变[contenthash]：基于文件内容生成的哈希，常用于提取出的 CSS 文件[id]：chunk 的内部编号
在生产环境中，为了利用浏览器缓存，通常会写成 filename: 'js/[name].[contenthash:8].js'。其中 :8 表示只取哈希值的前 8 位，避免文件名过长。contenthash 的好处是文件内容不变时哈希不变，浏览器可以继续使用缓存，只有内容真正变化的文件才会生成新的文件名。
publicPath 与 path 的区别及用法
初学者最容易混淆的就是 path 和 publicPath 这两个选项。简单来说：path 决定文件写到哪里（物理存储位置），而 publicPath 决定浏览器从哪里加载这些资源（URL 前缀）。两者一个面向文件系统，一个面向网络请求，是完全不同维度的配置。
const path = require('path');
module.exports = {
output: {
path: path.resolve(__dirname, 'dist'),
filename: 'js/[name].[contenthash:8].js',
publicPath: 'https://cdn.ipipp.com/assets/'
}
};上面的配置中，打包文件物理上写入本地的 dist/js 目录，但 HTML 中引用的 script 标签地址会是 https://cdn.ipipp.com/assets/js/xxx.js。这种做法在资源托管到 CDN 的场景中非常常见：构建产物上传到 CDN 服务器，页面通过 publicPath 指定的域名去加载。
publicPath 还有一些特殊取值需要了解：
'auto'：让 Webpack 自动推断，从 Webpack 5 开始这是默认值，会根据当前页面的 URL 推断出资源路径'/'：表示资源挂载在域名根路径下，例如/js/main.js'./'：相对路径，适合不部署在服务器根目录、而是放在任意子目录下的静态站点
一个典型的坑是：本地开发时页面正常，部署到服务器子目录后白屏，控制台报 404。这往往是因为 publicPath 默认取了根路径，而实际资源在子目录下。此时把 publicPath 改为 './' 或与部署目录一致的路径即可解决。
多入口配置与 clean 选项
当项目存在多个入口时，output.filename 中的 [name] 占位符就派上用场了。多入口配置下，每个入口会生成独立的 chunk，[name] 会被替换成对应的入口名称：
const path = require('path');
module.exports = {
entry: {
index: './src/index.js',
login: './src/login.js'
},
output: {
path: path.resolve(__dirname, 'dist'),
filename: 'js/[name].[contenthash:8].js',
clean: true
}
};这个配置会输出 dist/js/index.xxxxxxxx.js 和 dist/js/login.xxxxxxxx.js 两个文件。需要注意的是，多入口时 filename 中必须包含 [name]、[id] 或 [hash] 这类占位符，否则多个 chunk 会写入同一个文件名导致冲突报错。
另一个值得关注的选项是 clean。Webpack 5 之前，每次重新构建时旧的哈希文件会残留在 dist 目录中，越积越多，通常需要借助 CleanWebpackPlugin 来清理。Webpack 5 将这个能力内置了，只需设置 clean: true，每次构建前就会自动清空输出目录，不再需要额外安装插件。如果需要保留某些特定文件，还可以传入一个对象进行精细控制：
module.exports = {
output: {
clean: {
keep: /assets\/logo\.png/ // 构建时保留 logo 文件不被清除
}
}
};除了上述核心选项，还有几个常用的配置值得了解。assetModuleFilename 用于指定资源模块（图片、字体等，通过 asset modules 处理）的输出文件名，例如 'assets/[hash][ext][query]'；library 与 libraryTarget 用于将打包产物输出为一个可被其他程序引用的库；chunkFilename 用于指定非入口 chunk（如动态导入产生的 chunk）的文件名。这些选项在库开发和代码分割场景中使用频率很高。
常见问题与最佳实践
关于 hash 的选择，官方推荐遵循这样的原则：开发环境用 [name].js 即可，方便调试；生产环境入口 JS 用 [contenthash]，提取的 CSS 文件也用 [contenthash]，这样能最大化缓存命中。避免使用 [hash]，因为它与整次构建绑定，任何一个模块变化都会导致所有文件名改变，缓存利用率最低。
开发环境与生产环境的 output 配置建议分开维护。开发环境通常不关心文件名哈希，配合 devServer 使用时甚至不需要真实写入磁盘；生产环境则要配置带哈希的文件名、正确的 publicPath 以及 clean 选项。通过导出函数形式的配置或使用 webpack-merge 合并，可以优雅地管理两套配置的差异。
最后总结一下 output 配置的记忆要点：path 管物理位置且必须绝对路径，publicPath 管 URL 前缀，filename 靠占位符动态命名，clean 负责清理旧产物，多入口必须带 [name] 占位符。掌握这些核心选项后，再遇到打包路径 404、缓存失效、产物目录混乱等问题时，就能快速定位到 output 配置层面并妥善解决。
Webpack output配置输出选项前端构建修改时间：2026-09-01 11:00:55