CC 4.0 授權條款

本節內容衍生自以下連結的內容，並受 CC BY 4.0 授權條款約束。
https://webpack.dev.org.tw/configuration/dev-server/
如果沒有特別說明，以下內容可以假設是基於原始內容修改和刪除後的結果。

DevServer

此頁面說明了影響 @rspack/dev-server（簡稱：dev-server）行為的選項，該選項基於 webpack-dev-server@5，有助於快速應用程式開發。

類型： object

提示

如果目前的應用程式不依賴 @rspack/dev-server，則 devServer 設定將不會生效。

例如，Rspack CLI 預設依賴 @rspack/dev-server，因此 devServer 設定可用於 Rspack CLI 專案。 Rsbuild 實作了它自己的開發伺服器，並提供了單獨的「伺服器」設定，因此 devServer 設定無法在 Rsbuild 專案中使用。

devServer.allowedHosts

類型： string | string[] | 'all' | 'auto'
預設值： 'auto'

此選項可讓您允許存取開發伺服器的服務。

rspack.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 的任何其他子網域。

rspack.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'],
  },
};

當設定為 'all' 時，此選項會繞過主機檢查。不建議這樣做，因為不檢查主機的應用程式容易受到 DNS 重新綁定攻擊。

rspack.config.js

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

當設定為 'auto' 時，此選項始終允許 localhost、host 和 client.webSocketURL.hostname

rspack.config.js

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

devServer.client

類型： object

記錄

類型： 'log' | 'info' | 'warn' | 'error' | 'none' | 'verbose'
預設值： 'info'

允許在瀏覽器中設定記錄等級，例如在重新載入之前、發生錯誤之前或啟用熱模組替換時。

rspack.config.js

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

覆蓋

類型： boolean | object
預設值： true

當編譯器出現錯誤或警告時，在瀏覽器中顯示全螢幕覆蓋。

rspack.config.js

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

您可以提供具有以下屬性的物件，以進行更精細的控制

屬性	說明
`錯誤`	編譯錯誤
`執行階段錯誤`	未處理的執行階段錯誤
`警告`	編譯警告

所有屬性都是可選的，預設值為 true（如果沒有提供）。

例如，要停用編譯警告，您可以提供以下配置

rspack.config.js

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

若要根據拋出的錯誤進行篩選，您可以傳遞一個函數，該函數接受一個 error 參數並返回一個布林值。

例如，要忽略由 AbortController.abort() 拋出的錯誤

rspack.config.js

module.exports = {
  //...
  devServer: {
    client: {
      overlay: {
        runtimeErrors: error => {
          if (error instanceof DOMException && error.name === 'AbortError') {
            return false;
          }
          return true;
        },
      },
    },
  },
};

警告

此函數將無法存取在配置檔案中宣告的外部範圍變數。

進度

類型： boolean
預設值： true

在瀏覽器中以百分比顯示編譯進度。

rspack.config.js

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

重新連線

類型： boolean | number
預設值： true

告知開發伺服器應嘗試重新連線用戶端的次數。當設定為 true 時，將嘗試無限次重新連線。

rspack.config.js

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

當設定為 false 時，將不會嘗試重新連線。

rspack.config.js

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

您也可以指定用戶端應嘗試重新連線的確切次數。

rspack.config.js

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

WebSocket 傳輸

類型： 'ws' | 'sockjs'
預設值： ws

此選項允許我們為客戶端單獨選擇當前的 devServer 傳輸模式，或提供自定義客戶端實作。這允許指定瀏覽器或其他客戶端如何與 devServer 通訊。

提示

將 'ws' 或 'sockjs' 提供給 webSocketServer 相當於將 devServer.client.webSocketTransport 和 devServer.webSocketServer 都設定為給定的值。

rspack.config.js

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

提示

當提供自定義客戶端和伺服器實作時，請確保它們彼此相容，以便成功通訊。

若要建立自定義客戶端實作，請建立一個擴展 BaseClient 的類別。

使用 CustomClient.js 的路徑，一個自定義 WebSocket 客戶端實作，以及相容的 'ws' 伺服器

rspack.config.js

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

使用自定義、相容的 WebSocket 客戶端和伺服器實作

rspack.config.js

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

WebSocket URL

類型： string | object
預設值： {}

此選項允許指定 WebSocket 伺服器的 URL（當您代理開發伺服器且客戶端腳本並非總是知道要連線到哪裡時很有用）。

rspack.config.js

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

您也可以指定具有以下屬性的物件

hostname：告知連線到 devServer 的客戶端使用提供的主機名稱。
pathname：告知連線到 devServer 的客戶端使用提供的路徑進行連線。
password：告知連線到 devServer 的客戶端使用提供的密碼進行驗證。
port：告知連線到 devServer 的客戶端使用提供的端口。
protocol：告知連線到 devServer 的客戶端使用提供的協定。
username：告知連線到 devServer 的客戶端使用提供的使用者名稱進行驗證。

rspack.config.js

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

提示

若要從瀏覽器取得 protocol/hostname/port，請使用 webSocketURL: 'auto://0.0.0.0:0/ws'。

devServer.compress

類型： boolean
預設值： true

為所有提供的內容啟用 gzip 壓縮

rspack.config.js

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

devServer.devMiddleware

類型： object
預設值： {}

提供選項給 webpack-dev-middleware，它會處理 Rspack 資產。

rspack.config.js

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

devServer.headers

類型： array | function | object
預設值： undefined

將標頭新增至所有回應

rspack.config.js

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

您也可以傳遞陣列

rspack.config.js

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

您也可以傳遞函數

rspack.config.js

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

devServer.historyApiFallback

類型： boolean | object
預設值： false

當使用 HTML5 History API 時，index.html 頁面可能需要用來取代任何 404 回應。將 devServer.historyApiFallback 設定為 true 來啟用它

rspack.config.js

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

透過提供物件，可以使用 rewrites 之類的選項來進一步控制此行為

rspack.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

rspack.config.js

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

如需更多選項和資訊，請參閱 connect-history-api-fallback 文件。

devServer.host

類型： 'local-ip' | 'local-ipv4' | 'local-ipv6' | string
預設值： 'local-ip'

指定要使用的主機。如果您希望您的伺服器可從外部存取，請像這樣指定它

rspack.config.js

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

local-ip

將 local-ip 指定為主機將嘗試將主機選項解析為您的本機 IPv4 位址（如果可用），如果 IPv4 不可用，它將嘗試解析您的本機 IPv6 位址。

local-ipv4

將 local-ipv4 指定為主機將嘗試將主機選項解析為您的本機 IPv4 位址。

local-ipv6

將 local-ipv6 指定為主機將嘗試將主機選項解析為您的本機 IPv6 位址。

devServer.hot

類型： boolean | 'only'
預設值： true

啟用 Rspack 的熱模組替換功能

rspack.config.js

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

若要啟用熱模組替換功能，在建置失敗時不進行頁面重新整理，請使用 hot: 'only'

rspack.config.js

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

devServer.liveReload

類型： boolean
預設值： true

預設情況下，當偵測到檔案變更時，開發伺服器會重新載入/重新整理頁面。必須停用 devServer.hot 選項，或必須啟用 devServer.watchFiles 選項，liveReload 才能生效。將 devServer.liveReload 設定為 false 來停用它

rspack.config.js

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

提示

即時重新載入僅適用於與網頁相關的目標，例如 web、webworker、electron-renderer 和 node-webkit。

devServer.onListening

類型： function (devServer)

提供在 @rspack/dev-server 開始監聽端口上的連線時執行自定義函數的能力。

rspack.config.js

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

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

devServer.open

類型： boolean | string | object | [string, object]
預設值： true

告知開發伺服器在伺服器啟動後開啟瀏覽器。將其設定為 true 以開啟您的預設瀏覽器。

rspack.config.js

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

若要在瀏覽器中開啟指定的頁面

rspack.config.js

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

若要在瀏覽器中開啟多個指定的頁面

rspack.config.js

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

提供要使用的瀏覽器名稱，而不是預設瀏覽器

rspack.config.js

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

該物件接受所有 open 選項

rspack.config.js

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

提示

瀏覽器應用程式名稱與平台相關。請勿在可重複使用的模組中硬式編碼它。例如，'Chrome' 在 macOS 上是 'Google Chrome'，在 Linux 上是 'google-chrome'，在 Windows 上是 'chrome'。

devServer.port

類型： 'auto' | string | number
預設值： []

指定要監聽要求的端口號碼

rspack.config.js

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

port 選項不能為 null 或空字串，要自動使用可用端口，請使用 port: 'auto'

rspack.config.js

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

devServer.proxy

類型： [object, function]

提示

Rspack 中的 @rspack/dev-server 使用 webpack-dev-server v5，而 devServer.proxy 是一個陣列類型。如果您使用的配置是 v4 版本的物件類型，則需要先根據 webpack-dev-server/migration-v5.md 移轉進行遷移。

當您有一個單獨的 API 後端開發伺服器，並且想要在同一個網域上傳送 API 請求時，代理某些 URL 會很有用。

開發伺服器使用強大的 http-proxy-middleware 套件。請查看其文件，以瞭解更多進階用法。請注意，http-proxy-middleware 的某些功能不需要 target 鍵，例如其 router 功能，但您仍然需要在此處的配置中包含 target 鍵，否則 @rspack/dev-server 不會將其傳遞給 http-proxy-middleware。

如果後端在 localhost:3000 上，您可以使用它來啟用代理

rspack.config.js

module.exports = {
  //...
  devServer: {
    proxy: [
      {
        context: ['/api'],
        target: 'https://127.0.0.1:3000',
      },
    ],
  },
};

現在對 /api/users 的請求將會代理到 https://127.0.0.1:3000/api/users。

如果您不希望傳遞 /api，我們需要重寫路徑

rspack.config.js

module.exports = {
  //...
  devServer: {
    proxy: [
      {
        context: ['/api'],
        target: 'https://127.0.0.1:3000',
        pathRewrite: { '^/api': '' },
      },
    ],
  },
};

預設情況下，後端伺服器在具有無效憑證的 HTTPS 上執行將不被接受。如果您想這樣做，請修改您的配置，如下所示

rspack.config.js

module.exports = {
  //...
  devServer: {
    proxy: [
      {
        context: ['/api'],
        target: 'https://127.0.0.1:3000',
        secure: false,
      },
    ],
  },
};

有時您不希望代理所有請求。可以根據函數的回傳值來繞過代理。

在函數中，您可以存取請求 (request)、回應 (response) 和代理選項。

回傳 null 或 undefined 以繼續使用代理處理請求。
回傳 false 以產生請求的 404 錯誤。
回傳一個要服務的路徑，而不是繼續代理請求。

例如，對於瀏覽器請求，您想要服務一個 HTML 頁面，但對於 API 請求，您想要代理它。您可以這樣做

rspack.config.js

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

如果您想將多個特定路徑代理到同一個目標，您可以使用一個或多個具有 context 屬性的物件陣列

rspack.config.js

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

請注意，預設情況下不會代理對根目錄的請求。要啟用根目錄代理，應將 devMiddleware.index 選項指定為 falsy 值。

rspack.config.js

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

預設情況下，代理時會保留主機標頭的來源，您可以將 changeOrigin 設定為 true 來覆蓋此行為。在某些情況下，例如使用基於名稱的虛擬主機網站，這會很有用。

rspack.config.js

module.exports = {
  //...
  devServer: {
    proxy: [
      {
        context: ['/api'],
        target: 'https://127.0.0.1:3000',
        changeOrigin: true,
      },
    ],
  },
};

devServer.server

類型： 'http' | 'https' | 'spdy' | string | object
預設值： 'http'

允許設定伺服器和選項（預設為 'http'）。

rspack.config.js

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

要使用自簽憑證透過 HTTPS 提供服務

rspack.config.js

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

要使用 spdy 和自簽憑證透過 HTTP/2 提供服務

rspack.config.js

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

使用物件語法來提供您自己的憑證

rspack.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: '@rspack/dev-server',
        requestCert: true,
      },
    },
  },
};

它也允許您設定額外的 TLS 選項，例如 minVersion，並且您可以直接傳遞各自檔案的內容

rspack.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: '@rspack/dev-server',
        requestCert: true,
      },
    },
  },
};

devServer.setupMiddlewares

類型： function (middlewares, devServer)

提供執行自訂函數和應用自訂中介軟體的能⼒。

rspack.config.js

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

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

      // Use the `unshift` method if you want to run a middleware before all other middlewares
      // or when you are migrating from the `onBeforeSetupMiddleware` option
      middlewares.unshift({
        name: 'first-in-array',
        // `path` is optional
        path: '/foo/path',
        middleware: (req, res) => {
          res.send('Foo!');
        },
      });

      // Use the `push` method if you want to run a middleware after all other middlewares
      // or when you are migrating from the `onAfterSetupMiddleware` option
      middlewares.push({
        name: 'hello-world-test-one',
        // `path` is optional
        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

rspack.config.js

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

要監視單個目錄

rspack.config.js

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

要監視多個靜態目錄

rspack.config.js

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

devServer.watchFiles

類型： string | object | [string, object]

此選項允許您設定要監視檔案變更的 glob/目錄/檔案清單。例如

rspack.config.js

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

可以為監視檔案設定進階選項。請參閱 chokidar 文件以了解可能的選項。

rspack.config.js

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

devServer.webSocketServer

類型： false | 'sockjs' | 'ws'

此選項允許我們選擇目前的 WebSocket 伺服器或提供自訂的 WebSocket 伺服器實作。

目前預設模式為 'ws'。此模式使用 ws 作為伺服器，並在客戶端使用原生 WebSockets。

rspack.config.js

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

DevServer#

devServer.allowedHosts#

devServer.client#

記錄#

覆蓋#

進度#

重新連線#

WebSocket 傳輸#

WebSocket URL#

devServer.compress#

devServer.devMiddleware#

devServer.headers#

devServer.historyApiFallback#

devServer.host#

local-ip#

local-ipv4#

local-ipv6#

devServer.hot#

devServer.liveReload#

devServer.onListening#

devServer.open#

devServer.port#

devServer.proxy#

devServer.server#

devServer.setupMiddlewares#

devServer.static#

devServer.watchFiles#

devServer.webSocketServer#

DevServer

devServer.allowedHosts

devServer.client

記錄

覆蓋

進度

重新連線

WebSocket 傳輸

WebSocket URL

devServer.compress

devServer.devMiddleware

devServer.headers

devServer.historyApiFallback

devServer.host

local-ip

local-ipv4

local-ipv6

devServer.hot

devServer.liveReload

devServer.onListening

devServer.open

devServer.port

devServer.proxy

devServer.server

devServer.setupMiddlewares

devServer.static

devServer.watchFiles

devServer.webSocketServer