Webpack5 搭建 React 脚手架实战指南

项目初始化与基础结构

首先创建项目文件夹并初始化 package.json。

mkdir react-cli
cd react-cli
npm init -y

接着安装 Webpack 核心包及相关辅助插件：webpack 和 webpack-cli 用于命令行操作，webpack-dev-server 提供开发服务器，webpack-merge 用于合并配置文件。

npm install webpack webpack-cli webpack-dev-server webpack-merge -D

搭建脚手架目录结构

建立以下目录与文件，将开发配置、生产配置与公共配置分离：

react-cli
├── public/
│   └── index.html       # 静态入口 HTML
├── src/
│   ├── App.js           # 主组件
│   ├── index.css        # 全局样式
│   ├── App.scss         # 测试 Sass 预编译
│   └── index.js         # JS 入口文件
├── webpack.common.js    # 公共配置
├── webpack.dev.js       # 开发环境配置
└── webpack.prod.js      # 生产环境配置

第1步：准备入口文件

在 public/index.html 中创建根节点：

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>react-cli</title>
</head>
<body>
  <div id="root"></div>
</body>
</html>

第2步：初步写入 JS 代码

在 src/index.js 中进行初始渲染：

const root = document.getElementById("root");
root.innerHTML = "cks";

开启本地服务与基本配置

安装 html-webpack-plugin 以自动生成引入 JS 文件的 HTML。

npm i html-webpack-plugin -D

第3步：编写公共配置 (webpack.common.js)

定义入口、输出路径及插件：

const path = require('path');
const HtmlWebpackPlugin = require('html-webpack-plugin');
module.exports = {
  entry: { index: './src/index.js' },
  plugins: [
    new HtmlWebpackPlugin({ template: './public/index.html' })
  ],
  output: {
    filename: '[name].bundle.js',
    path: path.resolve(__dirname, 'dist'),
  }
};

第4步：配置开发环境 (webpack.dev.js)

利用 webpack-merge 合并公共配置并设置调试模式：

const { merge } = require('webpack-merge');
const baseConfig = require('./webpack.common.js');
module.exports = merge(baseConfig, {
  mode: 'development',
  devtool: 'inline-source-map'
});

第5步：添加运行脚本并验证

在 package.json 中添加启动命令：

{
  "scripts": {
    "dev": "webpack-dev-server --config webpack.dev.js"
  }
}

运行 npm run dev 并在浏览器访问 http://localhost:8080，看到文字显示即成功。

配置 CSS 与 Sass 样式

Webpack 5 已内置 Asset Modules，无需额外处理图片，仅需安装样式相关的 Loader。

npm install --save-dev style-loader css-loader sass sass-loader

第6步：修改公共配置以支持样式

在 webpack.common.js 的 module.rules 中添加规则：

module.exports = { // ...其他配置省略...
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: ['style-loader', 'css-loader', 'sass-loader']
      },
      {
        test: /\.(png|jpg|jpeg|svg|gif)$/i,
        type: 'asset/resource'
      },
      {
        test: /\.(woff|woff2|eot|ttf|otf)$/i,
        type: 'asset/resource'
      }
    ]
  }
};

安装并配置 React 相关依赖

安装 React 核心库及 Babel 转译工具链。

npm install --save react react-dom
npm install babel-loader @babel/core @babel/preset-env @babel/preset-react -D

第7步：配置 Babel 转译 JSX

修改 webpack.common.js，增加解析扩展名、排除 node_modules 并启用 Babel：

module.exports = { // ...省略其他配置...
  resolve: { extensions: ['.js', '.json', '.jsx'] },
  module: {
    rules: [
      // ...css 等规则省略...
      {
        test: /\.js|jsx$/, 
        exclude: /node_modules/,
        use: {
          loader: 'babel-loader',
          options: { presets: ['@babel/preset-env', '@babel/preset-react'] }
        }
      }
    ]
  }
};

第8步：切换至 React 18 API

React 18 推荐使用 createRoot。修改 src/index.js：

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

const container = document.getElementById('root');
const root = createRoot(container);
root.render(<App />);

此时页面正常渲染 React 应用。

项目添加热更新 (HMR)

虽然默认开启了 HMR，但仅针对样式有效。需手动监听组件变化以触发局部重新挂载。

第9步：添加 HMR 监听逻辑

在 src/index.js 末尾追加：

// ...上述代码...
if (module.hot) {
  module.hot.accept('./App.js', () => {
    const NextApp = require('./App.js').default;
    root.render(<NextApp />)
  })
}

修改 App.js 后保存，浏览器页面内容会即时更新而不会刷新整页。

生产环境打包

第10步：配置生产构建文件 (webpack.prod.js)

const { merge } = require('webpack-merge');
const baseConfig = require('./webpack.common.js');
module.exports = merge(baseConfig, {
  mode: 'production', // 修正为 production 模式
  output: {
    clean: true // Webpack 5 新特性：每次生成前清空 dist 目录
  }
});

第11步：添加打包脚本

更新 package.json：

"scripts": {
  "build": "webpack --config webpack.prod.js"
}

执行 npm run build，即可在 dist 目录下获得优化后的静态资源。

总结

以上就是搭建 Webpack5 + React 基础脚手架的详细流程。该方案实现了环境与配置的隔离，集成了 Babel 编译及模块热更新机制，为后续深入进行性能优化奠定了坚实基础。更多关于前端工程化实践的资料请关注本站其它相关文章！