伺服器選項

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

server.host

型別： string | boolean
預設： 'localhost'

指定伺服器應監聽的 IP 地址。將其設定為 0.0.0.0 或 true 以監聽所有地址，包括區域網和公共地址。

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

注意

在某些情況下，其他伺服器可能會代替 Vite 響應。

第一種情況是使用 localhost 時。Node.js v17 以下版本預設會重新排序 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）時。這是因為監聽非萬用字元主機的伺服器優先順序高於監聽萬用字元主機的伺服器。

在區域網中訪問 WSL2 上的伺服器

在 WSL2 上執行 Vite 時，僅設定 host: true 不足以讓你從區域網訪問伺服器。詳情請參閱 WSL 文件。

server.allowedHosts

型別： string[] | true
預設： []

允許 Vite 響應的主機名。預設允許 localhost、.localhost 下的域名以及所有 IP 地址。使用 HTTPS 時，此檢查將被跳過。

如果字串以 . 開頭，則允許該主機名及其所有子域名（不包含 . 本身）。例如，.example.com 將允許 example.com、foo.example.com 和 foo.bar.example.com。如果設定為 true，則伺服器允許響應任何主機的請求。

新增哪些主機是安全的？

如果你能控制主機名解析到的 IP 地址，那麼將其新增到允許主機列表中是安全的。

例如，如果你擁有域名 vite.dev，你可以將 vite.dev 和 .vite.dev 新增到列表中。如果你不擁有該域名且不信任該域名的所有者，則不應新增它。

特別要注意的是，切勿將頂級域名（如 .com）新增到列表中。因為任何人都可以購買像 example.com 這樣的域名並控制其解析的 IP 地址。

危險

將 server.allowedHosts 設定為 true 會允許任何網站透過 DNS 重繫結攻擊向你的開發伺服器傳送請求，從而導致它們下載你的原始碼和內容。我們建議始終使用明確的允許主機列表。詳情請參閱 GHSA-vg6x-rcgg-rjx6。

透過環境變數配置

你可以設定環境變數 __VITE_ADDITIONAL_SERVER_ALLOWED_HOSTS 來新增額外的允許主機。

server.port

型別： number
預設： 5173

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

server.strictPort

型別： boolean

設定為 true 後，如果埠已被佔用，伺服器將直接退出，而不是嘗試下一個可用埠。

server.https

型別： https.ServerOptions

啟用 TLS + HTTP/2。該值是傳遞給 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>

為開發伺服器配置自定義代理規則。期望一個 { key: options } 對的物件。任何請求路徑以該 key 開頭的請求都將被代理到指定的目標。如果 key 以 ^ 開頭，它將被解釋為 RegExp。可以使用 configure 選項來訪問代理例項。如果請求匹配配置的任何代理規則，則該請求將不會被 Vite 轉換。

注意：如果你使用的是非相對路徑的 base，則必須為每個 key 新增該 base 字首。

擴充套件自 http-proxy-3。更多選項見此處。

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

示例

export default defineConfig({
  server: {
    proxy: {
      // string shorthand:
      // https://:5173/foo
      //   -> https://:4567/foo
      '/foo': 'https://:4567',
      // with options:
      // https://:5173/api/bar
      //   -> http://jsonplaceholder.typicode.com/bar
      '/api': {
        target: 'http://jsonplaceholder.typicode.com',
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/api/, ''),
      },
      // with RegExp:
      // https://: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://:5173/socket.io
      //   -> ws://:5174/socket.io
      // Exercise caution using `rewriteWsOrigin` as it can leave the
      // proxying open to CSRF attacks.
      '/socket.io': {
        target: 'ws://:5174',
        ws: true,
        rewriteWsOrigin: true,
      },
    },
  },
})

server.cors

型別： boolean | CorsOptions
預設： { origin: /^https?:\/\/(?:(?:[^:]+\.)?localhost|127\.0\.0\.1|\[::1\])(?::\d+)?$/ }（允許 localhost、127.0.0.1 和 ::1）

為開發伺服器配置 CORS。傳入一個選項物件以微調行為，或設定為 true 以允許任何源。

危險

將 server.cors 設定為 true 會允許任何網站向你的開發伺服器傳送請求並下載你的原始碼和內容。我們建議始終使用明確的允許源列表。

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 前端的反向代理應支援代理 WebSocket。如果 Vite HMR 客戶端連線 WebSocket 失敗，客戶端將回退為直接連線到 Vite HMR 伺服器，從而繞過反向代理。

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

當發生回退時，瀏覽器中顯示的錯誤可以忽略。若要透過直接繞過反向代理來避免該錯誤，你可以：

配置反向代理以同時代理 WebSocket
設定 server.strictPort = true 並將 server.hmr.clientPort 設定為與 server.port 相同的值
將 server.hmr.port 設定為與 server.port 不同的值

server.forwardConsole

型別： boolean | { unhandledErrors?: boolean, logLevels?: ('error' | 'warn' | 'info' | 'log' | 'debug')[] }
預設： 自動（當基於 @vercel/detect-agent 檢測到 AI 編碼代理時為 true，否則為 false）

在開發期間將瀏覽器執行時事件轉發到 Vite 伺服器控制檯。

true 啟用轉發未捕獲的錯誤以及 console.error / console.warn 日誌。
unhandledErrors 控制是否轉發未捕獲的異常和未處理的 Promise 拒絕。
logLevels 控制轉發哪些 console.* 呼叫。

例如：

export default defineConfig({
  server: {
    forwardConsole: {
      unhandledErrors: true,
      logLevels: ['warn', 'error'],
    },
  },
})

當轉發未捕獲的錯誤時，它們會以增強的格式記錄在伺服器終端中，例如：

日誌

1:18:38 AM [vite] (client) [Unhandled error] Error: this is test error
 > testError src/main.ts:20:8
     18|
     19| function testError() {
     20|   throw new Error('this is test error')
       |        ^
     21| }
     22|
 > HTMLButtonElement.<anonymous> src/main.ts:6:2

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/、test-results/ 以及 Vite 的 cacheDir 和 build.outDir 目錄。更新監聽檔案時，Vite 將應用 HMR 並僅在必要時更新頁面。

如果設定為 null，則不會監聽任何檔案。server.watcher 將提供相容的事件觸發器，但呼叫 add 或 unwatch 將不起作用。

監聽 node_modules 中的檔案

目前無法監聽 node_modules 中的檔案和包。有關進展和變通方法，請關注 issue #8619。

在 Windows 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 模式。

注意

此黑名單不適用於 public 目錄。public 目錄中的所有檔案在構建時都會直接複製到輸出目錄，因此會被無過濾地提供服務。

server.origin

型別： string

定義開發期間生成的資源 URL 的 origin。

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

server.sourcemapIgnoreList

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

是否忽略伺服器源對映中的原始檔，用於填充 x_google_ignoreList 源對映擴充套件。

server.sourcemapIgnoreList 相當於開發伺服器的 build.rollupOptions.output.sourcemapIgnoreList。這兩個配置選項的一個區別是，rollup 函式呼叫時 sourcePath 為相對路徑，而 server.sourcemapIgnoreList 呼叫時 sourcePath 為絕對路徑。在開發過程中，大多數模組的 map 和原始檔都在同一個資料夾中，因此 sourcePath 的相對路徑就是檔名本身。在這種情況下，使用絕對路徑會更方便。

預設情況下，它會排除所有包含 node_modules 的路徑。你可以傳遞 false 來停用此行為，或者為了完全控制，傳入一個函式，該函式接收源路徑和源對映路徑並返回是否忽略該源路徑。

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.allowedHosts ​

server.port ​

server.strictPort ​

server.https ​

server.open ​

server.proxy ​

server.cors ​

server.headers ​

server.hmr ​

server.forwardConsole ​

server.warmup ​

server.watch ​

server.middlewareMode ​

server.fs.strict ​

server.fs.allow ​

server.fs.deny ​

server.origin ​

server.sourcemapIgnoreList ​