html设置basepath,webpack中极容易混淆的path、publicPath、contentBase配置

最近在写一个 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 保持一致。

参考