【前端工程化】webpack5从零搭建完整的react18+ts开发和打包环境

目录

1.前言
2.初始化项目
3.配置基础版react+ts环境
4.常用功能配置
5.配置react模块热替换
6.优化构建速度
7.优化构建结果文件
8.总结

全文概览

一. 前言

从2020年10月10日，webpack 升级至 5 版本到现在已经快两年，webpack5版本优化了很多原有的功能比如tree-shaking优化，也新增了很多新特性，比如联邦模块，具体变动可以看这篇文章阔别两年，webpack 5 正式发布了！。

本文将使用最新的webpack5一步一步从零搭建一个完整的react18+ts开发和打包环境，配置完善的模块热替换以及构建速度和构建结果的优化，完整代码已上传到webpack5-react-ts。本文只是配置webpack的，配置代码规范相关的可以看这篇文章搭建react18+vite2+ts+prettier+eslint+lint-staged+husky+stylelint开发环境

二. 初始化项目

在开始webpack配置之前，先手动初始化一个基本的react+ts项目，新建项目文件夹webpack5-react-18, 在项目下执行

npm init -y 

初始化好package.json后,在项目下新增以下所示目录结构和文件

├── build
| ├── webpack.base.js # 公共配置
| ├── webpack.dev.js# 开发环境配置
| └── webpack.prod.js # 打包环境配置
├── public
│ └── index.html # html模板
├── src
| ├── App.tsx 
│ └── index.tsx # react应用入口页面
├── tsconfig.json# ts配置
└── package.json 

安装webpack依赖

npm i webpack webpack-cli -D 

安装react依赖

npm i react react-dom -S 

安装react类型依赖

npm i @types/react @types/react-dom -D 

添加public/index.html内容

添加tsconfig.json内容

{"compilerOptions": {"target": "ESNext","lib": ["DOM", "DOM.Iterable", "ESNext"],"allowJs": false,"skipLibCheck": false,"esModuleInterop": false,"allowSyntheticDefaultImports": true,"strict": true,"forceConsistentCasingInFileNames": true,"module": "ESNext","moduleResolution": "Node","resolveJsonModule": true,"isolatedModules": true,"noEmit": true,"jsx": "react", // react18这里也可以改成react-jsx},"include": ["./src"]
} 

添加src/App.tsx内容

import React from 'react'

function App() {return 
webpack5-react-ts
}
export default App 

添加src/index.tsx内容

import React from 'react';
import { createRoot } from 'react-dom/client';
import App from './App';

const root = document.getElementById('root');
if(root) {createRoot(root).render()
} 

现在项目业务代码已经添加好了,接下来可以配置webpack的代码了。

三. 配置基础版React+ts环境

2.1. webpack公共配置

修改webpack.base.js

1. 配置入口文件

// webpack.base.js
const path = require('path')

module.exports = {entry: path.join(__dirname, '../src/index.tsx'), // 入口文件
} 

2. 配置出口文件

// webpack.base.js
const path = require('path')

module.exports = {// ...// 打包文件出口output: {filename: 'static/js/[name].js', // 每个输出js的名称path: path.join(__dirname, '../dist'), // 打包结果输出路径clean: true, // webpack4需要配置clean-webpack-plugin来删除dist文件,webpack5内置了publicPath: '/' // 打包后文件的公共前缀路径},
} 

3. 配置loader解析ts和jsx

由于webpack默认只能识别js文件,不能识别jsx语法,需要配置loader的预设预设 @babel/preset-typescript 来先ts语法转换为 js 语法,再借助预设 @babel/preset-react 来识别jsx语法。

安装babel核心模块和babel预设

npm i babel-loader @babel/core @babel/preset-react @babel/preset-typescript -D 

在webpack.base.js添加module.rules配置

// webpack.base.js
module.exports = {// ...module: {rules: [{test: /.(ts|tsx)$/, // 匹配.ts, tsx文件use: {loader: 'babel-loader',options: {// 预设执行顺序由右往左,所以先处理ts,再处理jsxpresets: ['@babel/preset-react','@babel/preset-typescript']}}}]}
} 

4. 配置extensions

extensions是webpack的resolve解析配置下的选项，在引入模块时不带文件后缀时，会来该配置数组里面依次添加后缀查找文件，因为ts不支持引入以 .ts, tsx为后缀的文件，所以要在extensions中配置，而第三方库里面很多引入js文件没有带后缀，所以也要配置下js

修改webpack.base.js，注意把高频出现的文件后缀放在前面

// webpack.base.js
module.exports = {// ...resolve: {extensions: ['.js', '.tsx', '.ts'],}
} 

这里只配置js, tsx和ts，其他文件引入都要求带后缀，可以提升构建速度。

4. 添加html-webpack-plugin插件

webpack需要把最终构建好的静态资源都引入到一个html文件中,这样才能在浏览器中运行,html-webpack-plugin就是来做这件事情的,安装依赖：

npm i html-webpack-plugin -D 

因为该插件在开发和构建打包模式都会用到,所以还是放在公共配置webpack.base.js里面

// webpack.base.js
const path = require('path')
const HtmlWebpackPlugin = require('html-webpack-plugin')

module.exports = {// ...plugins: [new HtmlWebpackPlugin({template: path.resolve(__dirname, '../public/index.html'), // 模板取定义root节点的模板inject: true, // 自动注入静态资源})]
} 

到这里一个最基础的react基本公共配置就已经配置好了,需要在此基础上分别配置开发环境和打包环境了。

2.2. webpack开发环境配置

1. 安装 webpack-dev-server

开发环境配置代码在webpack.dev.js中,需要借助 webpack-dev-server在开发环境启动服务器来辅助开发,还需要依赖webpack-merge来合并基本配置,安装依赖:

npm i webpack-dev-server webpack-merge -D 

修改webpack.dev.js代码, 合并公共配置，并添加开发模式配置

// webpack.dev.js
const path = require('path')
const { merge } = require('webpack-merge')
const baseConfig = require('./webpack.base.js')

// 合并公共配置,并添加开发环境配置
module.exports = merge(baseConfig, {mode: 'development', // 开发模式,打包更加快速,省了代码优化步骤devtool: 'eval-cheap-module-source-map', // 源码调试模式,后面会讲devServer: {port: 3000, // 服务端口号compress: false, // gzip压缩,开发环境不开启,提升热更新速度hot: true, // 开启热更新，后面会讲react模块热替换具体配置historyApiFallback: true, // 解决history路由404问题static: {directory: path.join(__dirname, "../public"), //托管静态资源public文件夹}}
}) 

2. package.json添加dev脚本

在package.json的scripts中添加

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

执行npm run dev,就能看到项目已经启动起来了,访问http://localhost:3000/,就可以看到项目界面,具体完善的react模块热替换在下面会讲到。

2.3. webpack打包环境配置

1. 修改webpack.prod.js代码

// webpack.prod.js

const { merge } = require('webpack-merge')
const baseConfig = require('./webpack.base.js')
module.exports = merge(baseConfig, {mode: 'production', // 生产模式,会开启tree-shaking和压缩代码,以及其他优化
}) 

2. package.json添加build打包命令脚本

在package.json的scripts中添加build打包命令

"scripts": {"dev": "webpack-dev-server -c build/webpack.dev.js","build": "webpack -c build/webpack.prod.js"
}, 

执行npm run build,最终打包在dist文件中, 打包结果:

dist├── static
| ├── js
| ├── main.js
├── index.html 

3. 浏览器查看打包结果

打包后的dist文件可以在本地借助node服务器serve打开,全局安装serve

npm i serve -g 

然后在项目根目录命令行执行serve -s dist,就可以启动打包后的项目了。

到现在一个基础的支持react和ts的webpack5就配置好了,但只有这些功能是远远不够的,还需要继续添加其他配置。

四. 基础功能配置

4.1 配置环境变量

环境变量按作用来分分两种

1.区分是开发模式还是打包构建模式
2.区分项目业务环境,开发/测试/预测/正式环境

区分开发模式还是打包构建模式可以用process.env.NODE_ENV,因为很多第三方包里面判断都是采用的这个环境变量。

区分项目接口环境可以自定义一个环境变量process.env.BASE_ENV,设置环境变量可以借助cross-env和webpack.DefinePlugin来设置。

• cross-env：兼容各系统的设置环境变量的包
• webpack.DefinePlugin：webpack内置的插件,可以为业务代码注入环境变量

安装cross-env

npm i cross-env -D 

修改package.json的scripts脚本字段,删除原先的dev和build,改为

"scripts": {"dev:dev": "cross-env NODE_ENV=development BASE_ENV=development webpack-dev-server -c build/webpack.dev.js","dev:test": "cross-env NODE_ENV=development BASE_ENV=test webpack-dev-server -c build/webpack.dev.js","dev:pre": "cross-env NODE_ENV=development BASE_ENV=pre webpack-dev-server -c build/webpack.dev.js","dev:prod": "cross-env NODE_ENV=development BASE_ENV=production webpack-dev-server -c build/webpack.dev.js","build:dev": "cross-env NODE_ENV=production BASE_ENV=development webpack -c build/webpack.prod.js","build:test": "cross-env NODE_ENV=production BASE_ENV=test webpack -c build/webpack.prod.js","build:pre": "cross-env NODE_ENV=production BASE_ENV=pre webpack -c build/webpack.prod.js","build:prod": "cross-env NODE_ENV=production BASE_ENV=production webpack -c build/webpack.prod.js",}, 

dev开头是开发模式,build开头是打包模式,冒号后面对应的dev/test/pre/prod是对应的业务环境的开发/测试/预测/正式环境。

process.env.NODE_ENV环境变量webpack会自动根据设置的mode字段来给业务代码注入对应的development和prodction,这里在命令中再次设置环境变量NODE_ENV是为了在webpack和babel的配置文件中访问到。

在webpack.base.js中打印一下设置的环境变量

// webpack.base.js
// ...
console.log('NODE_ENV', process.env.NODE_ENV)
console.log('BASE_ENV', process.env.BASE_ENV) 

执行npm run build:dev,可以看到打印的信息

// NODE_ENV production
// BASE_ENV development 

当前是打包模式,业务环境是开发环境,这里需要把process.env.BASE_ENV注入到业务代码里面,就可以通过该环境变量设置对应环境的接口地址和其他数据,要借助webpack.DefinePlugin插件。

修改webpack.base.js

// webpack.base.js
// ...
const webpack = require('webpack')
module.export = {// ...plugins: [// ...new webpack.DefinePlugin({'process.env.BASE_ENV': JSON.stringify(process.env.BASE_ENV)})]
} 

配置后会把值注入到业务代码里面去,webpack解析代码匹配到process.env.BASE_ENV,就会设置到对应的值。测试一下，在src/index.tsx打印一下两个环境变量

// src/index.tsx
// ...
console.log('NODE_ENV', process.env.NODE_ENV)
console.log('BASE_ENV', process.env.BASE_ENV) 

执行npm run dev:test,可以在浏览器控制台看到打印的信息

// NODE_ENV development
// BASE_ENV test 

当前是开发模式,业务环境是测试环境。

4.2 处理css和less文件

在src下新增app.css

h2 {color: red;transform: translateY(100px);
} 

在src/App.tsx中引入app.css

import React from 'react'
import './app.css'

function App() {return 
webpack5-rea11ct-ts
}
export default App 

执行打包命令npm run build:dev,会发现有报错, 因为webpack默认只认识js,是不识别css文件的,需要使用loader来解析css, 安装依赖

npm i style-loader css-loader -D 

• style-loader: 把解析后的css代码从js中抽离,放到头部的style标签中(在运行时做的)
• css-loader: 解析css文件代码

因为解析css的配置开发和打包环境都会用到,所以加在公共配置webpack.base.js中

// webpack.base.js
// ...
module.exports = {// ...module: { rules: [// ...{test: /.css$/, //匹配 css 文件use: ['style-loader','css-loader']}]},// ...
} 

上面提到过,loader执行顺序是从右往左,从下往上的,匹配到css文件后先用css-loader解析css, 最后借助style-loader把css插入到头部style标签中。

配置完成后再npm run build:dev打包,借助serve -s dist启动后在浏览器查看,可以看到样式生效了。

4.3 支持less或scss

项目开发中,为了更好的提升开发体验,一般会使用css超集less或者scss,对于这些超集也需要对应的loader来识别解析。以less为例,需要安装依赖:

npm i less-loader less -D 

• less-loader: 解析less文件代码,把less编译为css
• less: less核心

实现支持less也很简单,只需要在rules中添加less文件解析,遇到less文件,使用less-loader解析为css,再进行css解析流程,修改webpack.base.js：

// webpack.base.js
module.exports = {// ...module: {// ...rules: [// ...{test: /.(css|less)$/, //匹配 css和less 文件use: ['style-loader','css-loader', 'less-loader']}]},// ...
} 

测试一下,新增src/app.less

#root {h2 {font-size: 20px;}
} 

在App.tsx中引入app.less,执行npm run build:dev打包,借助serve -s dist启动项目,可以看到less文件编写的样式编译css后也插入到style标签了了。

4.4 处理css3前缀兼容

虽然css3现在浏览器支持率已经很高了, 但有时候需要兼容一些低版本浏览器,需要给css3加前缀,可以借助插件来自动加前缀, postcss-loader就是来给css3加浏览器前缀的,安装依赖：

npm i postcss-loader autoprefixer -D 

• postcss-loader：处理css时自动加前缀
• autoprefixer：决定添加哪些浏览器前缀到css中

修改webpack.base.js, 在解析css和less的规则中添加配置

module.exports = {// ...module: { rules: [// ...{test: /.(css|less)$/, //匹配 css和less 文件use: ['style-loader','css-loader',// 新增{loader: 'postcss-loader',options: {postcssOptions: {plugins: ['autoprefixer']}}},'less-loader']}]},// ...
} 

配置完成后,需要有一份要兼容浏览器的清单,让postcss-loader知道要加哪些浏览器的前缀,在根目录创建 .browserslistrc文件

IE 9 # 兼容IE 9
chrome 35 # 兼容chrome 35 

以兼容到ie9和chrome35版本为例,配置好后,执行npm run build:dev打包,可以看到打包后的css文件已经加上了ie和谷歌内核的前缀

上面可以看到解析css和less有很多重复配置,可以进行提取postcss-loader配置优化一下

postcss.config.js是postcss-loader的配置文件,会自动读取配置,根目录新建postcss.config.js：

module.exports = {plugins: ['autoprefixer']
} 

修改webpack.base.js, 取消postcss-loader的options配置

// webpack.base.js
// ...
module.exports = {// ...module: { rules: [// ...{test: /.(css|less)$/, //匹配 css和less 文件use: ['style-loader','css-loader','postcss-loader','less-loader']},]},// ...
} 

提取postcss-loader配置后,再次打包,可以看到依然可以解析css, less文件, css3对应前缀依然存在。

4.5 babel预设处理js兼容

现在js不断新增很多方便好用的标准语法来方便开发,甚至还有非标准语法比如装饰器,都极大的提升了代码可读性和开发效率。但前者标准语法很多低版本浏览器不支持,后者非标准语法所有的浏览器都不支持。需要把最新的标准语法转换为低版本语法,把非标准语法转换为标准语法才能让浏览器识别解析,而babel就是来做这件事的,这里只讲配置,更详细的可以看Babel 那些事儿。

安装依赖

npm i babel-loader @babel/core @babel/preset-env core-js -D 

• babel-loader: 使用 babel 加载最新js代码并将其转换为 ES5（上面已经安装过）
• @babel/corer: babel 编译的核心包
• @babel/preset-env: babel 编译的预设,可以转换目前最新的js标准语法
• core-js: 使用低版本js语法模拟高版本的库,也就是垫片

修改webpack.base.js

// webpack.base.js
module.exports = {// ...module: {rules: [{test: /.(ts|tsx)$/,use: {loader: 'babel-loader',options: {// 执行顺序由右往左,所以先处理ts,再处理jsx,最后再试一下babel转换为低版本语法presets: [["@babel/preset-env",{// 设置兼容目标浏览器版本,这里可以不写,babel-loader会自动寻找上面配置好的文件.browserslistrc// "targets": {//"chrome": 35,//"ie": 9// }, "useBuiltIns": "usage", // 根据配置的浏览器兼容,以及代码中使用到的api进行引入polyfill按需添加 "corejs": 3, // 配置使用core-js低版本}],'@babel/preset-react','@babel/preset-typescript']}}}]}
} 

此时再打包就会把语法转换为对应浏览器兼容的语法了。

为了避免webpack配置文件过于庞大,可以把babel-loader的配置抽离出来, 新建babel.config.js文件,使用js作为配置文件,是因为可以访问到process.env.NODE_ENV环境变量来区分是开发还是打包模式。

// babel.config.js
module.exports = {// 执行顺序由右往左,所以先处理ts,再处理jsx,最后再试一下babel转换为低版本语法"presets": [["@babel/preset-env",{// 设置兼容目标浏览器版本,这里可以不写,babel-loader会自动寻找上面配置好的文件.browserslistrc// "targets": {//"chrome": 35,//"ie": 9// },"useBuiltIns": "usage", // 根据配置的浏览器兼容,以及代码中使用到的api进行引入polyfill按需添加"corejs": 3 // 配置使用core-js使用的版本}],"@babel/preset-react","@babel/preset-typescript"]
} 

移除webpack.base.js中babel-loader的options配置

// webpack.base.js
module.exports = {// ...module: {rules: [{test: /.(ts|tsx)$/,use: 'babel-loader'},// 如果node_moduels中也有要处理的语法，可以把js|jsx文件配置加上// {//test: /.(js|jsx)$/,//use: 'babel-loader'// }// ...]}
} 

4.6 babel处理js非标准语法

现在react主流开发都是函数组件和react-hooks,但有时也会用类组件,可以用装饰器简化代码。

新增src/components/Class.tsx组件, 在App.tsx中引入该组件使用

import React, { PureComponent } from "react";

// 装饰器为,组件添加age属性
function addAge(Target: Function) {Target.prototype.age = 111
}
// 使用装饰圈
@addAge
class Class extends PureComponent {age?: numberrender() {return (
我是类组件---{this.age}
)}
}

export default Class 

需要开启一下ts装饰器支持,修改tsconfig.json文件

// tsconfig.json
{"compilerOptions": {// ...// 开启装饰器使用"experimentalDecorators": true}
} 

上面Class组件代码中使用了装饰器,目前js标准语法是不支持的,现在运行或者打包会报错,不识别装饰器语法,需要借助babel-loader插件,安装依赖

npm i @babel/plugin-proposal-decorators -D 

在babel.config.js中添加插件

module.exports = { // ..."plugins": [["@babel/plugin-proposal-decorators", { "legacy": true }]]
} 

现在项目就支持装饰器了。

4.7 复制public文件夹

一般public文件夹都会放一些静态资源,可以直接根据绝对路径引入,比如图片,css,js文件等,不需要webpack进行解析,只需要打包的时候把public下内容复制到构建出口文件夹中,可以借助copy-webpack-plugin插件,安装依赖

npm i copy-webpack-plugin -D 

开发环境已经在devServer中配置了static托管了public文件夹,在开发环境使用绝对路径可以访问到public下的文件,但打包构建时不做处理会访问不到,所以现在需要在打包配置文件webpack.prod.js中新增copy插件配置。

// webpack.prod.js
// ..
const path = require('path')
const CopyPlugin = require('copy-webpack-plugin');
module.exports = merge(baseConfig, {mode: 'production',plugins: [// 复制文件插件new CopyPlugin({patterns: [{from: path.resolve(__dirname, '../public'), // 复制public下文件to: path.resolve(__dirname, '../dist'), // 复制到dist目录中filter: source => {return !source.includes('index.html') // 忽略index.html}},],}),]
}) 

在上面的配置中,忽略了index.html,因为html-webpack-plugin会以public下的index.html为模板生成一个index.html到dist文件下,所以不需要再复制该文件了。

测试一下,在public中新增一个favicon.ico图标文件,在index.html中引入

<