1. DevServer（开发服务）

webpack-dev-server 能够用于快速开发应用程序。

此页面描述影响 webpack-dev-server(简写为：dev-server) 行为的选项。

[info] 注：

与webpack-dev-middleware兼容的选项旁边有 🔑

module.exports = {
    devServer: {
        after: '',

    }
}

1.1. devServer

类型：object

通过来自webpack-dev-server的这些选项，能够用多种方式改变其行为。这里有一个简单的例子，所有来自dist/目录的文件都做 gzip 压缩，并提供为服务：

devServer: {
  contentBase: path.join(__dirname, "dist"),
  compress: true,
  port: 9000
}

当服务器启动时，在解析模块列表之前会有一条消息：

http://localhost:9000/
webpack output is served from /build/
Content not from webpack is served from /path/to/dist/

这将给出一些关于服务器的位置，以及服务本身的背景信息。

如果你通过 Node.js API 来使用 dev-server，devServer中的选项将被忽略。将选项作为第二个参数传入：new WebpackDevServer(compiler, {...})。关于如何通过 Node.js API 使用 webpack-dev-server 的示例，请查看此处。

[warning] 注：

在导出多个配置时，只考虑第一个配置的devServer选项，并将其用于数组中的所有配置。-

-

[info] 注：

如果您遇到麻烦，导航到/webpack-dev-server路由将显示被服务的文件的位置。例如,http://localhost:9000/webpack-dev-server

1.1.1. devServer.after

类型：function

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

after(app){
  // 执行一些操作
}

1.1.2. devServer.allowedHosts

类型：数组

这个选项允许你指定一个白名单，这个白名单记录了被允许访问的开发服务器。

allowedHosts: [
  'host.com',
  'subdomain.host.com',
  'subdomain2.host.com',
  'host2.com'
]

模仿django的ALLOWED_HOSTS，这是一个以.开始的值，可以用作子域名通配符。.host.com将匹配host.com、www.host.com和host.com的任何其他子域名。

// 这与第一个例子的效果相同
// 无需更新配置就可以获得额外的好处
// 如果新子域需要访问开发服务器
allowedHosts: [
    '.host.com',
    'host2.com'
]

使用命令行接口CLI时，通过--allowed-hosts选择一个用逗号分隔的字符串。

webpack-dev-server --entry /entry/file --output-path /output/path --allowed-hosts .host.com,host2.com

1.1.3. devServer.before

类型：function

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

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

1.1.4. devServer.bonjour

这个选项配置在启动时通过ZeroConf网络广播服务器

bonjour: true

通过CLI使用：

webpack-dev-server --bonjour

1.1.5. devServer.clientLogLevel

类型：string

当使用内联模式(inline mode)时，在开发工具(DevTools)的控制台(console)将显示消息，如：在重新加载之前，在一个错误之前，或者模块热替换(Hot Module Replacement)启用时。这可能显得很繁琐。

你可以阻止所有这些消息显示，使用这个选项：

clientLogLevel: "none"

通过CLI使用：

webpack-dev-server --client-log-level none

可能的值有none,error,warning或者info（默认值）。

1.1.6. devServer.color

通过CLI设置。

类型：boolean

在控制台显示/禁用颜色。

webpack-dev-server --color

1.1.7. devServer.compress

类型：boolean

一切服务都启用gzip 压缩：

compress: true

通过CLI使用：

webpack-dev-server --compress

1.1.8. devServer.contentBase

类型：boolean | string | array

告诉服务器从哪里提供内容。只有在你想要提供静态文件时才需要。devServer.publicPath将用于确定应该从哪里提供 bundle，并且此选项优先。

默认情况下，将使用当前工作目录作为提供内容的目录，但是你可以修改为其他目录：

contentBase: path.join(__dirname, "public")

[info] 注：

推荐使用绝对路径。

但是也可以从多个目录提供内容：

contentBase: [path.join(__dirname, "public"), path.join(__dirname, "assets")]

禁用contentBase：

contentBase: false

通过CLI使用：

webpack-dev-server --content-base /path/to/content/dir

1.1.9. devServer.disableHostCheck

类型：boolean

当该选项设置为true时，将绕过主机检查。这是不推荐的，因为不检查主机的应用程序很容易受到DNS重新绑定攻击。

disableHostCheck: true

通过CLI使用：

webpack-dev-server --disable-host-check

1.1.10. devServer.filename 🔑

类型：string

在惰性模式中，此选项可减少编译。 默认在惰性模式，每个请求结果都会产生全新的编译。使用filename，可以只在某个文件被请求时编译。

如果output.filename设置为bundle.js，filename使用如下：

lazy: true,
filename: "bundle.js"

现在只有在请求/bundle.js时候，才会编译 bundle。

[info] 注：

filename在不使用懒加载时没有效果

1.1.11. devServer.headers 🔑

类型：object

在所有响应中添加首部内容：

headers: {
  "X-Custom-Foo": "bar"
}

1.1.12. devServer.historyApiFallback

类型：boolean | object

当使用HTML5 History API时，任意的404响应都可能需要被替代为index.html。通过传入以下启用：

historyApiFallback: true

通过传入一个对象，比如使用rewrites这个选项，此行为可进一步地控制：

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

当路径中使用点(dot)（常见于 Angular），你可能需要使用disableDotRule：

historyApiFallback: {
  disableDotRule: true
}

通过CLI使用

webpack-dev-server --history-api-fallback

1.1.13. devServer.host

类型：string

指定使用一个 host。默认是localhost。如果你希望服务器外部可访问，指定如下：

host: "0.0.0.0"

通过CLI使用：

webpack-dev-server --host 0.0.0.0

1.1.14. devServer.hot

类型：boolean

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

hot: true

[info] 注：

webpack.HotModuleReplacementPlugin对于完全启用HMR是必须的。如果webpack或webpack-devserver是用--hot选项启动的，这个插件将会自动添加，因此您可能不需要将它添加到您的webpack.config.js中。请参阅HMR概念页面获得更多信息。

1.1.15. devServer.hotOnly

类型：boolean

启用热模块替换(见devServer.hot)，而不需要页面刷新，以防出现构建失败。

hotOnly: true

通过CLI使用

webpack-dev-server --hot-only

1.1.16. devServer.https

类型：boolean | object

默认情况下，dev-server 通过 HTTP 提供服务。也可以选择带有 HTTPS 的 HTTP/2 提供服务：

https: true

使用以下设置自签名证书，但是你可以提供自己的：

https: {
  key: fs.readFileSync("/path/to/server.key"),
  cert: fs.readFileSync("/path/to/server.crt"),
  ca: fs.readFileSync("/path/to/ca.pem"),
}

此对象直接传递到 Node.js HTTPS 模块，所以更多信息请查看HTTPS 文档。

通过CLI使用：

webpack-dev-server --https

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

webpack-dev-server --https --key /path/to/server.key --cert /path/to/server.crt --cacert /path/to/ca.pem

1.1.17. devServer.index

类型：string

被认为是索引文件的文件名。

index: 'index.htm'

1.1.18. devServer.info

只能通过CLI配置

类型：boolean

输出CLI信息，默认是启用的。

webpack-dev-server --info=false

1.1.19. devServer.inline

类型：boolean

在 dev-server 的两种不同模式之间切换。默认情况下，应用程序启用内联模式(inline mode)。这意味着一段处理实时重载的脚本被插入到你的包(bundle)中，并且构建消息将会出现在浏览器控制台。

也可以使用iframe 模式，它在通知栏下面使用<iframe>标签，包含了关于构建的消息。切换到iframe 模式：

inline: false

通过命令行使用：

webpack-dev-server --inline=false

[info] 注：

推荐使用模块热替换的内联模式，因为它包含来自 websocket 的 HMR 触发器。轮询模式可以作为替代方案，但需要一个额外的入口点：'webpack/hot/poll?1000'。

1.1.20. devServer.lazy 🔑

类型：boolean

当启用lazy时，dev-server 只有在请求时才编译包(bundle)。这意味着 webpack 不会监视任何文件改动。我们称之为“惰性模式”。

lazy: true

通过命令行使用：

webpack-dev-server --lazy

[info] 注：

watchOptions在使用惰性模式时无效。

-

[info] 注：

如果使用命令行工具(CLI)，请确保内联模式(inline mode)被禁用。

1.1.21. devServer.noInfo 🔑

类型：boolean

启用noInfo后，诸如「启动时和每次保存之后，那些显示的 webpack 包(bundle)信息」的消息将被隐藏。错误和警告仍然会显示。

noInfo: true

1.1.22. devServer.open

类型：boolean

当open被启用，dev server将打开浏览器

open: true

通过CLI使用:

webpack-dev-server --open

1.1.23. devServer.openPage

类型：string

指定在打开浏览器时导航到的页面。

openPage: '/different/page'

1.1.24. devServer.overlay

类型：boolean | object

当出现编译错误或警告时，在浏览器中显示一个全屏覆盖。默认情况下禁用。如果您只想显示编译器错误:

overlay: true

如果您想要显示警告和错误:

overlay: {
  warnings: true,
  errors: true
}

1.1.25. devServer.pfx

类型：string

当通过CLI使用时，是一条到SSL.pfx文件的路径。如果在选项中使用，它应该是.pfx文件的字节流

pfx: '/path/to/file.pfx'

通过CLI使用：

webpack-dev-server --pfx /path/to/file.pfx

1.1.26. devServer.pfxPassphrase

类型：string

The passphrase to a SSL PFX file.

pfxPassphrase: 'passphrase'

通过CLI使用：

webpack-dev-server --pfx-passphrase passphrase

1.1.27. devServer.port

类型：number

port: 8080

通过CLI使用：

webpack-dev-server --port 8080

1.1.28. devServer.proxy

类型：object

如果你有单独的后端开发服务器 API，并且希望在同域名下发送 API 请求 ，那么代理某些 URL 会很有用。

dev-server 使用了非常强大的http-proxy-middleware包。更多高级用法，请查阅其文档。

在localhost:3000上有后端服务的话，你可以这样启用代理：

proxy: {
  "/api": "http://localhost:3000"
}

请求到/api/users现在会被代理到请求http://localhost:3000/api/users。

如果你不想始终传递/api，则需要重写路径：

proxy: {
  "/api": {
    target: "http://localhost:3000",
    pathRewrite: {"^/api" : ""}
  }
}

默认情况下，不接受运行在 HTTPS 上，且使用了无效证书的后端服务器。如果你想要接受，修改配置如下：

proxy: {
  "/api": {
    target: "https://other-server.example.com",
    secure: false
  }
}

有时你不想代理所有的请求。可以基于一个函数的返回值绕过代理。

在函数中你可以访问请求体、响应体和代理选项。必须返回false或路径，来跳过代理请求。

例如：对于浏览器请求，你想要提供一个 HTML 页面，但是对于 API 请求则保持代理。你可以这样做：

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";
      }
    }
  }
}

如果您想要代理多个特定路径到同一个目标，您可以使用一个或多个具有上下文属性的对象的数组:

proxy: [{
  context: ["/auth", "/api"],
  target: "http://localhost:3000",
}]

1.1.29. devServer.progress

只能使用CLI配置

类型：boolean

将运行进度输出到控制台。

webpack-dev-server --progress

1.1.30. devServer.public

类型：string

当使用内联模式(inline mode)并代理 dev-server 时，内联的客户端脚本并不总是知道要连接到什么地方。它会尝试根据window.location来猜测服务器的 URL，但是如果失败，你需要这样。

例如，dev-server 被代理到 nginx，并且在myapp.test上可用：

public: "myapp.test:80"

通过CLI使用：

webpack-dev-server --public myapp.test:80

1.1.31. devServer.publicPath 🔑

类型：string

此路径下的打包文件可在浏览器中访问。

假设服务器运行在http://localhost:8080并且output.filename被设置为bundle.js。默认publicPath是"/"，所以你的包(bundle)可以通过http://localhost:8080/bundle.js访问。

可以修改publicPath，将 bundle 放在一个目录：

publicPath: "/assets/"

你的包现在可以通过http://localhost:8080/assets/bundle.js访问。

[info] 注：

确保publicPath总是以斜杠(/)开头和结尾。

也可以使用一个完整的 URL。这是模块热替换所必需的。

publicPath: "http://localhost:8080/assets/"

bundle 可以通过http://localhost:8080/assets/bundle.js访问。

[info] 注：

推荐使用devServer.publicPath和output.publicPath

1.1.32. devServer.quiet 🔑

类型：boolean

启用quiet后，除了初始启动信息之外的任何内容都不会被打印到控制台。这也意味着来自 webpack 的错误或警告在控制台不可见。

quiet: true

通过CLI使用

webpack-dev-server --quiet

1.1.33. devServer.socket

类型：string

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

socket:'socket'

通过 CLI使用：

webpack-dev-server --socket socket

1.1.34. devServer.staticOptions

可以配置来自contentBase的提供静态文件的高级选项。关于可能的选项，请参阅Express 文档。一个例子:

staticOptions: {
  redirect: false
}

[info] 注：

仅当使用contentBase作为一个string有效。

1.1.35. devServer.stats 🔑

类型：string | object

这个选项允许您精确控制哪些bundle信息被显示。如果你想要一些bundle信息，但不是全部，这可能是一个很好的中间地带。

这样只会显示包中的错误:

stats: "errors-only"

想要获取更多信息, 查看 stats 文档.

[info] 注：

此选项在使用quiet或noInfo时无效

1.1.36. devServer.stdin

只能通过CLI设置

类型：boolean

当 stdin 结束时，该选项关闭服务器。

webpack-dev-server --stdin

1.1.37. devServer.useLocalIp

类型：boolean

该选项让浏览器使用你的本地IP打开。

useLocalIp: true

通过CLI使用：

webpack-dev-server --useLocalIp

1.1.38. devServer.watchContentBase

类型：boolean

告诉服务器观察被devServer.contentBase选项提供的文件。文件变化将触发全页面重载。

watchContentBase: true

默认是禁用的。

通过CLI使用：

webpack-dev-server --watch-content-base

1.1.39. devServer.watchOptions 🔑

类型：boolean

与监视文件相关的控制选项。

webpack 使用文件系统(file system)获取文件改动的通知。在某些情况下，不会正常工作。例如，当使用网络文件系统 Network File System (NFS) 时。Vagrant也有很多问题。在这些情况下，请使用轮询：

watchOptions: {
  poll: true
}

如果这对文件系统来说太重了的话，你可以修改间隔时间（以毫秒为单位），将其设置为一个整数。

查看 WatchOptions 更多选项。