伺服器選項

除非另有說明，本節中的選項僅適用於開發模式。

server.host

類型： string | boolean
預設值： 'localhost'

指定伺服器應監聽的 IP 位址。將其設定為 0.0.0.0 或 true 以監聽所有位址，包括 LAN 和公開位址。

可以使用 CLI 透過 --host 0.0.0.0 或 --host 設定。

注意

在某些情況下，其他伺服器可能會回應而不是 Vite。

第一種情況是使用 localhost 時。在 v17 之前的 Node.js 版本中，預設會重新排序 DNS 解析位址的結果。當存取 localhost 時，瀏覽器會使用 DNS 解析位址，而該位址可能與 Vite 正在監聽的位址不同。當解析的位址不同時，Vite 會列印該位址。

您可以設定 dns.setDefaultResultOrder('verbatim') 以停用重新排序行為。Vite 屆時將會將位址列印為 localhost。

vite.config.js

import { defineConfig
 } from 'vite'
import dns
 from 'node:dns'

dns
.setDefaultResultOrder
('verbatim')

export default defineConfig
({
  // omit
})

第二種情況是使用萬用字元主機 (例如 0.0.0.0) 時。這是因為監聽非萬用字元主機的伺服器優先於監聽萬用字元主機的伺服器。

從您的 LAN 存取 WSL2 上的伺服器

在 WSL2 上執行 Vite 時，僅設定 host: true 不足以從您的 LAN 存取伺服器。請參閱 WSL 文件以瞭解更多詳細資訊。

server.port

類型： number
預設值： 5173

指定伺服器連接埠。請注意，如果連接埠已被使用，Vite 將自動嘗試下一個可用的連接埠，因此這可能不是伺服器最終實際監聽的連接埠。

server.strictPort

類型： boolean

設定為 true，若連接埠已被使用，則會結束程式，而不是自動嘗試下一個可用的連接埠。

server.https

類型： https.ServerOptions

啟用 TLS + HTTP/2。請注意，當同時使用 server.proxy 選項時，會降級為僅 TLS。

該值也可以是傳遞給 https.createServer() 的選項物件。

需要有效的憑證。對於基本設定，您可以將 @vitejs/plugin-basic-ssl 新增到專案外掛中，這會自動建立並快取自我簽署的憑證。但我們建議您建立自己的憑證。

server.open

類型： boolean | string

在伺服器啟動時自動在瀏覽器中開啟應用程式。當值為字串時，它將被用作 URL 的路徑名稱。如果您想在您喜歡的特定瀏覽器中開啟伺服器，您可以設定環境變數 process.env.BROWSER（例如 firefox）。您還可以設定 process.env.BROWSER_ARGS 以傳遞其他引數（例如 --incognito）。

BROWSER 和 BROWSER_ARGS 也是您可以在 .env 檔案中設定以進行設定的特殊環境變數。請參閱 open 套件以瞭解更多詳細資訊。

範例

export default defineConfig({
  server: {
    open: '/docs/index.html',
  },
})

server.proxy

類型： Record<string, string | ProxyOptions>

設定開發伺服器的自訂 Proxy 規則。期望使用 { key: options } 配對的物件。任何請求路徑以該鍵開頭的請求都將 Proxy 到指定目標。如果該鍵以 ^ 開頭，則將其解釋為 RegExp。可以使用 configure 選項來存取 Proxy 執行個體。如果請求與任何已設定的 Proxy 規則相符，則該請求將不會被 Vite 轉換。

請注意，如果您使用非相對的 base，則必須在每個鍵前面加上該 base。

擴充 http-proxy。其他選項在此。

在某些情況下，您可能還需要設定底層的開發伺服器（例如，將自訂的中介軟體新增到內部的 connect 應用程式）。為此，您需要編寫自己的外掛並使用 configureServer 函式。

範例

export default defineConfig({
  server: {
    proxy: {
      // string shorthand:
      // https://127.0.0.1:5173/foo
      //   -> https://127.0.0.1:4567/foo
      '/foo': 'https://127.0.0.1:4567',
      // with options:
      // https://127.0.0.1:5173/api/bar
      //   -> http://jsonplaceholder.typicode.com/bar
      '/api': {
        target: 'http://jsonplaceholder.typicode.com',
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/api/, ''),
      },
      // with RegExp:
      // https://127.0.0.1:5173/fallback/
      //   -> http://jsonplaceholder.typicode.com/
      '^/fallback/.*': {
        target: 'http://jsonplaceholder.typicode.com',
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/fallback/, ''),
      },
      // Using the proxy instance
      '/api': {
        target: 'http://jsonplaceholder.typicode.com',
        changeOrigin: true,
        configure: (proxy, options) => {
          // proxy will be an instance of 'http-proxy'
        },
      },
      // Proxying websockets or socket.io:
      // ws://127.0.0.1:5173/socket.io
      //   -> ws://127.0.0.1:5174/socket.io
      // Exercise caution using `rewriteWsOrigin` as it can leave the
      // proxying open to CSRF attacks.
      '/socket.io': {
        target: 'ws://127.0.0.1:5174',
        ws: true,
        rewriteWsOrigin: true,
      },
    },
  },
})

server.cors

類型： boolean | CorsOptions

設定開發伺服器的 CORS。預設啟用此功能並允許任何來源。傳遞選項物件以微調行為或 false 以停用。

server.headers

類型： OutgoingHttpHeaders

指定伺服器回應標頭。

server.hmr

類型： boolean | { protocol?: string, host?: string, port?: number, path?: string, timeout?: number, overlay?: boolean, clientPort?: number, server?: Server }

停用或設定 HMR 連線（在 HMR WebSocket 必須使用與 HTTP 伺服器不同的位址的情況下）。

將 server.hmr.overlay 設定為 false 以停用伺服器錯誤覆蓋。

protocol 設定用於 HMR 連線的 WebSocket 通訊協定：ws (WebSocket) 或 wss (WebSocket Secure)。

clientPort 是一個進階選項，僅在用戶端覆寫連接埠，允許您在與用戶端程式碼尋找它的不同連接埠上提供 WebSocket。

定義 server.hmr.server 時，Vite 將透過提供的伺服器處理 HMR 連線請求。如果不在中介軟體模式下，Vite 將嘗試透過現有的伺服器處理 HMR 連線請求。當使用自我簽署的憑證或想要在單一連接埠上透過網路公開 Vite 時，這可能會很有幫助。

請查看 vite-setup-catalogue 以取得一些範例。

注意

使用預設設定時，預期位於 Vite 前面的反向 Proxy 支援 Proxy WebSocket。如果 Vite HMR 用戶端無法連線 WebSocket，用戶端將會退回直接連線 WebSocket 到 Vite HMR 伺服器，繞過反向 Proxy

Direct websocket connection fallback. Check out https://vite.dev.org.tw/config/server-options.html#server-hmr to remove the previous connection error.

發生退回時在瀏覽器中出現的錯誤可以忽略。若要避免直接繞過反向 Proxy 的錯誤，您可以執行以下操作

設定反向 Proxy 也 Proxy WebSocket
將 server.strictPort = true 設定為 server.hmr.clientPort，其值與 server.port 相同
將 server.hmr.port 設定為與 server.port 不同的值

server.warmup

類型： { clientFiles?: string[], ssrFiles?: string[] }
相關： 預熱常用檔案

預熱要轉換的檔案並預先快取結果。這可以改善伺服器啟動期間的初始頁面載入，並防止轉換瀑布。

clientFiles 是僅在用戶端中使用的檔案，而 ssrFiles 是僅在 SSR 中使用的檔案。它們接受檔案路徑或相對於 root 的 tinyglobby 模式的陣列。

請務必只新增常用檔案，以免在啟動時使 Vite 開發伺服器過載。

export default defineConfig({
  server: {
    warmup: {
      clientFiles: ['./src/components/*.vue', './src/utils/big-utils.js'],
      ssrFiles: ['./src/server/modules/*.js'],
    },
  },
})

server.watch

類型： object | null

要傳遞給 chokidar 的檔案系統觀察器選項。

Vite 伺服器觀察器會觀察 root 並預設跳過 .git/、node_modules/ 以及 Vite 的 cacheDir 和 build.outDir 目錄。更新受觀察的檔案時，Vite 將套用 HMR，並且僅在需要時更新頁面。

如果設定為 null，則不會觀察任何檔案。server.watcher 將提供相容的事件發射器，但呼叫 add 或 unwatch 將不會產生任何影響。

觀察 node_modules 中的檔案

目前無法監看 node_modules 中的檔案和套件。如需了解進一步的進展和解決方案，您可以追蹤 issue #8619。

在 Windows Subsystem for Linux (WSL) 2 上使用 Vite

在 WSL2 上執行 Vite 時，當檔案由 Windows 應用程式（非 WSL2 處理程序）編輯時，檔案系統監看功能將無法運作。這是由於 WSL2 的限制所致。這也適用於使用 WSL2 後端在 Docker 上執行的情況。

要解決此問題，您可以選擇以下其中一種方式：

推薦：使用 WSL2 應用程式來編輯您的檔案。
- 也建議將專案資料夾移至 Windows 檔案系統之外。從 WSL2 存取 Windows 檔案系統速度較慢。移除這個額外負擔將會改善效能。
設定 { usePolling: true }。
- 請注意，usePolling 會導致 CPU 使用率偏高。

server.middlewareMode

類型： boolean
預設值： false

以中介軟體模式建立 Vite 伺服器。

相關： appType、 SSR - 設定開發伺服器
範例

import express
 from 'express'
import { createServer
 as createViteServer
 } from 'vite'

async function createServer
() {
  const app
 = express
()

  // Create Vite server in middleware mode
  const vite
 = await createViteServer
({
    server
: { middlewareMode
: true },
    // don't include Vite's default HTML handling middlewares
    appType
: 'custom',
  })
  // Use vite's connect instance as middleware
  app
.use
(vite
.middlewares
)

  app
.use
('*', async (req
, res
) => {
    // Since `appType` is `'custom'`, should serve response here.
    // Note: if `appType` is `'spa'` or `'mpa'`, Vite includes middlewares
    // to handle HTML requests and 404s so user middlewares should be added
    // before Vite's middlewares to take effect instead
  })
}

createServer
()

server.fs.strict

類型： boolean
預設值： true （自 Vite 2.7 起預設啟用）

限制在工作區根目錄之外提供檔案。

server.fs.allow

類型： string[]

限制可透過 /@fs/ 提供的檔案。當 server.fs.strict 設定為 true 時，存取此目錄清單之外的檔案，且該檔案並非從允許的檔案匯入，將會導致 403 錯誤。

可以提供目錄和檔案。

Vite 將會搜尋潛在工作區的根目錄，並將其作為預設值。有效的工作區符合以下條件，否則將會回退至專案根目錄。

package.json 中包含 workspaces 欄位
包含以下其中一個檔案
- lerna.json
- pnpm-workspace.yaml

接受路徑以指定自訂工作區根目錄。可以是絕對路徑，或是相對於專案根目錄的路徑。例如：

export default defineConfig({
  server: {
    fs: {
      // Allow serving files from one level up to the project root
      allow: ['..'],
    },
  },
})

當指定 server.fs.allow 時，將停用自動工作區根目錄偵測。為了擴展原始行為，公開了一個實用工具 searchForWorkspaceRoot

import { defineConfig, searchForWorkspaceRoot } from 'vite'

export default defineConfig({
  server: {
    fs: {
      allow: [
        // search up for workspace root
        searchForWorkspaceRoot(process.cwd()),
        // your custom rules
        '/path/to/custom/allow_directory',
        '/path/to/custom/allow_file.demo',
      ],
    },
  },
})

server.fs.deny

類型： string[]
預設值： ['.env', '.env.*', '*.{crt,pem}', '**/.git/**']

禁止敏感檔案由 Vite 開發伺服器提供的封鎖清單。這將比 server.fs.allow 具有更高的優先權。支援 picomatch 模式。

server.origin

類型： string

定義開發期間產生的資源 URL 的來源。

export default defineConfig({
  server: {
    origin: 'http://127.0.0.1:8080',
  },
})

server.sourcemapIgnoreList

類型： false | (sourcePath: string, sourcemapPath: string) => boolean
預設值： (sourcePath) => sourcePath.includes('node_modules')

是否忽略伺服器 source map 中的原始碼檔案，用於填入 x_google_ignoreList source map 擴充功能。

server.sourcemapIgnoreList 等同於開發伺服器的 build.rollupOptions.output.sourcemapIgnoreList。這兩個設定選項之間的差異在於，rollup 函數會以 sourcePath 的相對路徑呼叫，而 server.sourcemapIgnoreList 則是以絕對路徑呼叫。在開發期間，大多數模組的 map 和原始碼位於同一個資料夾中，因此 sourcePath 的相對路徑就是檔案名稱本身。在這些情況下，絕對路徑使用起來更為方便。

預設情況下，它會排除所有包含 node_modules 的路徑。您可以傳遞 false 來停用此行為，或者，為了完全控制，您可以傳遞一個接受原始碼路徑和 source map 路徑的函數，並傳回是否要忽略原始碼路徑。

export default defineConfig({
  server: {
    // This is the default value, and will add all files with node_modules
    // in their paths to the ignore list.
    sourcemapIgnoreList(sourcePath, sourcemapPath) {
      return sourcePath.includes('node_modules')
    },
  },
})

注意

server.sourcemapIgnoreList 和 build.rollupOptions.output.sourcemapIgnoreList 需要獨立設定。server.sourcemapIgnoreList 是一個僅限伺服器的設定，不會從已定義的 rollup 選項取得其預設值。

伺服器選項 ​

server.host ​

server.port ​

server.strictPort ​

server.https ​

server.open ​

server.proxy ​

server.cors ​

server.headers ​

server.hmr ​

server.warmup ​

server.watch ​

server.middlewareMode ​

server.fs.strict ​

server.fs.allow ​

server.fs.deny ​

server.origin ​

server.sourcemapIgnoreList ​