webpack 极容易混淆的 path、publicPath、contentBase 配置

Question

最近在写一个 Webpack + React 的 Demo，关于涉及路径参数配置很容易混淆，所以写这篇文章整理一下。

以下关于 webpack-dev-server 会简写成 dev-server 或者 devServer。

总结：

• output.path 表示 output 目录对应的一个绝对路径。
• output.publicPath 表示打包生成的 index.html 文件里面引用资源的前缀。
• devServer.publicPath 表示打包生成的静态文件所在的位置，若 devServer.publicPath 没有设置，则会取 output.publicPath 的值。
• devServer.contentBase 表示服务器从哪里提供内容。一般只有在提供静态文件时才需要。

基本配置

写一个简单的项目，没有过多的东西，足以说明本文的几个配置项即可，目录结构如下：

my-project
  src
    index.css // 仅设置了一个背景图片
    index.html // 简单的一个 HTML 作为模板而已，随意写个 div 标签啥的就 OK 了
    index.js // 仅引用了 index.css
  package.json
  webpack.config.js

项目里面 index.js、index.css、index.html 里面其实没什么内容的，就如上面备注一样而已。

// package.json
{
  "scripts": {
    "build": "webpack",
    "dev": "webpack-dev-server"
  }
}

// webpack.config.js
const path = require('path')
const webpack = require('webpack')
const HtmlWebpackPlugin = require('html-webpack-plugin')
const MiniCssExtractPlugin = require('mini-css-extract-plugin')
const { CleanWebpackPlugin } = require('clean-webpack-plugin')

module.exports = {
  entry: './src/index.js',
  output: {
    filename: 'bundle.js',
    path: path.resolve(__dirname, 'dist')
  },
  devServer: {
    open: true
  },
  plugins: [
    new HtmlWebpackPlugin({
      title: 'webpack demo',
      template: './src/index.html',
      filename: 'index.html',
      inject: true,
      hash: false
    }),
    new CleanWebpackPlugin(),
    new MiniCssExtractPlugin({
      filename: 'style.css'
    })
  ],
  module: {
    rules: [
      {
        test: /\.css$/,
        exclude: /node_modules/,
        use: [MiniCssExtractPlugin.loader, 'css-loader']
      },
      {
        test: /\.(png|jpg|gif)$/,
        loader: 'file-loader',
        options: {
          name: '[name].[ext]'
        }
      }
    ]
  }
}

1. output.path

• 默认值：path.join(process.cwd(), 'dist')

指定输出文件的目标路径。它是一个绝对路径，默认是项目根目录下的 dist 路径。项目中经常会看到如下配置：

output: {
  path: path.resolve(__dirname, 'dist')
}

简单地说，就是运行 yarn run build 命令，webpack 将项目打包之后的文件（如 index.html、bundle.js、图片等）输出到该目录。这个还是比较好理解的。

2. output.publicPath

• 默认值：''（空字符串）

output.publicPath 常用于在生产环境。它会为所有的资源指定一个基础路径，它被称为公共路径。

如何理解？

这里所说的所有资源的基础路径是指项目中引用 CSS、JS、Image 等资源时候的一个基础路径。这个基础路径要配合具体资源中指定的路径使用，所以打包后的资源的访问可以用如下公式表示：

静态资源最终访问路径 = output.publicPath + 资源 loader 或插件等配置路径

这个最终静态资源访问路径在使用 html-webpack-plugin 打包后得到的 html 中可以看到。如果 output.publicPath 设置成相对路径后，相对路径是相应地打包后的 html 的。

假设 output.publicPath 设置成了 './dist/'，那么打包后的 JS 引用路径为 ./dist/main.js。这里会存在一个问题，相对路径在本地能正常访问到。但是如果把静态资源托管到 CDN 上，访问路径显然不能使用相对路径的。如果设置成 '/dist/'，则打包后的访问路径是 localhost:8080/dist/main.js，此时本地无法访问。一般解决方法就是利用 webpack.DefinePlugin 来定义一个全局变量（process.env.NODE_ENV）区分开发、生产环境来设定不同的值，或者是采用两份不同的配置文件来进行打包。

一般来说，output.publicPath 应该以 '/' 结尾，而其他 loader 或插件的配置不要以 '/' 开头。

案例：

output.publicPath = '/dist/'


// 案例一（image file-loader）
options: {
  name: 'img/[name].[ext]'
}
// 最终路径：output.publicPath + 'img/[name].[ext]' = '/dist/img/[name].[ext]'


// 案例二（js output.filename）
output: {
  filename: '[name].js'
}
// 最终路径：output.publicPath + '[name].js' = '/dist/[name].js'


// 案例三（extract-text-webpack-plugin css）
new ExtractTextPlugin({
  filename: 'style.[chunkhash].css'
})
// 最终路径：output.publicPath + 'style.[chunkhash].css' = '/dist/style.[chunkhash].css'

我们修改一下 output.publicPath 配置，如下：

// webpack.config.js
const path = require('path')
module.exports = {
  output: {
    filename: 'bundle.js',
    path: path.resolve(__dirname, 'dist'),
    publicPath: '/outputDir/'
  }
}

运行 yarn run dev 命令，可以看到命令行显示如下信息：

ℹ ｢wds｣: Project is running at http://localhost:8080/
ℹ ｢wds｣: webpack output is served from /outputDir/

然后，访问 http://localhost:8080/ 结果如下：

访问 http://localhost:8080/outputDir/ 结果如下：

根据上面两张图可以看出，设置 output.publicPath 后，如果 devServer.publicPath 没有设置，那么使用 webpack-dev-server 进行打包时生成的静态文件所在的位置以及 index.html 文件里面引用资源的前缀都是 output.publicPath 里面设置的值。

3. devServer.publicPath

默认值：'/'

插句话，斜杠 / 的含义表示 URL 的根路径，例如 http://localhost:8080/dist/main.js 中的 http://localhost:8080/。

在开发过程中，我们借用 webpack-dev-server 启动一个开发服务器，我们一般也会配置一个 devServer.publicPath，这里的 devServer.publicPath 路径下的打包文件可以在浏览器中访问。而静态资源仍然使用 output.publicPath。

webpack-dev-server 打包的内容是放在内存中的，这些打包后的资源对外的根目录就是 devServer.publicPath，换句话说，这里我们设置的是打包后资源存放的位置。

假设 devServer.publicPath = '/dist/'
那么，启动 webpack-dev-server 后 index.html 路径为 publicPath + index.html
那么，启动 webpack-dev-server 后 main.js 路径为 publicPath + main.js

以上这些，通过访问 http://localhost:8080/webpack-dev-server 可以看到启动后的资源访问路径。点击里面的静态资源文件可以看到路径为 http://localhost:8080${publicPath}index.html。

接着，我们修改一下 devServer.publicPath 的配置，如下：

// webpack.config.js
module.exports = {
  output: {
    filename: 'bundle.js',
    path: path.resolve(__dirname, 'dist'),
    publicPath: '/outputDir/'
  },
  devServer: {
    publicPath: '/assets/'
    open: true
  }
}

执行 yarn run dev 命令 ，命令行显示如下信息（我们看到跟此前不一样了）：

ℹ ｢wds｣: Project is running at http://localhost:8080/
ℹ ｢wds｣: webpack output is served from /assets/

然后，访问 http://localhost:8080/ 结果如下：

访问 http://localhost:8080/assets/ 结果如下：

我们发现 JS 和 CSS 文件的引用路径还是没变，但是我们发现页面的背景图片没有了，因为它报错了，CSS 和 JS 都找不到，如下：

可以看出，devServer.publicPath 表示打包生成的静态文件所在的位置。并且它的优先级是最高的。而 output.publicPath 表示 index.html 文件里面引用资源的前缀。

4. devServer.contentBase

• 默认值：process.cwd()（即当前工作目录）

只有在你想要提供静态文件时才需要。

接着，添加 devServer.contentBase 配置，如下：

// webpack.config.js
module.exports = {
  output: {
    filename: 'bundle.js',
    path: path.resolve(__dirname, 'dist'),
    publicPath: '/outputDir/'
  },
  devServer: {
    contentBase: './aaa',
    publicPath: '/assets/',
    open: true
  }
}

执行 yarn run dev 命令，命令行显示信息如下：

ℹ ｢wds｣: Project is running at http://localhost:8080/
ℹ ｢wds｣: webpack output is served from /assets/
ℹ ｢wds｣: Content not from webpack is served from ./aaa

可以发现有一条是：Content not from webpack is served from ./aaa，可以看出 devServer.contentBase 指的是，不由 webpack 打包生成的静态文件。

访问 http://localhost:8080/ 结果如下：

因为 http://localhost:8080/ 下并没有 aaa 目录，所以根本找不到。而前面没有设置 devServer.contentBase 的时候，会使用 contentBase 的默认值（当前执行的目录，即项目根目录）。在访问 http://localhost:8080/ 时，由于在根目录下没有找到 index.html 文件，因此会显示根目录下的资源文件。

访问 http://localhost:8080/assets/，结果如下：

可见，devServer.contentBase 与打包生成的静态文件所在的位置和 index.html 里面引用资源的前缀是没有影响的。

接着，我们再修改一下 devServer.contentBase 的配置，将其设置为 src 目录，而该目录下是有我们编写的 index.html 模板文件的。

// webpack.config.js
module.exports = {
  output: {
    filename: 'bundle.js',
    path: path.resolve(__dirname, 'dist'),
    publicPath: '/outputDir/'
  },
  devServer: {
    contentBase: './src',
    publicPath: '/assets/',
    open: true
  }
}

访问 http://localhost:8080/，结果如下：

可以看出，访问的是我们本地编写的 index.html 文件。请注意，这个不是 webpack 打包生成的 index.html 文件。

5. html-webpack-plugin

这个插件用于将 CSS 和 JS 添加到 HTML 模板中，其中 template 和 filename 会受到路径的影响。

template

作用是用于定义模板文件的路径。

// 源码
this.options.template = this.getFullTemplatePath(this.options.template, compiler.context)

因此，template 只有定义在 webpack 的 context 才会被识别，webpack 的 context 默认值为 process.cwd()，即运行 node 命令时所在的文件夹的绝对路径。

filename

作用是输出的 HTML 文件名，默认为 index.html，可以直接配置带有子目录。

// 源码
this.options.filename = path.relative(compiler.options.output.path, filename)

所以 filename 的路径是相当于 output.path 的，而在 webpack-dev-server 中，则是相当于 devServer.publicPath 的。

如果 devServer.publicPath 和 output.publicPath 不一致，在使用 html-webpack-plugin 可能会导致引用静态资源失败，因为在 devServer 中仍然以 output.publicPath 引用静态资源的，当跟 webpack-dev-server 的提供的资源访问路径不一致，从而无法正常访问。

有一种情况除外，就是 output.publicPath 是相对路径，这时候可以访问本地资源。

所以一般情况下，都要保证 devServer.publicPath 与 output.publicPath 保持一致。

参考

• webpack 中的 path、publicPath 和 contentBase
• Webpack 中 publicPath 详解