Vite 配置文件怎么写？路径别名如何避免踩坑？

Vite 配置文件不复杂，但项目变大后，真正需要管理的东西会变多：开发服务器、代理、路径别名、构建输出、CSS、环境变量、依赖预构建和插件顺序。好的配置不是把所有选项都写满，而是把开发体验和生产产物的边界分清楚。

配置文件从哪里来

Vite 默认识别 vite.config.js、vite.config.mjs、vite.config.ts、vite.config.cjs。现代 TypeScript 项目通常用 vite.config.ts，配合 defineConfig 能拿到类型提示。

ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  server: { port: 5173, open: true },
  build: { outDir: 'dist', sourcemap: false }
})

如果配置要根据命令变化，可以导出函数。command 区分 serve 和 build，mode 对应 development、production 或自定义模式。

ts
export default defineConfig(({ command, mode }) => ({
  base: mode === 'production' ? '/app/' : '/',
  build: { sourcemap: command === 'serve' }
}))

server 只影响开发环境

server 常用选项有 host、port、open、proxy、cors、https、watch。本地联调最常见的是代理，把 /api 转到后端服务，避免开发环境跨域。

ts
export default defineConfig({
  server: {
    host: '0.0.0.0',
    port: 5173,
    proxy: {
      '/api': {
        target: 'https://api.example.com',
        changeOrigin: true,
        rewrite: p => p.replace(/^\/api/, '')
      }
    }
  }
})

边界要记住：server.proxy 不会进入生产环境。上线后的代理要交给 Nginx、网关、BFF 或后端 CORS。

build 决定产物形态

build.outDir 控制输出目录，assetsDir 控制资源目录，target 决定语法目标，minify 决定压缩方式。复杂分包和文件命名通常写在 rollupOptions。

ts
export default defineConfig({
  build: {
    target: 'es2020',
    chunkSizeWarningLimit: 800,
    rollupOptions: {
      output: {
        chunkFileNames: 'assets/[name]-[hash].js',
        assetFileNames: 'assets/[name]-[hash][extname]'
      }
    }
  }
})

不要一看到 chunk 警告就手写大量 manualChunks。分包能改善缓存，也可能制造更多请求；先分析体积来源，再动配置更稳。

路径别名要配两处

Vite 的别名写在 resolve.alias，TypeScript 的编辑器和类型解析写在 tsconfig.json 的 paths。只配一边，常见结果是开发能跑但编辑器报错，或编辑器不报错但构建失败。

ts
import { fileURLToPath, URL } from 'node:url'
import { defineConfig } from 'vite'

export default defineConfig({
  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url))
    }
  }
})

json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": { "@/*": ["src/*"] }
  }
}

ESM 配置里不要直接用 __dirname。用 fileURLToPath(new URL(..., import.meta.url)) 更稳。

CSS 和 optimizeDeps 怎么放

CSS 配置常用于 CSS Modules、预处理器和 PostCSS；optimizeDeps 用来处理依赖预构建的扫描盲区或兼容性问题。

ts
export default defineConfig({
  css: {
    modules: { localsConvention: 'camelCaseOnly' },
    preprocessorOptions: {
      scss: { additionalData: '@use "@/styles/vars.scss" as *;' }
    }
  },
  optimizeDeps: { include: ['lodash-es'] }
})

additionalData 适合注入变量和 mixin，不适合注入会产出实际 CSS 的规则，否则每个文件都会重复生成。

追问

为什么配了 @ 别名，编辑器还是报错？

通常是只配了 vite.config.ts，没配 tsconfig.json。Vite 管运行和构建，TypeScript 管类型和编辑器提示，它们不是同一个解析器。取舍上两份配置有重复，但显式配置最可控。

server.proxy 能当线上代理吗？

不能。它只在 vite dev 的开发服务器里生效，构建产物只是静态文件。线上要用 Nginx、CDN 边缘函数、网关或后端 CORS；本地正常、线上 404，多半就是把开发代理当成了生产能力。

base 应该怎么配置？

部署在域名根路径就用 /，部署在 /app/ 就写 /app/。同时还要同步前端路由的 basename 或 history base。只改 Vite 的 base 不改路由，刷新深层页面仍可能出问题。

optimizeDeps.include 什么时候需要？

当动态导入、插件生成入口或依赖扫描盲区导致开发时反复重新优化，可以把依赖加入 include。但它不是越多越好，包含太多会拖慢冷启动。先看控制台提示和缓存行为，再决定是否手动配置。