服务器选项
除非另有说明,本节中的选项仅应用于开发环境。
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
。
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.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()
的 选项对象。
请注意,当同时使用 server.proxy
选项时,这会降级为仅 TLS。
需要有效的证书。对于基本设置,您可以将 @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 }
对的对象。任何请求路径以该键开头的请求都将代理到指定的 target。如果键以 ^
开头,它将被解释为 RegExp
。可以使用 configure
选项来访问代理实例。如果请求与任何配置的代理规则匹配,则该请求将不会被 Vite 转换。
请注意,如果您使用的是非相对 base
,则必须在该 base
前缀每个键。
扩展 http-proxy
。其他选项 在此处。
在某些情况下,您可能还想配置底层开发服务器(例如,将自定义中间件添加到内部 connect 应用程序)。为了做到这一点,你需要编写你自己的 插件 并使用 configureServer 函数。
示例
export default defineConfig({
server: {
proxy: {
// string shorthand:
// http://localhost:5173/foo
// -> http://localhost:4567/foo
'/foo': 'http://localhost:4567',
// with options:
// http://localhost:5173/api/bar
// -> http://jsonplaceholder.typicode.com/bar
'/api': {
target: 'http://jsonplaceholder.typicode.com',
changeOrigin: true,
rewrite: (path) => path.replace(/^\/api/, ''),
},
// with RegExp:
// http://localhost: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://localhost:5173/socket.io
// -> ws://localhost:5174/socket.io
// Exercise caution using `rewriteWsOrigin` as it can leave the
// proxying open to CSRF attacks.
'/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
以允许任何来源。
危险
将 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,客户端将回退到将 WebSocket 直接连接到 Vite HMR 服务器,绕过反向代理
Direct websocket connection fallback. Check out https://vite.vuejs.ac.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.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 }
。
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')
是否忽略服务器 sourcemap 中的源文件,用于填充 x_google_ignoreList
源代码映射扩展。
server.sourcemapIgnoreList
等效于开发服务器的 build.rollupOptions.output.sourcemapIgnoreList
。两个配置选项之间的区别在于,rollup 函数使用 sourcePath
的相对路径调用,而 server.sourcemapIgnoreList
使用绝对路径调用。在开发期间,大多数模块的 map 和 source 位于同一文件夹中,因此 sourcePath
的相对路径是文件名本身。在这些情况下,绝对路径使其方便使用。
默认情况下,它排除所有包含 node_modules
的路径。您可以传递 false
以禁用此行为,或者,为了完全控制,可以使用一个函数,该函数接受源路径和 sourcemap 路径,并返回是否忽略源路径。
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 选项中获取其默认值。