服务器选项

除非另有说明，本节中的选项仅适用于开发环境。

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.org.cn/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 ​