webpack-dev-server使用

这些 API 主要分为两大类：1. 通过 webpack.config.js 配置文件 和 2. 通过 Node.js API 以编程方式使用。

---

一、核心配置选项 (在 webpack.config.js 中使用)

这是最常见的使用方式。你在 webpack.config.js 的 devServer 对象中配置各种选项。

// webpack.config.js
module.exports = {
  // ... 其他 webpack 配置 (entry, output, module, etc.)
  devServer: {
    // webpack-dev-server 的配置项都放在这里
    port: 8080,
    hot: true,
    open: true,
    // ... 其他配置
  },
};

以下是一些最重要和最常用的配置项：

1. 服务器连接配置 (Host & Port)

• port : number | 'auto'
  • 指定要使用的端口号。默认是 8080。设置为 'auto' 会寻找可用的端口。
• host : string
  • 指定要使用的主机。如果你希望服务器可以被外部访问（例如同一局域网内的手机访问），设置为 '0.0.0.0'。默认通常是 'localhost'。
• allowedHosts : array
  • 允许访问开发服务器的白名单。当设置为 'auto' 时，会允许 host、localhost 和 client.webSocketURL.hostname。
  • allowedHosts: ['host.com', 'subdomain.host.com'] // 允许特定域名
  • allowedHosts: ['.host.com'] // 允许 host.com 及其所有子域名
• bonjour : boolean | object
  • 设置为 true 时，启动后会在网络广播 ZeroConf 服务，方便局域网内设备发现。

2. 静态文件服务 (Static Files)

• static : boolean | string | object | array
  • 替代了旧版的 contentBase。用于配置从哪里提供静态文件（如图片、字体等，不需要 webpack 处理的文件）。
  • static: false：禁用静态文件服务。
  • static: './public'：提供一个目录的字符串路径。
  • static: { directory: path.join(__dirname, 'public'), watch: true }：对象形式，更详细的控制。
    • directory: 静态文件目录路径。
    • watch: 是否监听静态文件的变化并刷新浏览器。
    • publicPath: 指定在浏览器中访问这个静态资源的公开路径，默认为 /。

3. 热模块替换 (Hot Module Replacement - HMR)

• hot : boolean | 'only'
  • 启用/禁用 HMR。设置为 true 时，如果 HMR 失败，会回退到完全刷新页面。设置为 'only' 时，不会回退，失败就失败。
• liveReload : boolean
  • 默认 true。当文件改变时，自动刷新整个页面。通常与 hot: true 配合使用，代码变化时用 HMR，静态文件变化时刷新页面。

4. 代理 (Proxy) - 解决跨域神器

• proxy : object

  • 配置代理规则，将特定 API 请求代理到后端服务器，解决开发时的跨域问题。

  devServer: {
    proxy: {
      // 当你请求 '/api' 路径时，会被代理到 http://localhost:3000
      '/api': {
        target: 'http://localhost:3000',
        changeOrigin: true, // 虚拟托管站点需要，改变 Origin 头为目标 URL 的 origin
        pathRewrite: {
          '^/api': '' // 重写路径，去掉 /api 前缀
        }
      }
    }
  }

5. 压缩与头部 (Compression & Headers)

• compress : boolean

  • 启用 gzip 压缩，默认 true，可以显著减少资源传输体积。

• headers : object

  • 为所有响应添加自定义 HTTP 头。

  headers: {
    'X-Custom-Header': 'custom-value',
    'Access-Control-Allow-Origin': '*'
  }

6. 打开浏览器与进度条

• open : boolean | string | object
  • 服务器启动后自动在浏览器中打开页面。可以指定浏览器名称或参数：open: { app: { name: 'google-chrome' } }。
• client : object
  • 配置客户端（浏览器中运行的脚本）的行为。
  • client: { overlay: true }：在浏览器中显示编译错误或警告的全屏遮罩层。
  • client: { progress: true }：在浏览器中显示编译进度。

---

二、Node.js API (编程方式)

你可以通过 require('webpack-dev-server') 在 Node.js 脚本中以编程方式启动服务器，这提供了更大的灵活性。

const Webpack = require('webpack');
const WebpackDevServer = require('webpack-dev-server');
const webpackConfig = require('./webpack.config.js');

const compiler = Webpack(webpackConfig);
const devServerOptions = { ...webpackConfig.devServer, open: true };
const server = new WebpackDevServer(devServerOptions, compiler);

const runServer = async () => {
  console.log('Starting server...');
  await server.start();
};
runServer();

// 优雅关闭
// process.on('SIGINT', () => { server.stop(); });

核心 API 方法：

• new WebpackDevServer(options, compiler) : 构造函数。
  • options: 与配置文件中的 devServer 对象完全相同。
  • compiler: 由 webpack(config) 创建的 compiler 实例。
• start(): 启动服务器。返回一个 Promise。
• startCallback(callback): 启动服务器，使用回调函数。
• stop(): 停止服务器。返回一个 Promise。
• stopCallback(callback): 停止服务器，使用回调函数。

---

三、通过命令行 (CLI) 传递参数

你可以在 package.json 的脚本中通过 CLI 参数覆盖配置文件中的设置。

{
  "scripts": {
    "dev": "webpack serve --port 3000 --hot --open"
  }
}

常用 CLI 参数：--port, --host, --hot, --open, --static (替代了 --content-base)。

优先级：命令行参数 > 配置文件中的 devServer 选项 > 默认值。

总结

使用方式	描述	适用场景
配置文件 (devServer)	最常用，在 webpack.config.js 中声明式配置。	绝大多数项目，配置可版本化管理。
Node.js API	编程式创建和启动服务器，灵活性最高。	需要与其他 Node.js 服务集成或进行复杂逻辑控制时。
命令行 (CLI)	快速覆盖配置项，临时调整参数。	在 package.json 脚本中或临时手动执行时。

要获取最完整和最新的 API 列表，建议始终查阅 官方文档。