vite.config.ts

Vite 项目根目录的配置文件，控制开发服务器、构建、插件、路径解析等所有行为。支持 .js/.ts/.mjs 等多种扩展名，vite/vite build/vite preview 启动时自动查找并加载。

基本写法

import { defineConfig } from 'vite'
 
export default defineConfig({
  // config options
})

defineConfig 是类型提示辅助函数，不用它也可以直接 export default { ... } 或配合 satisfies UserConfig 拿类型检查，但用 defineConfig 是社区默认写法。

条件配置

配置项可能需要根据 serve（开发）还是 build（生产）区分，这时导出一个函数而不是对象：

export default defineConfig(({ command, mode, isSsrBuild, isPreview }) => {
  if (command === 'serve') {
    return {
      // dev 专属配置
    }
  } else {
    // command === 'build'
    return {
      // build 专属配置
    }
  }
})

注意 command 在开发时的值是 serve（vite/vite dev/vite serve 都是它的别名），生产构建时是 build。也支持返回 Promise 做异步配置（比如需要先 await 读取远程配置）。

核心字段（shared，dev+build+preview 通用）

字段	说明
`root`	项目根目录（`index.html` 所在位置），默认 `process.cwd()`
`base`	公共基础路径，部署到子路径（如 `/foo/`）时用，默认 `/`
`mode`	覆盖默认 mode（`serve` 默认 `development`，`build` 默认 `production`）
`define`	全局常量替换，构建时静态替换，运行时当全局变量注入
`plugins`	插件数组，Vite 生态的扩展点
`publicDir`	静态资源目录，原样复制不经过转换，默认 `public`
`resolve.alias`	路径别名映射，类似 `@rollup/plugin-alias`
`resolve.dedupe`	强制去重的依赖列表，解决 monorepo 下同一依赖多份拷贝的问题

define 示例

export default defineConfig({
  define: {
    __APP_VERSION__: JSON.stringify('v1.0.0'),
    __API_URL__: 'window.__backend_api_url', // 单个标识符，不会被字符串化
  },
})

配合 TypeScript 需要在 vite-env.d.ts 里补类型声明（declare const __APP_VERSION__: string）才有类型提示。

resolve.alias 示例

export default defineConfig({
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
      utils: '../../../utils',
    },
  },
})

别名指向文件系统路径时务必用绝对路径，相对路径不会被解析成文件系统路径。

server 配置（仅开发生效）

字段	说明
`server.host`	监听地址，默认 `localhost`，设为 `true`/`0.0.0.0` 监听所有地址（含局域网）
`server.port`	端口，默认 `5173`，被占用会自动尝试下一个可用端口
`server.strictPort`	设为 `true` 时端口被占用直接退出，不自动切换
`server.open`	启动后自动打开浏览器，可传字符串指定打开的路径
`server.proxy`	开发服务器代理规则，转发指定前缀的请求到后端
`server.allowedHosts`	允许响应的 hostname 白名单，防止 DNS rebinding 攻击

proxy 示例

export default defineConfig({
  server: {
    port: 3000,
    proxy: {
      '/api': 'http://localhost:8080',
      '/api2': {
        target: 'http://localhost:8081',
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/api2/, ''),
      },
    },
  },
})

build 配置（仅构建生效）

字段	说明
`build.target`	产物浏览器兼容目标，默认 `baseline-widely-available`（覆盖近两年主流浏览器），`esnext` 只做最小转译
`build.outDir`	输出目录，相对项目根，默认 `dist`
`build.assetsDir`	静态资源子目录，相对 `outDir`，默认 `assets`
`build.assetsInlineLimit`	小于该体积（默认 4KB）的资源内联为 base64，避免额外请求
`build.cssCodeSplit`	CSS 代码分割开关，默认开启；关闭后全部 CSS 合并成一个文件
`build.sourcemap`	是否生成 sourcemap
`build.minify`	压缩方式，`esbuild`（默认，快）或 `terser`（体积更小但更慢）
`build.rollupOptions`	透传给底层打包器的原生配置（如自定义多入口 `input`）
`build.lib`	库模式配置，打包成可发布的库而非应用

常用插件配置示例

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
 
export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      '@': '/src',
    },
  },
  server: {
    port: 3000,
    proxy: {
      '/api': 'http://localhost:8080',
    },
  },
  build: {
    outDir: 'dist',
    sourcemap: true,
  },
})

配置文件本身的环境变量限制

vite.config.ts 执行时能拿到的环境变量只有当前进程已存在的 process.env，Vite 故意延迟到 config 解析完之后才加载 .env* 文件（因为要加载哪些 .env 文件本身依赖 root/envDir/mode 等配置项）。也就是说 .env、.env.local 等文件里的变量默认不会自动注入到配置文件执行时的 process.env，它们是后续才加载、暴露给应用代码的 import.meta.env。如果 config 文件本身需要读 .env* 的值（比如根据它决定 server.port），要用 loadEnv 手动加载。

与其他配置文件的关系

tsconfig.json：Vite 会读取其中的 compilerOptions.paths/baseUrl 影响模块解析，但不做类型检查（默认用 esbuild 只转译不校验类型），类型检查需要单独跑 tsc --noEmit 或装 vite-plugin-checker，详见 tsconfig-json
package.json：scripts 里的 dev/build/preview 通常直接映射到 vite/vite build/vite preview 命令，详见 package-json

zhaoweiguo 的知识库

目录