Vite 配置入门

默认配置已经能让 Vite 很好用，但真实项目往往需要定制，比如改端口、配代理、改部署路径。这一篇我们系统讲 vite.config.js 的写法和最常用的配置项。

配置文件的创建与位置

在项目根目录（和 index.html 同级）新建 vite.config.js 即可，Vite 启动时自动读取它。如果用了 TypeScript，文件名可以是 vite.config.ts。

defineConfig 辅助函数

写配置时建议用 Vite 提供的 defineConfig 包裹配置对象，它能带来类型提示，写错字段名编辑器会提醒你。

import { defineConfig } from 'vite'

export default defineConfig({
  // 所有配置都在这里
})

root 项目根目录

root 指定项目的根目录，默认就是配置文件所在的目录。如果你的 HTML 入口不在根目录，比如放在 src 下，可以这样改：

export default defineConfig({
  root: 'src'
})

多数情况下不用动它。

base 部署基础路径

base 决定资源在最终页面里的基础路径。默认是 /，表示部署在域名根下。

如果你要把项目部署到子路径，比如 https://example.com/my-app/，就必须改 base：

export default defineConfig({
  base: '/my-app/'
})

否则上线后 CSS、JS 这些资源的路径会 404。这是新手部署时最常见的坑之一。

server 开发服务器配置

开发时最常用的配置都在 server 里。

export default defineConfig({
  server: {
    port: 3000,        // 改端口
    open: true,        // 启动后自动打开浏览器
    host: true,        // 允许局域网其他设备访问
    proxy: {           // 接口代理，解决跨域
      '/api': {
        target: 'http://localhost:8080',
        changeOrigin: true
      }
    }
  }
})

proxy 特别实用。前端开发时后端接口可能在另一个端口，直接请求会跨域。配了代理后，浏览器请求 /api/xxx 会被 Vite 转发到 http://localhost:8080/api/xxx，跨域问题迎刃而解。

build 构建配置

build 控制生产构建的行为，最常见的几个：

export default defineConfig({
  build: {
    outDir: 'dist',        // 输出目录，默认 dist
    assetsDir: 'assets',   // 资源子目录
    sourcemap: false,      // 是否生成 source map
    minify: 'esbuild'      // 压缩工具，默认 esbuild
  }
})

这些配置的详细用法我们会在生产构建那一篇展开。

区分开发和生产环境

很多配置只在特定环境需要。你可以用 defineConfig 接收一个函数，根据 mode 返回不同配置。

export default defineConfig(({ mode }) => {
  if (mode === 'development') {
    return {
      server: { open: true }
    }
  }
  return {
    base: '/my-app/'
  }
})

mode 在 npm run dev 时是 development，在 npm run build 时是 production。你也可以在执行命令时用 --mode 指定自定义环境，比如 vite build --mode staging。

配置优先级

配置的覆盖顺序是，命令行参数 > 环境变量 > 配置文件 > 默认值。一般你只需要维护好 vite.config.js 就够了。

本篇小结

• 用 defineConfig 写配置，获得类型提示。
• base 部署到子路径时必须改，否则资源 404。
• server.proxy 是开发跨域的标配解法。
• 通过 defineConfig(({ mode }) => ...) 区分环境。

下一篇我们进入 Vite 真正强大之处，插件系统。