开发服务器选项

vite-main配置参考

开发服务器选项

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

server.host

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

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

也可以通过 CLI 使用 --host 0.0.0.0 或 --host 进行设置。

::: tip 注意

在某些情况下，其他服务器可能代替 Vite 进行响应。

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

第二种情况是使用通配符主机（如 0.0.0.0）时。这是因为监听非通配符主机的服务器优先于监听通配符主机的服务器。

::: tip 在 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，服务器允许响应任意主机的请求。

::: details 哪些主机可以安全添加？

你可以控制其解析到哪些 IP 地址的主机，是添加到允许主机列表中的安全选项。

例如，如果你拥有域名 vite.dev，你可以将 vite.dev 和 .vite.dev 添加到列表中。如果你不拥有该域名，并且无法信任该域名的所有者，则不应将其添加。

尤其是，你永远不应将顶级域（如 .com）添加到列表中。因为任何人都可以购买类似 example.com 的域名，并控制其解析到的 IP 地址。

::: danger 危险

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

::: details 通过环境变量配置

你可以设置环境变量 __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 包。

示例：
js 复制代码
export default defineConfig({
  server: {
    open: '/docs/index.html',
  },
})
server.proxy

类型： Record<string, string | ProxyOptions>

为开发服务器配置自定义代理规则。需要提供一个 { key: options } 对的对象。任何请求路径以该键开头的请求，都将被代理到指定的目标。如果键以 ^ 开头，它将被解释为 RegExp。configure 选项可用于访问代理实例。如果请求匹配任何配置的代理规则，则该请求将不会被 Vite 转换。

注意，如果你使用了非相对的 base，则必须为每个键加上该 base 前缀。

扩展自 http-proxy-3。其他选项见此处。

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

示例：
js 复制代码
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/, ''),
      },
      // 使用 RegExp：
      // 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-3' 的一个实例
        },
      },
      // 代理 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

类型： boolean | CorsOptions

默认： { origin: /^https?:\/\/(?:(?:[^:]+\.)?localhost|127\.0\.0\.1|\[::1\])(?::\d+)?$/ }（允许 localhost、127.0.0.1 和 ::1）

为开发服务器配置 CORS。传入一个选项对象以微调行为，或传入 true 以允许任意来源。 danger 危险

将 server.cors 设置为 true 会允许任何网站向你的开发服务器发送请求并下载你的源代码和内容。我们建议始终使用明确的允许来源列表。

server.headers

类型： OutgoingHttpHeaders

指定服务器响应头。

server.hmr

类型： boolean | { overlay?: boolean }

禁用或配置 HMR 行为。

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

与 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 - 使用自定义 HTTP 服务器处理 WebSocket 连接

当定义了 server.ws.server 时，Vite 将通过提供的服务器处理 WebSocket 连接请求。如果不在中间件模式下，Vite 将尝试通过现有服务器处理 WebSocket 连接请求。这在以下情况中很有帮助：使用自签名证书，或者希望通过单个端口在网络上暴露 Vite。
js 复制代码
export default defineConfig({
  server: {
    ws: {
      protocol: 'wss',
      host: 'localhost',
      port: 3001,
    },
  },
})
查看 vite-setup-catalogue 获取一些示例。 tip 注意

使用默认配置时，期望 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.* 调用被转发。

例如：
js 复制代码
export default defineConfig({
  server: {
    forwardConsole: {
      unhandledErrors: true,
      logLevels: ['warn', 'error'],
    },
  },
})
当未处理错误被转发时，它们会以增强的格式化方式记录在服务器终端中，例如：
log 复制代码
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 开发服务器过载。
js 复制代码
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 将不会产生任何效果。 warning 监视 node_modules 中的文件

目前无法监视 node_modules 中的文件和包。有关进一步进展和变通方法，你可以关注 issue #8619。

::: warning 在 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 | { server: http.Server }
默认： false

以中间件模式创建 Vite 服务器。

如果为 proxy 设置了 WebSocket，则应提供 server 以正确绑定代理。

相关： appType、SSR - 设置开发服务器
示例：

js twoslash 复制代码

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

接受路径以指定自定义工作区根目录。可以是绝对路径，也可以是相对于项目根目录的路径。例如：

js 复制代码

export default defineConfig({
  server: {
    fs: {
      // 允许从项目根目录上一级提供文件
      allow: ['..'],
    },
  },
})

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

js 复制代码

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

类型： string[]
默认： ['.env', '.env.*', '*.{crt,pem,key,p12,pfx,cer,der}', '.npmrc', '.yarnrc.yml', '**/.git/**']

用于限制 Vite 开发服务器提供敏感文件的黑名单。其优先级高于 server.fs.allow。支持 picomatch 模式。

::: tip 注意

此黑名单不适用于 public 目录。public 目录中的所有文件都会无过滤地提供，因为它们在构建时会被直接复制到输出目录。

::: tip 注意

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

server.origin

类型： string

定义开发期间生成的资源 URL 的来源。

js 复制代码

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 source map 扩展。

server.sourcemapIgnoreList 相当于开发服务器的 build.rolldownOptions.output.sourcemapIgnoreList。这两个配置选项之间的一个区别是，Rolldown 函数使用相对路径调用 sourcePath，而 server.sourcemapIgnoreList 使用绝对路径。在开发期间，大多数模块的 map 和源文件位于同一文件夹中，因此 sourcePath 的相对路径就是文件名本身。在这些情况下，使用绝对路径更加方便。

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

js 复制代码

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

::: tip 注意
server.sourcemapIgnoreList 和 build.rolldownOptions.output.sourcemapIgnoreList 需要独立设置。server.sourcemapIgnoreList 是仅服务器的配置，不会从定义的 Rolldown 选项中获取其默认值。
:::

帮助我们改进文档

发现翻译问题或内容错误？请告诉我们。