Webpack Dev Server配置与使用

Webpack Dev Server 是一个基于 Express 的本地开发服务器，专为 Webpack 项目设计。它提供了热模块替换（HMR）、自动刷新、代理请求等功能，极大提升了开发效率。下面从配置到使用逐步展开说明。

安装 Webpack Dev Server

首先需要确保项目中已安装 webpack 和 webpack-cli。如果尚未安装，可以通过以下命令安装：

npm install webpack webpack-cli --save-dev

接着安装 webpack-dev-server：

npm install webpack-dev-server --save-dev

基本配置

在 webpack.config.js 中配置 devServer 对象。以下是一个基础配置示例：

const path = require('path');

module.exports = {
  // ...其他配置
  devServer: {
    static: {
      directory: path.join(__dirname, 'dist'), // 静态文件目录
    },
    compress: true, // 启用 gzip 压缩
    port: 8080, // 指定端口号
    open: true, // 自动打开浏览器
  },
};

热模块替换（HMR）

HMR 允许在不刷新整个页面的情况下更新模块。启用方式如下：

module.exports = {
  // ...其他配置
  devServer: {
    hot: true, // 启用 HMR
  },
};

同时需要在入口文件中添加 HMR 支持代码：

if (module.hot) {
  module.hot.accept('./app.js', () => {
    console.log('模块已热更新');
  });
}

代理配置

开发时可能需要将 API 请求代理到后端服务器。通过 proxy 配置实现：

module.exports = {
  devServer: {
    proxy: {
      '/api': {
        target: 'http://localhost:3000', // 后端地址
        pathRewrite: { '^/api': '' }, // 重写路径
        changeOrigin: true, // 修改请求头中的 host
      },
    },
  },
};

自定义中间件

可以通过 setupMiddlewares 添加自定义 Express 中间件：

module.exports = {
  devServer: {
    setupMiddlewares: (middlewares, devServer) => {
      if (!devServer) {
        throw new Error('webpack-dev-server 未定义');
      }
      // 添加自定义中间件
      middlewares.unshift({
        name: 'logger',
        path: '/log',
        middleware: (req, res) => {
          console.log('请求日志:', req.url);
          res.send('日志记录完成');
        },
      });
      return middlewares;
    },
  },
};

开发环境与生产环境区分

通常需要为开发环境单独配置 webpack.dev.js。示例：

const { merge } = require('webpack-merge');
const commonConfig = require('./webpack.common.js');

module.exports = merge(commonConfig, {
  mode: 'development',
  devtool: 'eval-source-map',
  devServer: {
    // 开发服务器配置
  },
});

高级配置示例

结合 historyApiFallback 和 publicPath 处理单页应用路由：

module.exports = {
  devServer: {
    historyApiFallback: {
      rewrites: [
        { from: /^\/admin/, to: '/admin.html' },
        { from: /./, to: '/index.html' },
      ],
    },
    static: {
      publicPath: '/assets/', // 静态资源公共路径
    },
  },
};

启动脚本配置

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

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

通过 npm run dev 即可启动开发服务器。

常见问题排查

1. 端口冲突：修改 port 或通过 --port 参数指定：

   webpack serve --port 9000
   

2. HMR 不生效：检查是否同时满足以下条件：

   • 配置中启用 hot: true
   • 入口文件添加 HMR 接受代码
   • 使用 webpack serve 而非 webpack-dev-server 命令

3. 代理无效：确保 target 地址可访问，并检查浏览器网络请求是否携带正确前缀。

性能优化建议

1. 启用懒编译提升启动速度：

   module.exports = {
     devServer: {
       lazy: true, // 仅当请求对应资源时才编译
     },
   };
   

2. 限制重新编译范围：

   module.exports = {
     watchOptions: {
       ignored: /node_modules/, // 忽略 node_modules 变化
     },
   };
   

3. 使用 inline 模式减少资源加载时间：

   module.exports = {
     devServer: {
       inline: true, // 将运行时逻辑内联到 bundle
     },
   };