webpack devServer

邹野

2023-12-01

DevServer

该文档主要描述关于devserver的相关配置。(配置同webpack-dev-middleware兼容)

devServer(Object类型)

该配置会被webpack-dev-server使用，并从不同方面做定制。
下面是一个例子，使用gzips提供对dist/文件夹下内容的访问。

devServer: {
contentBase: path.join(__dirname, "dist"),//对外提供的访问内容的路径
compress: true,//是否启用gzip压缩
port: 9000//提供访问的端口
}

当server运行后，在请求时会打印如下内容

http://localhost:9000/
webpack result is served from /build/
content is served from dist/

打印出来的内容会显示，server在监听什么端口，提供的服务来来源于内容(如来源于dist文件夹)。
如果以Node.js API的方式使用dev-server，则devServer中的配置将会被忽略。
需要将设置的options作为第二个参数进行传递new WebpackDevServer(compiler,{...})通过Node.js API进行配置的内容参见此处

devServer.clientLogLevel(String 类型)

当使用inline mode，devTools的命令行中将会显示一些调试信息，
如：before loading，before an error 或 Hot Module Replacement 被启用。
这类调试信息，可能会让输出变得比较乱。
可以通过如下设置禁止显示上述的调试信息。

clientLogLevel: "none"

其中的值可以是none,error,warning或info。
如果不设置默认的log level为info。
注意console一致都会显示bundle error和warning。上面的配置只对log级别低的message有效。

devServer.compress(boolean 类型)

对所有请求启用gzip压缩

compress: true

devServer.contentBase(boolean string array类型)

设置server对外服务的内容来源，只有在提供静态文件访问的情况下才需要使用该配置。
devServer.publicPath会被用来设置提供bundles文件的位置，而且会优先考虑该配置的路径。
默认情况下会使用当前运行命令的文件夹作为内容源，可以使用如下配置对此进行更改。

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

注意：建议使用绝对路径，不要使用相对路径
可以定义多个文件夹提供数据源。

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

禁止使用contentBase可以做如下设置

contentBase: false

devServer.filename(String)

该配置可以配置成lazy mode来减少编译，lazy mode模式下默认会在每次请求时，
进行一次编译。使用filename,可以设置当请求某个指定的文件时，才执行编译。
如果output.filename被设置位bundle.js并且filename如下使用,
则仅仅会在请求bundle.js时，进行编译。

lazy: true,
filename:"bundle.js"

如果是设置filename而不设置lazy mode，则不会有任何效果。

devServer.headers(object)

像所有的请求添加headers

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

devServer.historyApiFallback(boolean object)

当使用html5 history api,将会在响应404时返回index.html。想要开启该功能进行如下设置。

historyApiFallback: true

通过传递一个 object 来对该共呢个做更多的定制。

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

当在路径中使用.符号，需要使用 disableDotRule 配置。

historyApiFallback: {
  disableDotRule: true
}

关于此处更多的信息，参考 connect-history-api-fallback 文档.

devServer.host(string 该配置只能用于CLI)

指定使用的host。默认情况下是localhost.
如果希望server被外部访问，需要向下面来制定。

host: "0.0.0.0"

devServer.hot(boolean)

启用webpack的Hot Module Replacement特性。

hot: true

devServer.hotOnly(boolean 只适用于CLI)

启用Hot Module Replacement，当编译失败时，不刷新页面。

hotOnly:true

devServer.https(boolean object)

默认情况下dev-server使用http协议，通过配置可以支持https

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 documentation

devServer.inline(boolean 只适用于CLI)

切换dev-server的两种模式，默认情况server使用inline mode。
这种情况下，live reload及构建信息的相关代码会被插入到bundle中。
另外一种模式位iframe mode.使用iframe mode会在通知栏下方
显示构建信息，切换到iframe mode可以使用下方配置。

inline: false

使用Hot Module Replacement时，建议使用inline mode。

devServer.lazy(boolean)

当启用lazy.dev-server会仅在请求时进行编译。
这意味着webpack不会监控文件改变，所以称该模式为lazy mode.
开启lazy模式如下。

lazy: true

当在lazy模式下，watchOptions将不会被启用
如果在CLI下使用，需要确保inline mode被禁用

devServer.noInfo(boolean)

启用noInfo，类似webpack bundle启动或保存的信息将会被隐藏，Errors和warnings仍会被显示。

noInfo: true

devServer.overlay(boolean object)

在浏览器上全屏显示编译的errors或warnings。
默认是关闭的。如果只想显示编译错误。则如下配置

overlay: true

如果既想显示erros也想显示warnings，则如下配置

overlay: {
    warnings: true,
    errors:true
}

devServer.port(number 只适用于CLI)

指定服务监听的端口

port: 8080

devServer.proxy(object)

未来保证在同一域名下，请求一些在其他域名下的api接口时会用到该配置。
dev-server使用http-proxy-middleware包。
当服务运行于localhost:3000时，可以使用如下配置启用代理。

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

对/api/users的请求将会通过代理请求到http://localhost:3000/api/users
如果不想将/api传递过去，需要重写path:

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

默认情况下如果请求的服务是https的，并且证书是未认证的的，则该错未认证证书默认是无法使用的。如果想要使用该证书。则需要进行如下配置，关闭安全检测。

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

有时，不希望代理所有请求，可以像bypass属性传递一个function来实现该需求。
在function中，可以获取到request，response以及proxy options。
该function必须返回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";
      }
    }
  }
}

devServer.public(string CLI only)

当使用inline mode并代理到dev-server。内链的客户端代码不知道应该访问哪个域名。
他将会基于window.location来链接服务器，但是如果这样做有问题，
则需要使用public配置。
例子：dev-server被代理到nginx中配置的myapp.test

public: "myapp.test:80"

devServer.publicPath(string)

打包的文件将被部署到该配置对应的path。
假设server运行在http://localhost:8080而output.filename设置位bundle.js
默认情况下publicPath为/,所以最终生成的bundle文件可以通过如下路径访问。
http://localhost:8080/bundle.js
publicPath 更改为一个文件夹

publicPath: "/assets/"

最终的生成文件的访问路径为 http://localhost:8080/assets/bundle.js

publicPath的值，前后必须包含斜杠

也可以使用完整的url进行制定，如果使用HMR则必须使用该种写法。

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

最终的生成文件仍然通过 http://localhost:8080/assets/bundle.js 进行访问。

建议将devServer.publicPath同output.publicPath配置成相同值

devServer.quiet(boolean)

当启用该配置，除了初始化信息会被写到console中，其他任何信息都不会被写进去。
errors和warnings也不会被写到console中。

quiet: true

devServer.setup(function)

通过该function可以访问Express app对象，添加自定义的middleware。
举例，为某个路径添加自定义处理

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

devServer.staticOptions

能够对通过 contentBase 配置部署的静态文件进行高级配置。
具体配置查看Express文档

staticOptions: {
  redirect: false
}

注意，该配置仅当 contentBase 配置为 string 时起作用

devServer.stats(string object)

针对bundle打印的信息进行精确控制。
使用场景为，当只想看一些想看到的信息，而不想看到所有的打印信息，
这种情况下，使用 quiet 或 noInfo 是不合适的，因为还希望关注一部分信息。
此种场景下就需要使用stats来控制日志内容的输出。

stats有一些可用的预设值

Preset	Alternative	Description
errors-only	none	只在产生error时打印日志
minimal	none	只打印errors或文件第一次被编译时
none	false	禁止打印日志
normal	true	标准打印日志
verbose	none	打印所有日志

示例:只显示bundle中的errors

stats: "errors-only"

stats提供了很多细力度的对日志信息的控制。可以详细指定希望打印的信息。

stats: {
  // Add asset Information
  assets: true,
  // Sort assets by a field
  assetsSort: "field",
  // Add information about cached (not built) modules
  cached: true,
  // Add children information
  children: true,
  // Add chunk information (setting this to `false` allows for a less verbose output)
  chunks: true,
  // Add built modules information to chunk information
  chunkModules: true,
  // Add the origins of chunks and chunk merging info
  chunkOrigins: true,
  // Sort the chunks by a field
  chunksSort: "field",
  // Context directory for request shortening
  context: "../src/",
  // `webpack --colors` equivalent
  colors: true,
  // Add errors
  errors: true,
  // Add details to errors (like resolving log)
  errorDetails: true,
  // Add the hash of the compilation
  hash: true,
  // Add built modules information
  modules: true,
  // Sort the modules by a field
  modulesSort: "field",
  // Add public path information
  publicPath: true,
  // Add information about the reasons why modules are included
  reasons: true,
  // Add the source code of modules
  source: true,
  // Add timing information
  timings: true,
  // Add webpack version information
  version: true,
  // Add warnings
  warnings: true
};

当配置了 quiet 或 noInfo 时，该配置不起作用

devServer.watchContentBase(boolean)

设置server监控通过devServer.contentBase设置的文件。
在文件改变时会进行页面刷新，默认情况下该配置是禁止的。

watchContentBase: true

devServer.watchOptions(object)

对文件更改的监控配置。
webpack基于文件系统来获取文件的改变。在某些场景下，是不起作用的。
比如，当使用NFS或Vagrant。针对这种情况使用polling进行监控。

watchOptions: {
  poll: true
}

如果该操作对于文件系统来说消耗比较大，可以设置在一定的间隔时间内出发一次。
更多的配置参见 WatchOptions