# webpack-howto

**Repository Path**: rhyanne/webpack-howto

## Basic Information

- **Project Name**: webpack-howto
- **Description**: 基于 Webpack 5 构建工具实战示例，探索 Webpack 的奥秘
- **Primary Language**: JavaScript
- **License**: MulanPSL-2.0
- **Default Branch**: webpack-howto-react
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2022-06-24
- **Last Updated**: 2022-07-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# webpack-howto

#### 介绍

基于 Webpack 5 构建工具实战示例，探索 Webpack 的奥秘


#### 主要目标

- 学些 Webpack5 的相关配置

- 基于 Webpack5 搭建 React 工程开发脚手架

- 基于 Webpack5 搭建 Vue3 工程开发脚手架


备注：每一个分支为独立的实战工程示例；


#### 执行命令

```shell
# 安装
pnpm install

# 开发环境
pnpm dev

# 生产构建
pnpm build

```

### 项目初始化

```shell
npm init -y
```

### 安装 webpack

```shell
# 当前版本 webpack@5.73.0  webpack-cli@4.10.0
pnpm add webpack webpack-cli -D

# webpack-merge 用于区分开发和生产环境配置
pnpm add webpack-merge -D
```

### 基础配置

新建 `config` 目录，用于存放配置文件：`paths.js`、`webpack.config.js`、`webpack.dev.js`、`webpack.prod.js`，分别为：路径变量定义、基础通用配置、开发环境配置、生产环境配置

```javascript
/// config/paths.js
const path = require('path')
const fs = require('fs')

// Make sure any symlinks in the project folder are resolved.
const appDirectory = fs.realpathSync(process.cwd())

// resolve path
const resolveApp = relativePath => path.resolve(appDirectory, relativePath)

module.exports = {
    appRoot: appDirectory,
    appSrc: resolveApp('src'),
    appBuild: resolveApp('build'),
    appPublic: resolveApp('public'),
    appIndexJs: resolveApp('src/main.js'),
    appHtml: resolveApp('public/index.html'),
    appDll: resolveApp('dll')
}
```

通用配置文件：

```javascript
/// config/webpack.config.js
const paths = require('./paths')
// 到处工程函数，用于生产通用配置
module.exports = function (webpackEnv) {
    const isEnvProd = webpackEnv === 'production'
    const isEnvDev = webpackEnv === 'development'
    return {
        entry: paths.appIndexJs,
        output: {
            path: paths.appBuild,
            filename: isEnvProd ? "js/[name].[contenthash:8].js" : isEnvDev && "js/[name].bundle.js"
        },
        // module: {},
        // plugins: [],
        // resolve: {}
    }
}
```

开发环境配置文件：

```javascript
/// config/webpack.dev.js
const { merge } = require('webpack-merge')
const configFactory = require('./webpack.config')
// 设置全局环境变量
process.env.NODE_ENV = "development"
// 通过工厂函数方法生成通用配置
const config = configFactory("development")
// 合并通用配置和开发环境相关配置
module.exports = merge(config, {
    mode: 'development',
})
```

生产环境配置文件：

```javascript
/// config/webpack.prod.js
const { merge } = require('webpack-merge')
const configFactory = require('./webpack.config')
// 设置全局环境变量
process.env.NODE_ENV = "production"
// 通过工厂函数方法生成通用配置
const config = configFactory("production")
// 合并通用配置和生产环境相关配置
module.exports = merge(config, {
    mode: 'production',
})
```

### `html-webpack-plugin` 生成 `index.html`

```shell
pnpm add html-webpack-plugin -D
```

### `clean-webpack-plugin` 移除或清除构建目录下的文件

```shell
pnpm add clean-webpack-plugin -D
```

### 集成 `ESLint` + `Prettier`

```shell
pnpm add eslint prettier @babel/core @babel/eslint-parser eslint-config-prettier eslint-plugin-prettier  -D

pnpm add eslint-plugin-import eslint-plugin-react -D
```

新建配置文件：

```shell
ni .eslintrc.js
ni .prettier.yaml
# 或者 ni .prettierrc
ni .prettierignore
ni .editorconfig
```


### 静态资源文件 —— `Asset Modules` 类型

静态资源主要包括：样式文件（CSS）、图片（Images）、字体（Fonts）、数据文件（Data）...

在 Webpack5 之前，比如 Webpack4 ，采用的是各种相关 `loaders` 来处理静态文件并打包的，比如：`css-loader`、`style-loader`、`url-loader`、`file-loader`、`raw-loader` 等；

Webpack5 简化了之前版本对于文件方面的配置，提供了 `Asset Modules` （静态资源模块），替代了相关 `loaders`，使得处理静态资源更加方便；

```javascript
// svg 转 data uri 编码算法插件
const svgToMiniDataURI = require("mini-svg-data-uri");

// module.rules
rules: [
  // 图片文件
  {
    test: /\.(jpe?g|png|gif|webp)$/i,
    type: "asset",
    generator: {
      // 独立设置文件打包后的路径及文件名
      filename: "images/[hash][ext][query]",
    },
    parser: {
      dataUrlCondition: {
        maxSize: 4 * 1024,
      },
    },
  },
  // SVG 文件
  // SVG 文件转换为 URI 编码后，与 base64 相比，体积会更小
  {
    test: /\.svg$/i,
    type: "asset",
    generator: {
      dataUrl: (content) => {
        content = content.toString();
        // 通过插件提供的编码算法处理文件
        return svgToMiniDataURI(content);
      },
      filename: "images/[hash][ext][query]"
    },
    parser: {
      dataUrlCondition: {
        // 2kb，低于 2kb 都会被压缩
        maxSize: 2 * 1024,
      },
    },
  },
  // 字体文件
  {
    test: /\.(otf|eof|woff2?|ttf)$/i,
    type: "asset/resource",
    generator: {
      filename: "iconfonts/[hash][ext][query]",
    },
  },
]

```

当 type 设置为 `asset` 是，webpack 会按照一下策略去打包文件：

- 如果一个模块大小超过 8kb (默认值)，使用 `asset/resource` ，被打包进输入文件夹中，类似 `file-loader`

- 否则，就是用 `asset/inline`，内联到打包文件中，类似 `url-loader`

> 区别：`asset/resource` 被单独放进输出文件中， `asset/inline` 被处理成 base64 编码字符串或者特定编码内联打包进输出的 JS 文件中


### 样式文件处理

- `style-loader`  将样式文件以 `<style>` 标签形式插入到 DOM 中

- `css-loader`  解析通过 `@import`、`url()`、`import / require()` 这些方式引入的样式文件

- `sass-loader`  加载 SASS/SCSS 文件，并编译成 CSS

- `less-loader`  加载 LESS 文件，并编译成 CSS

- `postcss-loader`  PostCSS 增强代码的可读性，`Autoprefixer` 插件自动添加浏览器前缀；未来 CSS 特性支持；避免 CSS 代码中的错误

```shell
# install style-loader css-loader
pnpm add style-loader css-loader -D

# install sass@1.53.0 sass-loader@13.0.1
pnpm add sass sass-loader -D

# install less@4.1.3 less-loader@11.0.0
pnpm add less less-loader -D

# install postcss postcss-loader postcss-preset-env
pnpm add postcss postcss-loader postcss-preset-env -D
```

```javascript
/// module.rules

rules: [
  // ...
  // 样式文件
  {
    test: /\.css$/,
    exclude: /node_modules/,
    // loader 执行顺序从右往左进行
    use: ["style-loader", "css-loader"],
  },
  {
    test: /\.s[ac]ss$/i,
    exclude: /node_modules/,
    use: ["style-loader", "css-loader", "sass-loader"],
  },
  {
    test: /\.less$/i,
    exclude: /node_modules/,
    use: ["style-laoder", "css-loader", "less-loader"],
  },
]
```

> css 样式被 `css-loader` 解析完成后， 然后通过 `style-loader` 以 `<style>` 标签形式插入到 DOM 中；


通常，`postcss-loader` 在 `css-loader` 之前执行，在 `less-loader`、`sass-loader` 执行完后执行；

```javascript
/// webpack.config.js

const postcssLoader = {
  loader: "postcss-loader",
  options: {
    postcssOptions: {
      plugins: [
        // 提高开发效率，只在生产构建时启用
        isEnvProd && [
          "postcss-preset-env",
          {
            // some options
          },
        ],
      ],
    },
  },
};

/// module.rules
rules: [

  // ...

  // 样式文件
  {
    test: /\.css$/,
    // loader 执行顺序从右往左进行
    use: ["style-loader", "css-loader", postcssLoader],
  },
  {
    test: /\.s[ac]ss$/i,
    use: ["style-loader", "css-loader", postcssLoader, "sass-loader"],
  },
  {
    test: /\.less$/i,
    use: ["style-laoder", "css-loader", postcssLoader, "less-loader"],
  },
]

```

补充：关于 `postcss`，除了如上所述配置方式外，也是支持独立的配置文件 `postcss.config.js` 来进行配置：

```javascript
/// 项目录根目录下 postcss.config.js

module.exports = {
  plugins: [require("postcss-preset-env")],
};

// 然后，在 webpack.config.js 的 rules 下，只需直接配置 postcss-loader 即可
```

`postcss-preset-env` 插件中已经包含了 `autoprefixer` 的特性，所以，一般只需要使用 `postcss-preset-env` 即可，无需添加 `autoprefixer`；


### 分离样式文件

生产构建时，通常是希望将 CSS 抽离出来成为独立的文件，并可以通过 CSS 文件的形式引入到页面

```shell
pnpm add mini-css-extract-plugin -D
```

```javascript
rules: [
  // ...
  // 样式文件
  {
    test: /\.css$/,
    // loader 执行顺序从右往左进行
    use: [
      isEnvDev ? MiniCssExtractPlugin.loader : "style-loader",
      "css-loader",
      postcssLoader,
    ],
  },
  {
    test: /\.s[ac]ss$/i,
    use: [
      isEnvDev ? MiniCssExtractPlugin.loader : "style-loader",
      "css-loader",
      postcssLoader,
      "sass-loader",
    ],
  },
  {
    test: /\.less$/i,
    use: [
      isEnvDev ? MiniCssExtractPlugin.loader : "style-laoder",
      "css-loader",
      postcssLoader,
      "less-loader",
    ],
  },
]


plugins: [
  new MiniCssExtractPlugin({
    filename: "[name].[hash:8].css",
  })
]
```


### 本地开发服务器 webpack-dev-server

```shell
pnpm add webpack-dev-server -D
```

主要配置如下：

```javascript
/// config/webpack.dev.js

const { merge } = require("webpack-merge");
const configFactory = require("./webpack.config");
const { resolveApp } = require("./paths");

process.env.NODE_ENV = "development";

const config = configFactory("development");

module.exports = merge(config, {
  mode: "development",
  devtool: "eval-cheap-module-source-map",
  devServer: {
    // webpack5 中已使用 static 替代了 contentBase
    static: {
      // 告诉服务器从哪里提供内容。只有在你希望提供静态文件时才需要这样做。
      directory: resolveApp("build"),
      // 服务器访问静态资源的默认路径，优先级高于 output.publicPath
      // 告诉服务器在哪个 URL 上提供 static.directory 的内容
      publicPath: "/",
    },
    open: true,
    compress: true,
    port: 9000,
  },
});
```

- 在开发环境中，`mode`、`devtool`、`devServer` 这三个配置很重要

- `webpack-dev-server` 在编译后不会在输出目录写入任何文件；**它会将打包的文件存在内存中**，就好像在服务器根路径上的真实文件一样

- 热模块替换是默认开启的，即：`hot: true`


### 开启 `React`、`ReactDOM`、`Babel`

```shell
# INSTALL REACT REACT-DOM
pnpm add react react-dom

# INSTALL BABEL BABEL-LOADER
pnpm add babel-loader @babel/core @babel/preset-react @babel/preset-env core-js -D

# INSTALL @babel/plugin-transform-react-jsx
# 配置如何编译 jsx ; @babel/preset-react 已经包含了这个插件
# 通常，我们只需要直接使用 @babel/preset-env 即可，不需要单独安装这个插件，这里只是为了了解这个插件
pnpm add @babel/plugin-transform-react-jsx -D
# 这两个插件可选安装，前者支持解析 jsx 语法，后者 转换 displayName
# 实际上 @babel/preset-env 中是包含了 @babel/plugin-transform-react-display-name 的
pnpm add @babel/plugin-syntax-jsx @babel/plugin-transform-react-display-name -D

# INSTALL @babel/plugin-transform-runtime  @babel/runtime
# 自动移除语法转换后内联的辅助函数（inline Babel helpers）,使用 @babel/runtime/helpers 里面的辅助函数来替代
# 当代码里使用了 corejs 的 API，自动引入 @babel/runtime-corejs3/core-js-stable/ ，来替代全局引入的 core-js/stable
# 当代码里使用了 Generator/async 函数，自动引入 @babel/runtime/regenerator，来替代全局引入的 regenerator-runtime/runtime
pnpm add @babel/plugin-transform-runtime -D
pnpm add @babel/runtime @babel/runtime-corejs3
```

基于 `@babel/plugin-transform-react-jsx` 插件的配置，启用新的 jsx 转换器支持：

```javascript
/// config/webpack.config.js

rules: [
  // js/jsx
  {
    test: /.jsx?$/,
    exclude: /node_modules/,
    use: {
      loader: "babel-loader",
      options: {
        presets: [
          [
            // 预设 polyfill
            "@babel/preset-env",
            {
              // polyfill 只加载使用的部分
              useBuiltIns: "usage",
              // 使用 corejs@3 解析，模块化
              corejs: "3",
            },
          ],
        ],
        plugins: [
          "@babel/plugin-syntax-jsx",
          "@babel/plugin-transform-react-display-name",
          [
            // 用于解析 react jsx 语法
            "@babel/plugin-transform-react-jsx",
            {
              // 旧的转换的默认选项为 {"runtime": "classic"}。
              // 如需启用新的转换，你可以使用 {"runtime": "automatic"} 作为 @babel/plugin-transform-react-jsx 或 @babel/preset-react 的选项
              runtime: "automatic",
            },
          ],
          [
            "@babel/plugin-transform-runtime",
            {
              // false - @babel/runtime
              // 2 - @babel/runtime-corejs2
              // 3 - @babel/runtime-corejs3
              corejs: 3, // @babel/runtime-corejs3 should be installed
            },
          ],
        ],
      },
    },
  },

  // ...
]
```

`useBuiltIns` —— 这个选项用来配置 `@babel/preset-env` 引入 polyfills 的处理方式（handle polyfills）

> 注意，`babel > 7.4.0` 之前，使用的是 `@babel/polyfill` 来处理，之后，需要使用 `core-js/stable` 和 `regenerator-runtime/runtime` 来替代

  - `false`   不引入 polyfill，只做了语法转换

  - `entry`  要求在打包入口文件顶部需要引入 `core-js/stable` 和 `regenerator-runtime/runtime`；引入所有的 es 扩展包，

```javascript
/// useBuiltIns: entry 时添加
import 'core-js/stable';
import 'regenerator-runtime/runtime';
```

  - `usage`  自动检测代码中用到的功能，自动引入模块（按需加载）

> babel默认不会检测第三方依赖包代码，所以使用 usage 时，可能会出现引入第三方的代码包未注入模块而引发bug

辅助插件 `@babel/plugin-transform-runtime` + `@babel/runtime` ， `@babel/runtime` 提供辅助函数，解决全局变量污染的问题，以及移除冗余的工具函数

实际上 `@babel/preset-react` 包含了下列插件

  - `@babel/helper-plugin-utils`,

  - `@babel/helper-validator-option`,

  - `@babel/plugin-transform-react-display-name`,

  - `@babel/plugin-transform-react-jsx`,

  - `@babel/plugin-transform-react-jsx-development`,

  - `@babel/plugin-transform-react-pure-annotations`



### `css-minimizer-webpack-plugin`

```shell
pnpm add -D css-minimizer-webpack-plugin
```


### `terser-webpack-plugin`

```shell
pnpm add -D terser-webpack-plugin
```

### 进度条美化 `progress-bar-webpack-plugin`

```shell
pnpm add -D progress-bar-webpack-plugin
```