服务器选项

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

server.host

类型： string | boolean
默认值： 'localhost'

指定服务器应该监听哪些 IP 地址。将其设置为 0.0.0.0 或 true 以监听所有地址，包括局域网和公共地址。

可以通过 CLI 使用 --host 0.0.0.0 或 --host 来设置。

注意

在某些情况下，其他服务器可能会响应而不是 Vite。

第一种情况是使用了 localhost。Node.js 的 dns.setDefaultResultOrder 改变了 DNS 解析地址的排序方式，浏览器使用的解析地址可能与 Vite 监听的地址不同。当解析地址不同时，Vite 会打印出来。

第二种情况是使用了通配符主机（例如 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 地址。

DANGER

将 server.allowedHosts 设置为 true 允许任何网站通过 DNS 重绑定攻击向你的开发服务器发送请求，从而下载你的源代码和内容。我们建议始终使用明确的允许主机列表。请参阅 GHSA-vg6x-rcgg-rjx6 了解更多详情。

通过环境变量配置

你可以设置环境变量 __VITE_ADDITIONAL_SERVER_ALLOWED_HOSTS 来添加额外的允许主机。使用逗号分隔多个主机（例如 host1.example.com,host2.example.com）。

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，你必须在每个键前加上该 base 前缀。

扩展自 http-proxy-3。其他选项见这里。

在某些情况下，你可能还想配置底层开发服务器（例如向内部的 connect 应用添加自定义中间件）。为此，你需要编写自己的插件并使用 configureServer 函数。

示例：

export default defineConfig({
  server: {
    proxy: {
      // 字符串简写：
      // http://localhost:5173/foo
      //   -> http://localhost:4567/foo
      '/foo': 'http://localhost:4567',
      // 带选项：
      // http://localhost:5173/api/bar
      //   -> http://jsonplaceholder.typicode.com/bar
      '/api': {
        target: 'http://jsonplaceholder.typicode.com',
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/api/, ''),
      },
      // 带正则表达式：
      // http://localhost:5173/fallback/
      //   -> http://jsonplaceholder.typicode.com/
      '^/fallback/.*': {
        target: 'http://jsonplaceholder.typicode.com',
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/fallback/, ''),
      },
      // 使用代理实例
      '/api': {
        target: 'http://jsonplaceholder.typicode.com',
        changeOrigin: true,
        configure: (proxy, options) => {
          // proxy 将是 'http-proxy' 的一个实例
        },
      },
      // 代理 websockets 或 socket.io：
      // ws://localhost:5173/socket.io
      //   -> ws://localhost:5174/socket.io
      // 使用 `rewriteWsOrigin` 时要小心，因为它可能使
      // 代理易受 CSRF 攻击。
      '/socket.io': {
        target: 'ws://localhost:5174',
        ws: true,
        rewriteWsOrigin: true,
      },
    },
  },
})

server.cors

Type: boolean | CorsOptions
Default: { origin: /^https?:\/\/(?:(?:[^:]+\.)?localhost|127\.0\.0\.1|\[::1\])(?::\d+)?$/ } (allows localhost, 127.0.0.1, and ::1)

Configure CORS for the development server. Pass an options object to fine-tune behavior, or pass true to allow any origin.

DANGER

Setting server.cors to true allows any website to send requests to your development server and download your source code and content. We recommend always using an explicit allowlist of origins.

server.headers

类型： OutgoingHttpHeaders

指定服务器响应头。

server.hmr

类型： boolean | { overlay?: boolean }

禁用或配置 HMR 行为。

将 server.hmr.overlay 设置为 false 以禁用服务器错误覆盖层。

已弃用的选项

与 WebSocket 相关的选项（protocol、host、port、path、clientPort、timeout、server）已弃用。请改用 server.ws。这些选项会自动同步，因此现有配置将继续生效。

server.ws

类型： false | { protocol?: string, host?: string, port?: number, path?: string, timeout?: number, clientPort?: number, server?: Server }

配置 WebSocket 连接选项。设置为 false 可完全禁用 WebSocket 连接。

protocol - WebSocket 协议（ws 或 wss）
host - WebSocket 服务器主机
port - WebSocket 服务器端口
path - WebSocket 路径
clientPort - 覆盖客户端使用的端口，使你可以让 websocket 运行在与客户端代码查找不同的端口上
timeout - 连接超时时间，单位毫秒（默认：30000）
server - 为 WebSocket 连接使用自定义 HTTP 服务器

当定义了 server.ws.server 时，Vite 会通过提供的服务器处理 WebSocket 连接请求。如果不是中间件模式，Vite 将尝试通过现有服务器处理 WebSocket 连接请求。这在使用自签名证书或希望通过单个端口在网络上暴露 Vite 时很有帮助。

export default defineConfig({
  server: {
    ws: {
      protocol: 'wss',
      host: 'localhost',
      port: 3001,
    },
  },
})

查看 vite-setup-catalogue 获取一些示例。

注意

使用默认配置时，Vite 前面的反向代理应该支持代理 WebSocket。如果 Vite HMR 客户端连接 WebSocket 失败，客户端将回退到直接连接 Vite HMR 服务器，绕过反向代理：

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

当发生回退时，浏览器中出现的错误可以忽略。要通过直接绕过反向代理来避免错误，你可以：

同时配置反向代理以代理 WebSocket
设置 server.strictPort = true 并将 server.ws.clientPort 设置为与 server.port 相同的值
将 server.ws.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'],
    },
  },
})

当转发未处理的错误时，它们会以增强的格式记录在服务器终端中，例如：

log

1:18:38 AM [vite] (client) [未处理的错误] 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 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
()

  // 以中间件模式创建 Vite 服务器
  const vite
 = await createViteServer
({
    server
: { middlewareMode
: true },
    // 不包含 Vite 默认的 HTML 处理中间件
    appType
: 'custom',
  })
  // 使用 vite 的 connect 实例作为中间件
  app
.use
(vite
.middlewares
)

  app
.use
('*', async (req
, res
) => {
    // 由于 `appType` 是 `'custom'`，应该在此处提供响应。
    // 注意：如果 `appType` 是 `'spa'` 或 `'mpa'`，Vite 包含中间件
    // 来处理 HTML 请求和 404，因此用户中间件应该添加
    // 在 Vite 的中间件之前才能生效
  })
}

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: ['..'],
    },
  },
})

当指定 server.fs.allow 时，自动工作区根目录检测将被禁用。为了扩展原始行为，暴露了一个工具函数 searchForWorkspaceRoot：

import { defineConfig, searchForWorkspaceRoot } from 'vite'

export default defineConfig({
  server: {
    fs: {
      allow: [
        // 向上搜索工作区根目录
        searchForWorkspaceRoot(process.cwd()),
        // 你的自定义规则
        '/path/to/custom/allow_directory',
        '/path/to/custom/allow_file.demo',
      ],
    },
  },
})

server.fs.deny

Type: string[]
Default: ['.env', '.env.*', '*.{crt,pem,key,p12,pfx,cer,der}', '.npmrc', '.yarnrc.yml', '**/.git/**']

限制由 Vite 开发服务器提供的敏感文件的阻止列表。这将比 server.fs.allow 具有更高的优先级。支持 picomatch 模式。

注意

此阻止列表不适用于公共目录。公共目录中的所有文件都无需任何过滤即可提供，因为它们在构建期间直接复制到输出目录。

NOTE

拒绝过滤器应用于模块 ID 以及去除查询参数后的 ID。由于插件可以在其加载钩子中读取任何文件（包括将符号链接解析为被拒绝路径），Vite 无法保证被拒绝的文件无法通过替代路径访问。如果你有其他替代路径，也请将其包含在拒绝列表中。

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')

是否忽略服务器 sourcemap 中的源文件，用于填充 x_google_ignoreList 源映射扩展。

server.sourcemapIgnoreList 是开发服务器中 build.rolldownOptions.output.sourcemapIgnoreList 的对应项。两者之间的区别在于，rollup 函数接收的 sourcePath 是相对路径，而 server.sourcemapIgnoreList 接收的是绝对路径。在开发过程中，大多数模块的 map 和 source 都位于同一文件夹中，因此 sourcePath 的相对路径本身就是文件名。在这些情况下，使用绝对路径反而更方便。

默认情况下，它会排除所有包含 node_modules 的路径。你可以传递 false 来禁用此行为，或者为了完全控制，传递一个接受源路径和 sourcemap 路径并返回是否忽略源路径的函数。

export default defineConfig({
  server: {
    // 这是默认值，会将所有路径中包含 node_modules
    // 的文件添加到忽略列表中。
    sourcemapIgnoreList(sourcePath, sourcemapPath) {
      return sourcePath.includes('node_modules')
    },
  },
})

Note

server.sourcemapIgnoreList 和 build.rolldownOptions.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.ws ​

server.forwardConsole ​

server.warmup ​

server.watch ​

server.middlewareMode ​

server.fs.strict ​

server.fs.allow ​

server.fs.deny ​

server.origin ​

server.sourcemapIgnoreList ​