Vite 配置详解

VitePress 基于 Vite 构建，通过 vite 字段可以直接配置 Vite 的所有选项。理解这些配置可以帮助你更好地优化开发体验和构建产物。

配置入口

VitePress 通过 defineConfig 的 vite 字段将配置传递给 Vite：

typescript

// .vitepress/config.mts
import { defineConfig } from 'vitepress'

export default defineConfig({
  // VitePress 站点配置
  title: '我的文档',
  description: '文档描述',

  // Vite 配置
  vite: {
    // 所有 Vite 配置选项均可在此使用
  }
})

优先级

VitePress 内部会预设一些 Vite 配置以保证正常工作。你在 vite 字段中的配置会与内部配置深度合并，你的配置优先级更高。

服务器配置

server 选项

开发服务器相关配置：

typescript

export default defineConfig({
  vite: {
    server: {
      // 指定开发服务器端口
      port: 5173,

      // 端口被占用时自动尝试下一个
      strictPort: false,

      // 自动打开浏览器
      open: true,

      // 配置 CORS
      cors: true,

      // 服务器启动时在终端显示的地址
      host: '0.0.0.0'
    }
  }
})

代理配置

开发环境中的 API 代理：

typescript

export default defineConfig({
  vite: {
    server: {
      proxy: {
        // 字符串简写
        '/api': 'http://localhost:3000',

        // 带选项的代理
        '/v1': {
          target: 'http://api.example.com',
          changeOrigin: true,
          rewrite: (path) => path.replace(/^\/v1/, '/api/v1')
        },

        // WebSocket 代理
        '/ws': {
          target: 'ws://localhost:3001',
          ws: true
        }
      }
    }
  }
})

注意

代理配置仅在开发环境生效。生产环境需要通过部署平台（如 Nginx、Vercel）配置反向代理。

解析配置

resolve 选项

模块解析相关配置：

typescript

export default defineConfig({
  vite: {
    resolve: {
      // 路径别名
      alias: {
        '@': '/.vitepress/theme',
        '@components': '/.vitepress/theme/components',
        '@composables': '/.vitepress/theme/composables',
        '@styles': '/.vitepress/theme/styles'
      },

      // 仅解析指定后缀的文件（减少解析时间）
      extensions: ['.mjs', '.js', '.ts', '.jsx', '.tsx', '.json', '.vue']
    }
  }
})

别名使用示例

配置别名后在组件和 TypeScript 中使用：

vue

<script setup lang="ts">
// 使用路径别名导入
import CustomCard from '@components/CustomCard.vue'
import { useTheme } from '@composables/useTheme'
</script>

构建配置

build 选项

生产构建相关配置：

typescript

export default defineConfig({
  vite: {
    build: {
      // 代码块大小警告阈值（单位：KB）
      chunkSizeWarningLimit: 1500,

      // Rollup 输出配置
      rollupOptions: {
        output: {
          // 手动代码分割
          manualChunks: {
            'vue-vendor': ['vue', 'vue-router'],
            'utils': ['@vueuse/core']
          },

          // 入口文件名
          entryFileNames: 'assets/[name]-[hash].js',

          // 代码块文件名
          chunkFileNames: 'assets/[name]-[hash].js',

          // 资源文件名
          assetFileNames: 'assets/[name]-[hash].[ext]'
        }
      },

      // CSS 代码分割
      cssCodeSplit: true,

      // 小于此阈值的资源内联为 base64
      assetsInlineLimit: 4096,

      // 启用/禁用 CSS 压缩
      minify: 'esbuild'
    }
  }
})

代码分割策略

合理的代码分割可以显著改善加载性能：

typescript

export default defineConfig({
  vite: {
    build: {
      rollupOptions: {
        output: {
          manualChunks(id) {
            // 将 node_modules 中的大型包单独拆分
            if (id.includes('node_modules')) {
              if (id.includes('vue')) return 'vue-vendor'
              if (id.includes('@vueuse')) return 'vueuse'
              if (id.includes('katex')) return 'katex'
              return 'vendor'
            }
          }
        }
      }
    }
  }
})

依赖优化

optimizeDeps 选项

依赖预构建配置：

typescript

export default defineConfig({
  vite: {
    optimizeDeps: {
      // 强制预构建的依赖
      include: [
        'vue',
        'vue-router',
        '@vueuse/core'
      ],

      // 排除预构建的依赖
      exclude: [
        'vitepress',
        '@vite-pwa/vitepress'
      ],

      // 预构建时使用的 ES 模块入口
      esbuildOptions: {
        target: 'es2020'
      }
    }
  }
})

预构建的作用

Vite 在开发模式下会使用 esbuild 预构建依赖，将 CommonJS/UMD 模块转换为 ESM 格式，大幅提升冷启动速度。

SSR 配置

ssr 选项

SSR（服务端渲染）相关配置：

typescript

export default defineConfig({
  vite: {
    ssr: {
      // SSR 外部化依赖（不打包进 SSR 产物）
      external: ['server-only-module'],

      // 不外部化的依赖（打包进 SSR 产物）
      noExternal: [
        'vue',
        'vue-router',
        // 包含 CSS 的包需要打包以确保 SSR 输出样式
        'my-ui-library'
      ]
    }
  }
})

SSR 兼容性问题

问题	原因	解决方案
`window is not defined`	代码在 Node.js 端执行	使用 `onMounted` 或 `defineClientComponent`
`document is not defined`	DOM API 在 SSR 中不可用	延迟到客户端执行
样式闪烁	SSR 和客户端渲染不一致	检查组件响应式数据初始化
第三方库报错	库不兼容 SSR	添加到 `ssr.external` 或使用动态导入

vue

<script setup lang="ts">
import { defineClientComponent } from 'vitepress/client'

// 仅在客户端加载的组件
const HeavyChart = defineClientComponent(() => {
  return import('./HeavyChart.vue')
})
</script>

<template>
  <HeavyChart />
</template>

CSS 配置

css 选项

CSS 处理相关配置：

typescript

export default defineConfig({
  vite: {
    css: {
      // CSS Modules 配置
      modules: {
        localsConvention: 'camelCaseOnly'
      },

      // 预处理器配置
      preprocessorOptions: {
        scss: {
          additionalData: `@import "/.vitepress/theme/styles/variables.scss";`
        }
      },

      // PostCSS 配置（也可使用 postcss.config.js）
      postcss: {
        plugins: [
          // PostCSS 插件
        ]
      }
    }
  }
})

日志与调试

logLevel 选项

控制 Vite 的日志输出级别：

typescript

export default defineConfig({
  vite: {
    // 'info' | 'warn' | 'error' | 'silent'
    logLevel: 'warn',

    // 自定义日志处理器
    customLogger: {
      info(msg) { console.log(msg) },
      warn(msg) { console.warn(msg) },
      error(msg) { console.error(msg) },
      warnOnce(msg) { console.warn(msg) },
      clearScreen(type) { /* ... */ },
      hasWarned: false
    }
  }
})

环境变量

envPrefix 选项

环境变量前缀配置：

typescript

export default defineConfig({
  vite: {
    // 只有以 VP_ 开头的环境变量才会暴露到客户端
    envPrefix: 'VP_'
  }
})

在代码中访问：

typescript

// 访问环境变量
const apiUrl = import.meta.env.VP_API_URL
const isDev = import.meta.env.DEV
const isProd = import.meta.env.PROD

define 选项

全局常量替换：

typescript

export default defineConfig({
  vite: {
    define: {
      __APP_VERSION__: JSON.stringify('1.0.0'),
      __API_BASE__: JSON.stringify(process.env.API_BASE || '/api')
    }
  }
})

完整配置示例

typescript

// .vitepress/config.mts
import { defineConfig } from 'vitepress'
import Components from 'unplugin-vue-components/vite'

export default defineConfig({
  title: '我的文档站',
  description: '技术文档',

  vite: {
    // 服务器
    server: {
      port: 5173,
      open: true,
      proxy: {
        '/api': 'http://localhost:3000'
      }
    },

    // 解析
    resolve: {
      alias: {
        '@': '/.vitepress/theme'
      }
    },

    // 依赖优化
    optimizeDeps: {
      include: ['vue', '@vueuse/core']
    },

    // 构建
    build: {
      chunkSizeWarningLimit: 1500,
      rollupOptions: {
        output: {
          manualChunks: {
            'vue-vendor': ['vue', 'vue-router']
          }
        }
      }
    },

    // SSR
    ssr: {
      noExternal: ['my-ui-library']
    },

    // 插件
    plugins: [
      Components({
        dirs: ['.vitepress/theme/components'],
        include: [/\.vue$/, /\.md$/],
        dts: '.vitepress/components.d.ts'
      })
    ]
  }
})

配置注意事项

注意点	说明
合并策略	VitePress 内部配置与你的配置深度合并，数组类型的配置会覆盖
SSR 兼容	`vite.server` 配置仅在开发环境生效，生产环境使用 SSR
路径规则	别名路径使用绝对路径，以 `/` 开头表示项目根目录
构建差异	部分选项（如 `server.proxy`）仅在开发环境有效
插件顺序	Vite 插件按数组顺序执行，注意插件间的依赖关系

Vite 配置详解

配置入口

服务器配置

server 选项

代理配置

解析配置

resolve 选项

别名使用示例

构建配置

build 选项

代码分割策略

依赖优化

optimizeDeps 选项

SSR 配置

ssr 选项

SSR 兼容性问题

CSS 配置

css 选项

日志与调试

logLevel 选项

环境变量

envPrefix 选项

define 选项

完整配置示例

配置注意事项

相关链接

贡献者

Vite 配置详解 ​

配置入口 ​

服务器配置 ​

server 选项 ​

代理配置 ​

解析配置 ​

resolve 选项 ​

别名使用示例 ​

构建配置 ​

build 选项 ​

代码分割策略 ​

依赖优化 ​

optimizeDeps 选项 ​

SSR 配置 ​

ssr 选项 ​

SSR 兼容性问题 ​

CSS 配置 ​

css 选项 ​

日志与调试 ​

logLevel 选项 ​

环境变量 ​

envPrefix 选项 ​

define 选项 ​

完整配置示例 ​

配置注意事项 ​

相关链接 ​

📖 相关文章推荐

贡献者

Vite 配置详解

配置入口

服务器配置

server 选项

代理配置

解析配置

resolve 选项

别名使用示例

构建配置

build 选项

代码分割策略

依赖优化

optimizeDeps 选项

SSR 配置

ssr 选项

SSR 兼容性问题

CSS 配置

css 选项

日志与调试

logLevel 选项

环境变量

envPrefix 选项

define 选项

完整配置示例

配置注意事项

相关链接