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