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 modee模式下默認會在每次請求時，
進行一次便宜。使用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有一些可用的預設值

示例:只顯示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