用Webpack 基础配置快速搭建项目开发环境

Webpack 是一个现代 JavaScript 应用程序的静态模块打包工具，但是Webpack有大量的配置项，对新手不太友好，但是我们可以根据webpack-cli的init命令根据项目需求快速生成webpack的配置文件，本文将手把手教你如何用 Webpack 和 npm 快速搭建一个基础开发环境。

一、初始化项目

首先，新建项目文件夹并初始化：

mkdir webpack_test
cd webpack_test
npm init -y

二、使用 webpack-cli 初始化配置

Webpack 提供了快速初始化配置的能力：

npx webpack init

报错后提示我们安装webpack-cli，输入yes

CLI for webpack must be installed.
  webpack-cli (https://github.com/webpack/webpack-cli)

We will use "npm" to install the CLI via "npm install -D webpack-cli".
Do you want to install 'webpack-cli' (yes/no):

提示我们init命令无法识别

[webpack-cli] Unknown command or entry 'init'
[webpack-cli] Did you mean 'info' (alias 'i')?
[webpack-cli] Run 'webpack --help' to see available commands and options

我们安装先安装webpack-cli

npm i -D @webpack-cli

再安装@webpack-cli/init，错误提示webpack-cli版本太高了，package.json中也可以看到webpack-cli的版本是6.0.1

E:\Code\Node-Code\webpack_test>npm i -D @webpack-cli/init
npm error code ERESOLVE
npm error ERESOLVE unable to resolve dependency tree
npm error
npm error While resolving: webpack_test@1.0.0
npm error Found: webpack-cli@6.0.1
npm error node_modules/webpack-cli
npm error   dev webpack-cli@"^6.0.1" from the root project
npm error
npm error Could not resolve dependency:
npm error peer webpack-cli@"4.x.x" from @webpack-cli/init@1.1.3
npm error node_modules/@webpack-cli/init
npm error   dev @webpack-cli/init@"*" from the root project
npm error
npm error Fix the upstream dependency conflict, or retry
npm error this command with --force or --legacy-peer-deps
npm error to accept an incorrect (and potentially broken) dependency resolution.
npm error
npm error
npm error For a full report see:
npm error E:\Environment\Node.js\node_cache\_logs\2025-04-14T09_08_54_013Z-eresolve-report.txt
npm error A complete log of this run can be found in: E:\Environment\Node.js\node_cache\_logs\2025-04-14T09_08_54_013Z-debug-0.log

{
  "name": "webpack_test",
  "version": "1.0.0",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "description": "",
  "devDependencies": {
    "webpack-cli": "^6.0.1"
  }
}

先将它降低到v4版本

npm i -D webpack-cli@4

降低到v4后，再运行npx webpack init，提示我们安装@webpack-cli/generators，我们选择yes

E:\Code\Node-Code\webpack_test>npx webpack init
[webpack-cli] Would you like to install '@webpack-cli/generators' package? (That will run 'npm install -D @webpack-cli/generators') (Y/n) y

安装好后就到配置询问环节了，示例如下：

? Which of the following JS solutions do you want to use? (Use arrow keys)
> none
  ES6
  Typescript

我选的配置如下：

# 选择ES6，还是TypeScript
? Which of the following JS solutions do you want to use? ES6

# 是否选择开发服务器，我们选择是
? Do you want to use webpack-dev-server? Yes

# 是否将打包的js文件自动给我们注入HTML文件，我们选择是
? Do you want to simplify the creation of HTML files for your bundle? Yes

# PWA（Progressive Web App）是可安装、支持离线访问的网页应用形式，我们选择否
? Do you want to add PWA support? No

# 我使用的CSS方案是SASS方案，选择CSS only也可以
? Which of the following CSS solutions do you want to use? SASS

# PostCSS方便后续对CSS进行扩展，我们选择是
? Will you be using PostCSS in your project? Yes

# 是否将CSS抽离为单个文件，我们选择仅在生成模式下，这样便于缓存
? Do you want to extract CSS for every file? Only for Production

# Prettier 是一个流行的代码格式化工具，选择是否都可以
? Do you like to install prettier to format generated configuration? Yes

# 我们选择npm进行包管理，当然pnpm和yarn也可以
? Pick a package manager: pnpm

# 选择重写 overwrite ，重写package.json文件
? Overwrite package.json? (ynarxdeiH)

回答完毕后，会自动安装相关依赖包，包括：

@babel/core, @babel/preset-env, babel-loader,
css-loader, style-loader, postcss, postcss-loader,
autoprefixer, mini-css-extract-plugin,
html-webpack-plugin, webpack-dev-server, prettier 等

三、配置文件说明

生成的 webpack.config.js 示例代码如下：

// Generated using webpack-cli https://github.com/webpack/webpack-cli
const path = require('path');
const HtmlWebpackPlugin = require('html-webpack-plugin');
const MiniCssExtractPlugin = require('mini-css-extract-plugin');
const isProduction = process.env.NODE_ENV == 'production';
const stylesHandler = isProduction ? MiniCssExtractPlugin.loader : 'style-loader';

const config = {
    // 入口文件
    entry: './src/index.js',
    // 出口文件夹
    output: {
        path: path.resolve(__dirname, 'dist'),
    },
    // 开发服务器
    devServer: {
        open: true,
        host: 'localhost',
    },
    // webpack插件
    plugins: [
        new HtmlWebpackPlugin({
            template: 'index.html',
        }),
        // Add your plugins here
        // Learn more about plugins from https://webpack.js.org/configuration/plugins/
    ],
    // webpack解析器
    module: {
        rules: [
            {
                test: /\.(js|jsx)$/i,
                loader: 'babel-loader',
            },
            {
                test: /\.s[ac]ss$/i,
                use: [stylesHandler, 'css-loader', 'postcss-loader', 'sass-loader'],
            },
            {
                test: /\.css$/i,
                use: [stylesHandler, 'css-loader', 'postcss-loader'],
            },
            {
                test: /\.(eot|svg|ttf|woff|woff2|png|jpg|gif)$/i,
                type: 'asset',
            },
            // Add your rules for custom modules here
            // Learn more about loaders from https://webpack.js.org/loaders/
        ],
    },
};

module.exports = () => {
    if (isProduction) {
        config.mode = 'production';
        config.plugins.push(new MiniCssExtractPlugin());
    } else {
        config.mode = 'development';
    }
    return config;
};

可以使用的命令在package.json中可以看到

  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "build": "webpack --mode=production --node-env=production",
    "build:dev": "webpack --mode=development",
    "build:prod": "webpack --mode=production --node-env=production",
    "watch": "webpack --watch",
    "serve": "webpack serve"
  },

四、项目启动开发服务器热模块替换

运行npm run serve命令

E:\Code\Node-Code\webpack_test>npm run serve
> webpack serve

[webpack-cli] Invalid options object. Dev Server has been initialized using an options object that does not match the API schema.
 - options has an unknown property '_assetEmittingPreviousFiles'. These properties are valid:
   object { allowedHosts?, bonjour?, client?, compress?, devMiddleware?, headers?, historyApiFallback?, host?, hot?, ipc?, liveReload?, onListening?, open?, port?, proxy?, server?, app?, setupExitSignals?, setupMiddlewares?, static?, watchFiles?, webSocketServer? }

用内置开发服务器启动项目报错，将webpack-cli版本变成v5版本

npm uninstall webpack-cli
npm i -D webpack-cli@5

重新启动项目，提示我们缺少@babel/plugin-syntax-dynamic-import依赖，关闭服务器，安装依赖

npm install -D @babel/plugin-syntax-dynamic-import

重新执行npm run serve即可在浏览器看到项目首页
因为没有开启HMR热模块替换，在编辑器中修改内容浏览器刷新才可以看到变换，我们在webpack.config.js修改开发服务器配置

devServer: {
        open: true, // 自动打开浏览器
        host: 'localhost', // 设置本机为主机地址
        port: 8080, // 添加端口设置
        hot: true,  // 开启热更新
        static: {
            directory: path.join(__dirname, 'dist'),  // 设置静态资源路径
        },
        historyApiFallback: true,  // 支持 HTML5 History API
    },

目录结构即内容如下：

index.html

<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8" />
        <title>Webpack</title>
    </head>
    <body>
        <div id="app"></div>
         <!-- Webpack 会自动注入打包后的脚本 -->
    </body>
    
</html>

index.js

const app = document.getElementById('app');
app.innerHTML = '<h1>Hello, Webpack Hot Update!</h1>';

五、常用命令整理

启动开发服务

npm run serve

构建项目

npm run build

六、更多资源推荐

官方配置文档： 链接: webpack初始配置

之后，我们就可以根据项目需求在webpack.config.js配置Loader和Plugin来扩展webpack的功能