서버 옵션

별도로 명시되지 않은 한, 이 섹션의 옵션들은 개발 환경에만 적용됩니다.

server.host

타입: string | boolean
기본값: 'localhost'

서버가 수신할 IP 주소를 지정합니다. LAN와 공용 주소를 포함한 모든 주소를 수신하려면 이 값을 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)가 사용되는 경우입니다. 와일드카드가 아닌 호스트에서 수신하는 서버가 와일드카드 호스트에서 수신하는 서버보다 우선하기 때문입니다.

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 주소로 연결할 수 있습니다.

DANGER

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 } 쌍의 객체를 받습니다. 요청 경로가 해당 키로 시작하는 모든 요청은 지정된 대상으로 프록시됩니다. 키가 ^로 시작하면 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/, ''),
      },
      // 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'의 인스턴스가 됩니다
        },
      },
      // 웹소켓 또는 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로 설정하면 모든 웹사이트에서 개발 서버에 요청을 보내고 소스 코드와 콘텐츠를 다운로드할 수 있게 됩니다. 따라서 항상 명시적으로 허용할 출처(origin) 목록을 사용할 것을 권장합니다.

server.headers

타입: OutgoingHttpHeaders

서버 응답 헤더를 지정합니다.

server.hmr

타입: boolean | { protocol?: string, host?: string, port?: number, path?: string, timeout?: number, overlay?: boolean, clientPort?: number, server?: Server }

HMR 연결을 설정하거나 사용하지 않을 수 있습니다. (HMR 웹소켓이 http 서버와 다른 주소를 사용해야 하는 경우)

서버 오류 오버레이를 사용하지 않으려면 server.hmr.overlay를 false로 설정하세요.

protocol은 HMR 연결에 사용되는 웹소켓 프로토콜을 설정합니다: ws (웹소켓) 또는 wss (보안 웹소켓) 값을 갖습니다.

clientPort는 클라이언트 측의 포트만 재정의하는 고급 옵션으로, 클라이언트 코드에서 찾는 것과 다른 포트에서 웹소켓을 제공할 수 있습니다.

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.dev/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'],
    },
  },
})

처리되지 않은 오류가 전달되면 서버 터미널에 향상된 형식으로 기록됩니다. 예를 들어:

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[] }
관련 항목: Warm Up Frequently Used Files

미리 변환하고 그 결과물을 캐시할 파일 목록입니다. 서버 시작 시 초기 페이지 로드를 개선하고 변환 워터폴(변환이 순차적으로 이루어지는 현상 - 옮긴이)을 방지합니다.

옵션의 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에 전달할 파일 시스템 감시자(Watcher) 옵션입니다.

Vite 서버 감시자는 기본적으로 root를 감시하며, .git/, node_modules/, test-results/, 그리고 Vite의 cacheDir 및 build.outDir 디렉터리는 건너뜁니다. 감시하는 파일이 업데이트되면, Vite는 필요한 경우에만 HMR을 적용하고 페이지를 업데이트합니다.

null로 설정하면 파일을 감시하지 않습니다. server.watcher는 호환되는 이벤트 이미터를 제공하지만, add 또는 unwatch를 호출해도 아무런 효과가 없습니다.

node_modules에서 파일 감시하기

현재 node_modules의 파일과 패키지는 감시할 수 없습니다. 더 많은 진행 상황과 해결 방법은 #8619 이슈를 참고해 주세요.

Windows Subsystem for Linux (WSL) 2 에서 Vite 사용하기

WSL2에서 Vite를 실행할 때, WSL2가 아닌 타 Windows 응용 프로그램에서 파일을 편집하면 파일 시스템 변경사항 감시 기능이 정상적으로 동작하지 않습니다. 이는 WSL2 제한사항으로 인한 것이며, WSL2 백엔드가 존재하는 Docker에서 실행하는 경우에도 동일합니다.

이를 해결하기 위해 아래 중 하나를 시도할 수 있습니다:

권고 사항: WSL2 응용 프로그램을 사용해 파일을 편집
- 또한 WSL2에서 Windows 파일 시스템에 접근하는 것은 느리기 때문에 프로젝트 폴더를 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

타입: string[]
기본값: ['.env', '.env.*', '*.{crt,pem}', '**/.git/**']

Vite 개발 서버가 제공하는 것을 제한할 민감한 파일에 대한 차단 목록입니다. 이 옵션은 server.fs.allow보다 높은 우선 순위를 가집니다. 피코매치 패턴이 지원됩니다.

참고

이 차단 목록은 Public 디렉터리에 적용되지 않습니다. Public 디렉터리 내 모든 파일은 빌드 시 결과물 출력 디렉터리에 직접 복사되므로, 어떠한 필터링 없이 제공됩니다.

참고

deny 필터는 모듈 id와 쿼리 매개변수가 제거된 id에 적용됩니다. 플러그인은 load 훅에서 어떤 파일이든 읽을 수 있으므로(차단된 경로로 확인되는 심볼릭 링크 포함), Vite는 차단된 파일이 대체 경로를 통해 접근 불가능하다고 보장할 수 없습니다. 대체 경로가 있다면 deny 목록에도 포함하세요.

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에 대한 상대 경로는 파일 이름 자체입니다. 이러한 경우 절대 경로를 사용하면 편리합니다.

기본적으로 node_modules가 포함된 모든 경로를 제외합니다. 이 동작을 비활성화하려면 false를 전달하거나, 완전한 제어를 위해 소스 경로와 소스맵 경로를 받아 소스 경로를 무시할지 여부를 반환하는 함수를 전달할 수 있습니다.

export default defineConfig({
  server: {
    // 이는 기본값이며, 경로에 node_modules가 포함된 모든 파일을
    // 무시할 목록에 추가합니다.
    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 ​