Webpack DevServer

webpack-dev-server 可用于快速开发应用程序。请查阅 开发指南 开始使用。

当前页面记录了影响 webpack-dev-server (简写: dev-server) version >= 4.0.0 配置的选项。可以在 这里 找到 v3 到 v4 的迁移指南

devServer

​object​

通过 webpack-dev-server 的这些配置，能够以多种方式改变其行为。这是一个基本的示例，利用 gzips 压缩 public/ 目录当中的所有内容并提供一个本地服务(serve)：

webpack.config.js

const path = require('path');

module.exports = {
  //...
  devServer: {
    static: {
      directory: path.join(__dirname, 'public'),
    },
    compress: true,
    port: 9000,
  },
};

当服务(server)启动后，在解析模块列表之前输出一条消息：

<i> [webpack-dev-server] Project is running at:
<i> [webpack-dev-server] Loopback: http://localhost:9000/
<i> [webpack-dev-server] On Your Network (IPv4): http://197.158.164.104:9000/
<i> [webpack-dev-server] On Your Network (IPv6): http://[fe80::1]:9000/
<i> [webpack-dev-server] Content not from webpack is served from '/path/to/public' directory

这里将会给出服务启动位置以及内容的一些基本信息。

如果你通过 Node.js API 使用 dev-server，则 devServer 中的配置选项将被忽略。但可以将配置选项作为第一个参数传入：new WebpackDevServer({...}, compiler)。此示例展示了如何通过 Node.js API 使用 webpack-dev-server。

Usage via CLI

你可以通过 CLI 调用 webpack-dev-server，方式是：

npx webpack serve

CLI 配置项列表可以在 这里 查询。

Usage via API

虽然推荐通过 CLI 运行 webpack-dev-server，但是你也可以通过 API 来启用服务器。

查看相关的 webpack-dev-server API 文档。

devServer.allowedHosts

​'auto' | 'all' [string]​

该选项允许将允许访问开发服务器的服务列入白名单。

webpack.config.js

module.exports = {
  //...
  devServer: {
    allowedHosts: [
      'host.com',
      'subdomain.host.com',
      'subdomain2.host.com',
      'host2.com',
    ],
  },
};

模仿 django 的ALLOWED_HOSTS，用 . 作为子域通配符。.host.com 会与 host.com，www.host.com 以及 host.com 等其他任何其他子域匹配。

webpack.config.js

module.exports = {
  //...
  devServer: {
    // this achieves the same effect as the first example
    // with the bonus of not having to update your config
    // if new subdomains need to access the dev server
    allowedHosts: ['.host.com', 'host2.com'],
  },
};

通过 CLI 使用：

npx webpack serve --allowed-hosts .host.com --allowed-hosts host2.com

当设置为 'all' 时会跳过 host 检查。并不推荐这样做，因为不检查 host 的应用程序容易受到 DNS 重绑定攻击。

webpack.config.js

module.exports = {
  //...
  devServer: {
    allowedHosts: 'all',
  },
};

通过 CLI 使用：

npx webpack serve --allowed-hosts all

当设置为 'auto' 时，此配置项总是允许 localhost、 host 和 client.webSocketURL.hostname：

webpack.config.js

module.exports = {
  //...
  devServer: {
    allowedHosts: 'auto',
  },
};

通过 CLI 使用：

npx webpack serve --allowed-hosts auto

devServer.bonjour

​boolean = false object​

这个配置用于在启动时通过 ZeroConf 网络广播你的开发服务器。

webpack.config.js

module.exports = {
  //...
  devServer: {
    bonjour: true,
  },
};

通过命令行使用：

npx webpack serve --bonjour

如需禁用：

npx webpack serve --no-bonjour

你也可以为 bonjour 设置 自定义配置项，例如：

webpack.config.js

module.exports = {
  //...
  devServer: {
    bonjour: {
      type: 'http',
      protocol: 'udp',
    },
  },
};

devServer.client

logging

​'log' | 'info' | 'warn' | 'error' | 'none' | 'verbose'​

允许在浏览器中设置日志级别，例如在重载之前，在一个错误之前或者 热模块替换 启用时。

webpack.config.js

module.exports = {
  //...
  devServer: {
    client: {
      logging: 'info',
    },
  },
};

通过命令行使用：

npx webpack serve --client-logging info

overlay

​boolean = true object: { errors boolean = true, warnings boolean = true }​

当出现编译错误或警告时，在浏览器中显示全屏覆盖。

webpack.config.js

module.exports = {
  //...
  devServer: {
    client: {
      overlay: true,
    },
  },
};

通过命令行使用：

npx webpack serve --client-overlay

如需禁用：

npx webpack serve --no-client-overlay

如果你只想显示错误信息：

webpack.config.js

module.exports = {
  //...
  devServer: {
    client: {
      overlay: {
        errors: true,
        warnings: false,
      },
    },
  },
};

通过命令行使用：

npx webpack serve --client-overlay-errors --no-client-overlay-warnings

progress

​boolean​

在浏览器中以百分比显示编译进度。

webpack.config.js

module.exports = {
  //...
  devServer: {
    client: {
      progress: true,
    },
  },
};

通过命令行使用：

npx webpack serve --client-progress

如需禁用：

npx webpack serve --no-client-progress

reconnect

​boolean = true number​

v4.4.0+

告诉 dev-server 它应该尝试重新连接客户端的次数。当为 true 时，它将无限次尝试重新连接。

webpack.config.js

module.exports = {
  //...
  devServer: {
    client: {
      reconnect: true,
    },
  },
};

通过 CLI 使用：

npx webpack serve --client-reconnect

当设置为 ​false​ 时，它将不会尝试连接。

module.exports = {
  //...
  devServer: {
    client: {
      reconnect: false,
    },
  },
};

通过 CLI 使用：

npx webpack serve --no-client-reconnect

您还可以指定客户端应该尝试重新连接的确切次数。

module.exports = {
  //...
  devServer: {
    client: {
      reconnect: 5,
    },
  },
};

通过 CLI 使用：

npx webpack serve --client-reconnect 5

webSocketTransport

​'ws' | 'sockjs' string​

该配置项允许我们为客户端单独选择当前的 devServer 传输模式，或者提供自定义的客户端实现。这允许指定浏览器或其他客户端与 devServer 的通信方式。

webpack.config.js

module.exports = {
  //...
  devServer: {
    client: {
      webSocketTransport: 'ws',
    },
    webSocketServer: 'ws',
  },
};

通过命令行使用：

npx webpack serve --client-web-socket-transport ws --web-socket-server ws

创建一个自定义客户端实现，创建一个类拓展 BaseClient。

使用 CustomClient.js 的路径，一个自定义 WebSocket 客户端实现，连同兼容的 'ws' 服务器：

webpack.config.js

module.exports = {
  //...
  devServer: {
    client: {
      webSocketTransport: require.resolve('./CustomClient'),
    },
    webSocketServer: 'ws',
  },
};

使用自定义且兼容的 WebSocket 客户端和服务端实现：

webpack.config.js

module.exports = {
  //...
  devServer: {
    client: {
      webSocketTransport: require.resolve('./CustomClient'),
    },
    webSocketServer: require.resolve('./CustomServer'),
  },
};

webSocketURL

​string object​

这个选项允许指定 URL 到 web socket 服务器（当你代理开发服务器和客户端脚本不总是知道连接到哪里时很有用）。

webpack.config.js

module.exports = {
  //...
  devServer: {
    client: {
      webSocketURL: 'ws://0.0.0.0:8080/ws',
    },
  },
};

通过命令行使用：

npx webpack serve --client-web-socket-url ws://0.0.0.0:8080/ws

您还可以指定具有以下属性的对象：

• hostname: 告诉连接到 devServer 的客户端使用提供的 hostname 进行连接。
• pathname: 告诉连接到 devServer 的客户端使用提供的路径进行连接。
• password: 告诉连接到 devServer 的客户端使用提供的密码进行认证。
• port: 告诉连接到 devServer 的客户端使用提供的端口进行连接。
• protocol: 告诉连接到 devServer 的客户端使用提供的协议进行连接。
• username: 告诉连接到 devServer 的客户端使用提供的用户名进行认证。

webpack.config.js

module.exports = {
  //...
  devServer: {
    client: {
      webSocketURL: {
        hostname: '0.0.0.0',
        pathname: '/ws',
        password: 'dev-server',
        port: 8080,
        protocol: 'ws',
        username: 'webpack',
      },
    },
  },
};

devServer.compress

​boolean = true​

启用 gzip compression：

webpack.config.js

module.exports = {
  //...
  devServer: {
    compress: true,
  },
};

通过命令行使用：

npx webpack serve --compress

如需禁用

npx webpack serve --no-compress

devServer.devMiddleware

​object​

为 webpack-dev-middleware 提供处理 webpack 资源的配置项。

webpack.config.js

module.exports = {
  devServer: {
    devMiddleware: {
      index: true,
      mimeTypes: { phtml: 'text/html' },
      publicPath: '/publicPathForDevServe',
      serverSideRender: true,
      writeToDisk: true,
    },
  },
};

devServer.http2

​boolean​

使用 spdy 提供 HTTP/2 服务。对于 Node 15.0.0 及更高版本，此选项将被忽略，因为 spdy 在这些版本中已被破坏。一旦 Express 支持，开发服务器将迁移到 Node 内置的 HTTP/2。

HTTP/2 带有自签名证书：

webpack.config.js

module.exports = {
  //...
  devServer: {
    http2: true,
  },
};

通过 CLI 使用：

npx webpack serve --http2

禁用：

npx webpack serve --no-http2

通过 https 配置你自己的证书文件：

webpack.config.js

const fs = require('fs');

module.exports = {
  //...
  devServer: {
    http2: true,
    https: {
      key: fs.readFileSync('/path/to/server.key'),
      cert: fs.readFileSync('/path/to/server.crt'),
      ca: fs.readFileSync('/path/to/ca.pem'),
    },
  },
};

要通过 CLI 使用你的证书，请使用以下配置项：

npx webpack serve --http2 --https-key ./path/to/server.key --https-cert ./path/to/server.crt --https-ca ./path/to/ca.pem

devServer.https

​boolean object​

默认情况下，开发服务器将通过 HTTP 提供服务。可以选择使用 HTTPS 提供服务：

webpack.config.js

module.exports = {
  //...
  devServer: {
    https: true,
  },
};

通过 CLI 使用：

npx webpack serve --https

禁用：

npx webpack serve --no-https

根据上述配置，将使用自签名证书，但是你也可以提供自己的证书：

webpack.config.js

module.exports = {
  devServer: {
    https: {
      ca: './path/to/server.pem',
      pfx: './path/to/server.pfx',
      key: './path/to/server.key',
      cert: './path/to/server.crt',
      passphrase: 'webpack-dev-server',
      requestCert: true,
    },
  },
};

该对象直接传递到 Node.js HTTPS 模块，因此请参阅 HTTPS documentation 以获取更多信息。

要通过 CLI 使用自己的证书，请使用以下选项：

npx webpack serve --https-request-cert --https-key ./path/to/server.key --https-cert ./path/to/server.crt --https-ca ./path/to/ca.pem --https-pfx ./path/to/server.pfx --https-passphrase webpack-dev-server

webpack-dev-server >= v4.2.0 允许你设置额外的 TLS 配置项，比如 minVersion。同样你可以直接传递各自文件的内容：

webpack.config.js

const fs = require('fs');
const path = require('path');

module.exports = {
  devServer: {
    https: {
      minVersion: 'TLSv1.1',
      key: fs.readFileSync(path.join(__dirname, './server.key')),
      pfx: fs.readFileSync(path.join(__dirname, './server.pfx')),
      cert: fs.readFileSync(path.join(__dirname, './server.crt')),
      ca: fs.readFileSync(path.join(__dirname, './ca.pem')),
      passphrase: 'webpack-dev-server',
      requestCert: true,
    },
  },
};

devServer.headers

​array function object​

为所有响应添加 headers：

webpack.config.js

module.exports = {
  //...
  devServer: {
    headers: {
      'X-Custom-Foo': 'bar',
    },
  },
};

你也可以传递一个数组：

webpack.config.js

module.exports = {
  //...
  devServer: {
    headers: [
      {
        key: 'X-Custom',
        value: 'foo',
      },
      {
        key: 'Y-Custom',
        value: 'bar',
      },
    ],
  },
};

你也可以传递一个函数：

module.exports = {
  //...
  devServer: {
    headers: () => {
      return { 'X-Bar': ['key1=value1', 'key2=value2'] };
    },
  },
};

devServer.historyApiFallback

​boolean = false object​

当使用HTML5 History API时，通常需要在任何404响应的情况下提供index.html页面。通过将devServer.historyApiFallback设置为true来启用该功能。

webpack.config.js

module.exports = {
  //...
  devServer: {
    historyApiFallback: true,
  },
};

通过 CLI 使用：

npx webpack serve --history-api-fallback

禁用：

npx webpack serve --no-history-api-fallback

通过提供一个对象，这种行为可以通过像 rewrites 这样的配置项进一步控制：

webpack.config.js

module.exports = {
  //...
  devServer: {
    historyApiFallback: {
      rewrites: [
        { from: /^\/$/, to: '/views/landing.html' },
        { from: /^\/subpage/, to: '/views/subpage.html' },
        { from: /./, to: '/views/404.html' },
      ],
    },
  },
};

在你的路径中使用点（与 Angular 相同），你可能需要使用 disableDotRule：

webpack.config.js

module.exports = {
  //...
  devServer: {
    historyApiFallback: {
      disableDotRule: true,
    },
  },
};

有关更多选项和信息，请参阅connect-history-api-fallback文档。

devServer.host

​'local-ip' | 'local-ipv4' | 'local-ipv6' string​

指定要使用的 host。如果你想让你的服务器可以被外部访问，像这样指定：

webpack.config.js

module.exports = {
  //...
  devServer: {
    host: '0.0.0.0',
  },
};

通过命令行使用：

npx webpack serve --host 0.0.0.0

这也适用于 IPv6：

npx webpack serve --host ::

local-ip

如果将host选项指定为local-ip，它将尝试将host解析为本地IPv4地址（如果可用），如果IPv4不可用，则尝试解析本地IPv6地址。

npx webpack serve --host local-ip

local-ipv4

如果将host选项指定为local-ipv4，它将尝试将host解析为本地IPv4地址。

npx webpack serve --host local-ipv4

local-ipv6

指定 local-ipv6 作为主机将尝试将主机选项解析为您的本地 IPv6 地址。

npx webpack serve --host local-ipv6

devServer.hot

​'only' boolean = true​

启用 webpack 的 热模块替换 特性：

webpack.config.js

module.exports = {
  //...
  devServer: {
    hot: true,
  },
};

通过命令行使用：

npx webpack serve --hot

如需禁用：

npx webpack serve --no-hot

启用热模块替换功能，在构建失败时不刷新页面作为回退，使用 hot: 'only'：

webpack.config.js

module.exports = {
  //...
  devServer: {
    hot: 'only',
  },
};

通过命令行使用：

npx webpack serve --hot only

devServer.ipc

​true string​

The Unix socket to listen to (instead of a host).

将其设置为 true 将会监听 /your-os-temp-dir/webpack-dev-server.sock 的 socket：

webpack.config.js

module.exports = {
  //...
  devServer: {
    ipc: true,
  },
};

通过命令行使用：

npx webpack serve --ipc

你也可以这样监听一个不同的 socket：

webpack.config.js

const path = require('path');

module.exports = {
  //...
  devServer: {
    ipc: path.join(__dirname, 'my-socket.sock'),
  },
};

devServer.liveReload

​boolean = true​

默认情况下，当监听到文件变化时 dev-server 将会重新加载或刷新页面。为了 liveReload 能够生效，devServer.hot 配置项必须禁用或者 devServer.watchFiles 配置项必须启用。将其设置为 false 以禁用 devServer.liveReload：

webpack.config.js

module.exports = {
  //...
  devServer: {
    liveReload: false,
  },
};

通过命令行使用：

npx webpack serve --live-reload

禁用该功能：

npx webpack serve --no-live-reload

devServer.magicHtml

​boolean = true​

v4.1.0+

告诉dev-server启用/禁用魔术HTML路由（与webpack输出相对应的路由，例如/main对应main.js）。

webpack.config.js

module.exports = {
  //...
  devServer: {
    magicHtml: true,
  },
};

通过 CLI 使用：

npx webpack serve --magic-html

禁用：

npx webpack serve --no-magic-html

devServer.onAfterSetupMiddleware

​function (devServer)​

提供服务器内部在所有其他中间件之后执行 自定义中间件的能力

webpack.config.js

module.exports = {
  //...
  devServer: {
    onAfterSetupMiddleware: function (devServer) {
      if (!devServer) {
        throw new Error('webpack-dev-server is not defined');
      }

      devServer.app.get('/some/path', function (req, res) {
        res.json({ custom: 'response' });
      });
    },
  },
};

devServer.onBeforeSetupMiddleware

​function (devServer)​

提供在服务器内部执行所有其他中间件之前执行自定义中间件的能力。 这可以用来定义自定义处理程序， 例如:

webpack.config.js

module.exports = {
  //...
  devServer: {
    onBeforeSetupMiddleware: function (devServer) {
      if (!devServer) {
        throw new Error('webpack-dev-server is not defined');
      }

      devServer.app.get('/some/path', function (req, res) {
        res.json({ custom: 'response' });
      });
    },
  },
};

devserver.onListening

​function (devServer)​

提供在 webpack-dev-server 开始监听端口连接时执行自定义函数的能力。

webpack.config.js

module.exports = {
  //...
  devServer: {
    onListening: function (devServer) {
      if (!devServer) {
        throw new Error('webpack-dev-server is not defined');
      }

      const port = devServer.server.address().port;
      console.log('Listening on port:', port);
    },
  },
};

devServer.open

​boolean string object [string, object]​

告诉 dev-server 在服务器已经启动后打开浏览器。设置其为 true 以打开你的默认浏览器。

webpack.config.js

module.exports = {
  //...
  devServer: {
    open: true,
  },
};

通过命令行使用：

npx webpack serve --open

如需禁用：

npx webpack serve --no-open

在浏览器中打开指定页面：

webpack.config.js

module.exports = {
  //...
  devServer: {
    open: ['/my-page'],
  },
};

通过命令行使用：

npx webpack serve --open /my-page

在浏览器中打开多个指定页面：

webpack.config.js

module.exports = {
  //...
  devServer: {
    open: ['/my-page', '/another-page'],
  },
};

通过命令行使用：

npx webpack serve --open /my-page --open /another-page

提供要使用的浏览器名称，而不是默认名称：

webpack.config.js

module.exports = {
  //...
  devServer: {
    open: {
      app: {
        name: 'google-chrome',
      },
    },
  },
};

通过命令行使用：

npx webpack serve --open-app-name 'google-chrome'

该对象接收所有 open 配置项：

webpack.config.js

module.exports = {
  //...
  devServer: {
    open: {
      target: ['first.html', 'http://localhost:8080/second.html'],
      app: {
        name: 'google-chrome',
        arguments: ['--incognito', '--new-window'],
      },
    },
  },
};

devServer.port

​'auto' string number​

指定监听请求的端口号：

webpack.config.js

module.exports = {
  //...
  devServer: {
    port: 8080,
  },
};

通过命令行使用：

npx webpack serve --port 8080

port 配置项不能设置为 null 或者空字符串，要想自动使用一个可用端口请使用 port: 'auto'：

webpack.config.js

module.exports = {
  //...
  devServer: {
    port: 'auto',
  },
};

通过 CLI 使用：

npx webpack serve --port auto

devServer.proxy

​object [object, function]​

当拥有单独的 API 后端开发服务器并且希望在同一域上发送 API 请求时，代理某些 URL 可能会很有用。

开发服务器使用功能强大的 http-proxy-middleware 软件包。 查看其 documentation 了解更多高级用法。 请注意，http-proxy-middleware 的某些功能不需要target键，例如 它的 router 功能，但是仍然需要在此处的配置中包含target，否则webpack-dev-server 不会将其传递给 http-proxy-middleware。

使用后端在 localhost:3000 上，可以使用它来启用代理：

webpack.config.js

module.exports = {
  //...
  devServer: {
    proxy: {
      '/api': 'http://localhost:3000',
    },
  },
};

现在，对 /api/users 的请求会将请求代理到 http://localhost:3000/api/users。

如果不希望传递/api，则需要重写路径：

webpack.config.js

module.exports = {
  //...
  devServer: {
    proxy: {
      '/api': {
        target: 'http://localhost:3000',
        pathRewrite: { '^/api': '' },
      },
    },
  },
};

默认情况下，将不接受在 HTTPS 上运行且证书无效的后端服务器。 如果需要，可以这样修改配置：

webpack.config.js

module.exports = {
  //...
  devServer: {
    proxy: {
      '/api': {
        target: 'https://other-server.example.com',
        secure: false,
      },
    },
  },
};

有时不想代理所有内容。 可以基于函数的返回值绕过代理。

在该功能中，可以访问请求，响应和代理选项。

• 返回 null 或 undefined 以继续使用代理处理请求。
• 返回 false 会为请求产生 404 错误。
• 返回提供服务的路径，而不是继续代理请求。

例如。 对于浏览器请求，想要提供 HTML 页面，但是对于 API 请求，想要代理它。 可以执行以下操作：

webpack.config.js

module.exports = {
  //...
  devServer: {
    proxy: {
      '/api': {
        target: 'http://localhost:3000',
        bypass: function (req, res, proxyOptions) {
          if (req.headers.accept.indexOf('html') !== -1) {
            console.log('Skipping proxy for browser request.');
            return '/index.html';
          }
        },
      },
    },
  },
};

如果想将多个特定路径代理到同一目标，则可以使用一个或多个带有 context 属性的对象的数组：

webpack.config.js

module.exports = {
  //...
  devServer: {
    proxy: [
      {
        context: ['/auth', '/api'],
        target: 'http://localhost:3000',
      },
    ],
  },
};

请注意，默认情况下不会代理对 root 的请求。 要启用根代理，应将 devMiddleware.index 选项指定为虚假值：

webpack.config.js

module.exports = {
  //...
  devServer: {
    devMiddleware: {
      index: false, // specify to enable root proxying
    },
    proxy: {
      context: () => true,
      target: 'http://localhost:1234',
    },
  },
};

默认情况下，代理时会保留主机头的来源，可以将 changeOrigin 设置为 true 以覆盖此行为。 在某些情况下，例如使用 name-based virtual hosted sites，它很有用。

webpack.config.js

module.exports = {
  //...
  devServer: {
    proxy: {
      '/api': {
        target: 'http://localhost:3000',
        changeOrigin: true,
      },
    },
  },
};

devServer.server

​'http' | 'https' | 'spdy' string object​

v4.4.0+

允许设置服务器和配置项（默认为 'http'）。

webpack.config.js

module.exports = {
  //...
  devServer: {
    server: 'http',
  },
};

通过 CLI 使用：

npx webpack serve --server-type http

使用自签名证书通过 HTTPS 提供服务：

webpack.config.js

module.exports = {
  //...
  devServer: {
    server: 'https',
  },
};

通过 CLI 使用：

npx webpack serve --server-type https

使用 spdy 使用自签名证书通过 HTTP/2 提供服务：

webpack.config.js

module.exports = {
  //...
  devServer: {
    server: 'spdy',
  },
};

通过 CLI 使用：

npx webpack serve --server-type spdy

使用对象语法提供自己的证书：

webpack.config.js

module.exports = {
  //...
  devServer: {
    server: {
      type: 'https',
      options: {
        ca: './path/to/server.pem',
        pfx: './path/to/server.pfx',
        key: './path/to/server.key',
        cert: './path/to/server.crt',
        passphrase: 'webpack-dev-server',
        requestCert: true,
      },
    },
  },
};

通过 CLI 使用：

npx webpack serve --server-type https --server-options-key ./path/to/server.key --server-options-cert ./path/to/server.crt --server-options-ca ./path/to/ca.pem --server-options-passphrase webpack-dev-server

它还允许您设置其他TLS选项，如minVersion，并且您可以直接传递相应文件的内容：

webpack.config.js

const fs = require('fs');
const path = require('path');

module.exports = {
  //...
  devServer: {
    server: {
      type: 'https',
      options: {
        minVersion: 'TLSv1.1',
        key: fs.readFileSync(path.join(__dirname, './server.key')),
        pfx: fs.readFileSync(path.join(__dirname, './server.pfx')),
        cert: fs.readFileSync(path.join(__dirname, './server.crt')),
        ca: fs.readFileSync(path.join(__dirname, './ca.pem')),
        passphrase: 'webpack-dev-server',
        requestCert: true,
      },
    },
  },
};

devServer.setupExitSignals

​boolean = true​

允许在 SIGINT 和 SIGTERM 信号时关闭开发服务器和退出进程。

webpack.config.js

module.exports = {
  //...
  devServer: {
    setupExitSignals: true,
  },
};

devServer.setupMiddlewares

​function (middlewares, devServer)​

v4.7.0+

提供执行自定义函数和应用自定义中间件的能力。

webpack.config.js

module.exports = {
  // ...
  devServer: {
    setupMiddlewares: (middlewares, devServer) => {
      if (!devServer) {
        throw new Error('webpack-dev-server is not defined');
      }

      devServer.app.get('/setup-middleware/some/path', (_, response) => {
        response.send('setup-middlewares option GET');
      });

      // 如果你想在所有其他中间件之前运行一个中间件或者当你从 `onBeforeSetupMiddleware` 配置项迁移时，
      // 可以使用 `unshift` 方法
      middlewares.unshift({
        name: 'first-in-array',
        // `path` 是可选的
        path: '/foo/path',
        middleware: (req, res) => {
          res.send('Foo!');
        },
      });

      // 如果你想在所有其他中间件之后运行一个中间件或者当你从 `onAfterSetupMiddleware` 配置项迁移时，
      // 可以使用 `push` 方法
      middlewares.push({
        name: 'hello-world-test-one',
        // `path` 是可选的
        path: '/foo/bar',
        middleware: (req, res) => {
          res.send('Foo Bar!');
        },
      });

      middlewares.push((req, res) => {
        res.send('Hello World!');
      });

      return middlewares;
    },
  },
};

devServer.static

​boolean string object [string, object]​

该配置项允许配置从目录提供静态文件的选项（默认是 'public' 文件夹）。将其设置为 false 以禁用：

webpack.config.js

module.exports = {
  //...
  devServer: {
    static: false,
  },
};

通过 CLI 使用：

npx webpack serve --static

禁用该功能：

npx webpack serve --no-static

监听单个目录：

webpack.config.js

module.exports = {
  // ...
  devServer: {
    static: ['assets'],
  },
};

通过 CLI 使用：

npx webpack serve --static assets

监听多个静态资源目录：

webpack.config.js

module.exports = {
  // ...
  devServer: {
    static: ['assets', 'css'],
  },
};

通过 CLI 使用：

npx webpack serve --static assets --static css

directory

​string = path.join(process.cwd(), 'public')​

告诉服务器从哪里提供内容。只有在你希望提供静态文件时才需要这样做。static.publicPath 将会被用来决定应该从哪里提供 bundle，并具有优先级。

webpack.config.js

const path = require('path');

module.exports = {
  //...
  devServer: {
    static: {
      directory: path.join(__dirname, 'public'),
    },
  },
};

提供一个对象数组，以防你有多个静态资源文件夹：

webpack.config.js

const path = require('path');

module.exports = {
  //...
  devServer: {
    static: [
      {
        directory: path.join(__dirname, 'assets'),
      },
      {
        directory: path.join(__dirname, 'css'),
      },
    ],
  },
};

staticOptions

​object​

可以配置从 static.directory 提供静态文件的高级选项。关于可用配置项可以插件 Express 文档。

webpack.config.js

module.exports = {
  //...
  devServer: {
    static: {
      staticOptions: {
        redirect: true,
      },
    },
  },
};

publicPath

​string = '/' [string]​

告诉服务器在哪个 URL 上提供 static.directory 的内容。例如为在 /serve-public-path-url/manifest.json 中的 assets/manifest.json 提供服务，你的配置项应该像下面这样：

webpack.config.js

const path = require('path');

module.exports = {
  //...
  devServer: {
    static: {
      directory: path.join(__dirname, 'assets'),
      publicPath: '/serve-public-path-url',
    },
  },
};

提供一个对象数组，以防你有多个静态文件夹：

webpack.config.js

const path = require('path');

module.exports = {
  //...
  devServer: {
    static: [
      {
        directory: path.join(__dirname, 'assets'),
        publicPath: '/serve-public-path-url',
      },
      {
        directory: path.join(__dirname, 'css'),
        publicPath: '/other-serve-public-path-url',
      },
    ],
  },
};

serveIndex

​boolean object = { icons: true }​

告诉开发服务器启用后使用 serveIndex 中间件。

serveIndex 中间件会在查看没有 index.html 文件的目录时生成目录列表。

webpack.config.js

const path = require('path');

module.exports = {
  //...
  devServer: {
    static: {
      directory: path.join(__dirname, 'public'),
      serveIndex: true,
    },
  },
};

通过 CLI 使用：

npx webpack serve --static-serve-index

禁用该功能：

npx webpack serve --no-static-serve-index

watch

​boolean object​

通过 static.directory 配置项告诉 dev-server 监听文件。默认启用，文件更改将触发整个页面重新加载。可以通过将 watch 设置为 false 禁用。

webpack.config.js

const path = require('path');

module.exports = {
  //...
  devServer: {
    static: {
      directory: path.join(__dirname, 'public'),
      watch: false,
    },
  },
};

通过 CLI 使用：

npx webpack serve --static-watch

禁用该功能：

npx webpack serve --no-static-watch

可以配置高级选项以监听 static.directory 中的静态文件。关于可用选项可以查看 chokidar 文档。

webpack.config.js

const path = require('path');

module.exports = {
  //...
  devServer: {
    static: {
      directory: path.join(__dirname, 'public'),
      watch: {
        ignored: '*.txt',
        usePolling: false,
      },
    },
  },
};

devServer.watchFiles

​string object [string, object]​

该配置项允许你配置 globs/directories/files 来监听文件变化。例如：

webpack.config.js

module.exports = {
  //...
  devServer: {
    watchFiles: ['src/**/*.php', 'public/**/*'],
  },
};

可以配置高级选项来监听文件。关于可用选项可以查看 chokidar 文档。

webpack.config.js

module.exports = {
  //...
  devServer: {
    watchFiles: {
      paths: ['src/**/*.php', 'public/**/*'],
      options: {
        usePolling: false,
      },
    },
  },
};

devServer.webSocketServer

​false | 'sockjs' | 'ws' string function object​

该配置项允许我们选择当前的 web-socket 服务器或者提供自定义的 web-socket 服务器实现。

当前默认模式为 'ws'。该模式使用 ws 作为服务器，客户端中的 WebSockets。

webpack.config.js

module.exports = {
  //...
  devServer: {
    webSocketServer: 'ws',
  },
};

为了创建一个自定义服务端实现，可以创建一个拓展 BaseServer 的类。

使用 CustomServer.js 导出的类实现自定义 WebSocket 客户端并兼容ws服务端：

webpack.config.js

module.exports = {
  //...
  devServer: {
    client: {
      webSocketTransport: 'ws',
    },
    webSocketServer: require.resolve('./CustomServer'),
  },
};

使用自定义且兼容的 WebSocket 客户端以及服务端实现：

webpack.config.js

module.exports = {
  //...
  devServer: {
    client: {
      webSocketTransport: require.resolve('./CustomClient'),
    },
    webSocketServer: require.resolve('./CustomServer'),
  },
};