基本配置

约 1229 字大约 4 分钟

2025-10-23

基本配置

Vite 的开发体验来自“职责分层”：

开发期以原生 ESM + 快速转译为主
构建期交给成熟打包链路处理产物

Vite 与 Oxc 的关系（先讲清概念）

很多同学会把 Vite、esbuild、Rolldown、Oxc 混在一起。

在你当前这套笔记里，可以先按这个认知使用：

Vite 的核心是“统一开发与构建体验”的工程框架。
Oxc 更像高性能编译基础设施，在新一代打包生态中出现频率更高。
你在项目里是否直接使用 Oxc，不影响先掌握 Vite 的基础配置方法。

base

用于在嵌套的公共路径下部署项目时，重写资源路径

vite.config.ts

import { defineConfig } from 'vite'

/**
 * 例如在本地开发环境中使用的是 http://localhost:5173/ 
 * 而在实际线上部署时使用的是 https://example.com/admin/
 * 那么需要将 base 配置为 /admin/
 */

export default defineConfig({
  // 例如部署到 https://example.com/admin/
  base: '/admin/',
})

resolve

用于进行模块解析（Module Resolution）配置，专门用来告诉 Vite 如何查找和解析代码中的 import / require 语句

配置项	作用	常见写法	使用注意
`alias`	配置路径别名	`@ -> /src`	要和 `tsconfig.json` 保持一致
`extensions`	自动补全扩展名	`['.ts','.js']`	不建议塞太多，避免误解析
`dedupe`	强制依赖单实例	`['vue']`	解决 monorepo 或软链接重复实例
`conditions`	条件导出匹配	`['browser']`	仅在特殊包分发策略下使用
`preserveSymlinks`	是否保留软链接路径	`true/false`	monorepo 调试时偶尔需要

import { defineConfig } from 'vite'
import { resolve } from 'node:path'

export default defineConfig({
  resolve: {
    alias: {
      '@': resolve(__dirname, 'src'),
      '~components': resolve(__dirname, 'src/components'),
    },
    dedupe: ['vue'],
  },
})

server

用于配置开发服务器

配置项	作用	常见写法	使用注意
`host`	监听地址	`'0.0.0.0'`	便于局域网设备联调
`port`	开发端口	`5173`	固定端口便于团队协作
`strictPort`	端口被占用是否退出	`true`	避免自动换端口导致联调混乱
`open`	启动后自动打开浏览器	`true`	在远程开发环境通常关闭
`proxy`	接口代理	`'/api' -> target`	仅 dev 生效，prod 仍需网关
`hmr`	热更新策略	`{ overlay: true }`	可关闭报错浮层做定制处理

import { defineConfig } from 'vite'

export default defineConfig({
  server: {
    host: '0.0.0.0',
    port: 5173,
    strictPort: true,
    open: true,
    proxy: {
      '/api': {
        target: 'http://localhost:8080',
        changeOrigin: true,
        // /api/users -> /users
        rewrite: (path) => path.replace(/^\/api/, ''),
      },
    },
  },
})

define

用于定义全局常量替换，在开发环境下其值会被定义在全局，在构件时将直接被静态替换

笔记

若使用 TypeScript 则需要额外在 vite-env.d.ts 中添加声明以及类型

vite.config.ts

import { defineConfig } from 'vite'

export default defineConfig({
  define: {
    __APP_VERSION__: JSON.stringify('1.0.0'),
    __BUILD_TIME__: JSON.stringify(new Date().toISOString()),
  },
})

vite-env.d.ts

declare const __APP_VERSION__: string
declare const __BUILD_TIME__: string

index.ts

console.log(__APP_VERSION__)

css

用于配置 CSS 处理相关行为的，包括预处理器（Sass/Less）、PostCSS、CSS Modules、源码映射等

可配置项

css.postcss：配置 PostCSS 插件链
css.preprocessorOptions：配置 Sass/Less 等预处理器全局注入与编译参数
css.modules：配置 CSS Modules 命名策略与作用域行为
css.devSourcemap：控制开发环境 CSS sourcemap

import { defineConfig } from 'vite'

export default defineConfig({
  css: {
    // 1. PostCSS 配置
    postcss: {
      plugins: [
        require('autoprefixer'),
        require('tailwindcss'), // 或 @tailwindcss/vite 插件方式
      ]
    },

    // 2. 预处理器全局配置
    preprocessorOptions: {
      scss: {
        additionalData: `@use "@/styles/variables.scss" as *; 
                         @use "@/styles/mixins.scss" as *;`, // 全局注入变量和 mixin
        silenceDeprecations: ['legacy-js-api'], // 关闭 Sass 废弃警告
      },
      less: {
        javascriptEnabled: true,
        additionalData: '@import "@/styles/variables.less";',
      }
    },

    // 3. CSS Modules 配置
    modules: {
      localsConvention: 'camelCaseOnly', // class 名转为驼峰
      scopeBehaviour: 'local', // 默认 local
      generateScopedName: '[name]__[local]___[hash:base64:5]', // 自定义 hash
    },

    // 4. 开发环境 source map
    devSourcemap: true, // 方便调试
  },
})

publicDir

用于存放 "不需要经过构建处理" 的静态文件（如 favicon.ico）

vite.config.ts

import { defineConfig } from 'vite'

export default defineConfig({
  // 默认是 public；可以改目录，也可以设为 false 关闭
  publicDir: 'public',
})

index.html

<!-- public/logo.svg -> 直接以 /logo.svg 访问 -->
<img src="/logo.svg" alt="logo" />

build

用于控制 vite 打包行为

常用配置项

配置项	作用	常见写法	说明
`target`	指定产物语法目标	`'es2018'`	兼容性与体积需要平衡
`outDir`	输出目录	`'dist'`	部署目录通常直接指向这里
`assetsDir`	静态资源子目录	`'assets'`	便于部署侧做资源策略
`sourcemap`	生成 sourcemap	`true/false/'hidden'`	生产环境常用 `hidden`
`minify`	压缩方式	`'oxc'`	默认即可，除非有特殊要求
`cssCodeSplit`	CSS 是否拆分	`true/false`	多页面/异步场景建议开启
`assetsInlineLimit`	小资源内联阈值	`4096`	阈值过大会放大 JS 体积
`manifest`	生成清单文件	`true`	后端模板注入静态资源常用
`rollupOptions`	深度构建控制	`{ output: { ... } }`	详见 Rollup 章节

vite.config.ts

import { defineConfig } from 'vite'

export default defineConfig({
  build: {
    target: 'es2018',
    outDir: 'dist',
    assetsDir: 'assets',
    sourcemap: false,
    minify: 'esbuild',
    cssCodeSplit: true,
    assetsInlineLimit: 4096,
    manifest: true,
    rollupOptions: {
      output: {
        manualChunks: {
          // 把第三方依赖拆到 vendor，减少业务 chunk 抖动
          vendor: ['vue', 'vue-router'],
        },
      },
    },
  },
})

基础篇

性能优化篇

基础篇

性能优化篇

基本配置

基本配置

base

resolve

server

define

css

publicDir

build