vite

Vite 7

React 项目的构建工具和开发服务器。Vite 7（2025 年 6 月）仅支持 ESM，要求 Node.js 20.19+ / 22.12+，并将浏览器目标默认设为 baseline-widely-available。用户的技术栈使用 rolldown-vite（基于 Rust 的即插即用替代方案）、@vitejs/plugin-react、@tailwindcss/vite、@tanstack/router-plugin、@cloudflare/vite-plugin 和 @tanstack/react-start。

关键规则

插件顺序很重要

TanStack Start 或 TanStack Router 插件必须放在 @vitejs/plugin-react 之前：

plugins: [
  tanstackStart(),      // or tanstackRouter() for SPA
  tailwindcss(),
  react(),              // ALWAYS last among framework plugins
]

顺序错误会导致路由生成失败和 HMR 故障。

Vite 7 仅支持 ESM

Vite 7 仅以 ESM 形式发布。vite.config.ts 必须使用 import/export 语法。配置文件不支持 CJS require()。Node.js 20.19+ 原生支持 require(esm)，因此 CJS 消费者仍可通过 require 使用 Vite。

不要使用 tailwind.config.js

Tailwind CSS v4 使用 CSS 优先的配置方式。切勿创建 tailwind.config.js/tailwind.config.ts。使用 @tailwindcss/vite 插件，并通过 CSS 中的 @theme、@utility、@plugin 进行配置。

环境变量需要使用 VITE_ 前缀

只有带有 VITE_ 前缀的变量才会通过 import.meta.env 暴露给客户端代码。仅供服务端使用的密钥不得使用此此前缀。为确保类型安全，请在 vite-env.d.ts 中扩展 ImportMetaEnv。

splitVendorChunkPlugin 已移除

该插件已在 Vite 7 中移除。自定义代码分块请使用 build.rollupOptions.output.manualChunks。

配置

vite.config.ts（使用 TanStack Start 的全栈应用）

import { defineConfig } from 'vite'
import { tanstackStart } from '@tanstack/react-start/plugin/vite'
import { cloudflare } from '@cloudflare/vite-plugin'
import tailwindcss from '@tailwindcss/vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [
    tanstackStart(),
    cloudflare(),
    tailwindcss(),
    react(),
  ],
  resolve: {
    alias: {
      '@': new URL('./src', import.meta.url).pathname,
    },
  },
})

vite.config.ts（使用 TanStack Router 的 SPA）

import { defineConfig } from 'vite'
import { tanstackRouter } from '@tanstack/router-plugin/vite'
import tailwindcss from '@tailwindcss/vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [
    tanstackRouter({ autoCodeSplitting: true }),
    tailwindcss(),
    react(),
  ],
  resolve: {
    alias: {
      '@': new URL('./src', import.meta.url).pathname,
    },
  },
})

React Compiler

react({
  babel: {
    plugins: [['babel-plugin-react-compiler', {}]],
  },
})

安装：pnpm add -D babel-plugin-react-compiler。自动为组件和钩子添加记忆化，无需手动使用 useMemo/useCallback。

路径别名

使用 import.meta.url 进行兼容 ESM 的解析（ESM 中没有 __dirname）：

resolve: {
  alias: {
    '@': new URL('./src', import.meta.url).pathname,
  },
}

在 tsconfig.json 中同步配置："paths": { "@/*": ["./src/*"] }

环境变量

文件：.env、.env.local、.env.[mode]、.env.[mode].local。只有带有 VITE_ 前缀的变量才会暴露给客户端。内置常量：import.meta.env.MODE、.DEV、.PROD、.SSR、.BASE_URL。

在 src/vite-env.d.ts 中扩展类型：

interface ImportMetaEnv {
  readonly VITE_API_URL: string
}
interface ImportMeta {
  readonly env: ImportMetaEnv
}

插件生态系统

@vitejs/plugin-react

提供 Fast Refresh（React 的 HMR）、JSX 转换，以及可选的 Babel 插件处理流程。始终将其放在框架插件的最后。

import react from '@vitejs/plugin-react'

react()                          // zero-config default
react({ fastRefresh: false })    // disable for debugging HMR issues

@tailwindcss/vite

为 Tailwind CSS v4 提供原生 Vite 集成。它取代基于 PostCSS 的配置，无需 postcss.config.js。

import tailwindcss from '@tailwindcss/vite'

tailwindcss()  // zero-config, reads @theme from CSS

@tanstack/router-plugin/vite

为 TanStack Router 生成基于文件的路由。必须放在 react() 之前。

import { tanstackRouter } from '@tanstack/router-plugin/vite'

tanstackRouter({ autoCodeSplitting: true })

@tanstack/react-start/plugin/vite

TanStack Start 的全栈插件。内部已包含路由插件，不要同时添加两者。

import { tanstackStart } from '@tanstack/react-start/plugin/vite'

tanstackStart()                           // default SSR
tanstackStart({ spa: { enabled: true } }) // SPA mode (no SSR)

@cloudflare/vite-plugin

开发期间在 workerd 中运行 Worker 代码，使其行为与生产环境一致。使用 Vite 的 Environment API 集成运行时。

import { cloudflare } from '@cloudflare/vite-plugin'

cloudflare()  // reads wrangler.jsonc by default

// Programmatic config (no wrangler file needed)
cloudflare({
  config: {
    name: 'my-worker',
    compatibility_flags: ['nodejs_compat'],
  },
})

开发服务器

代理配置

server: {
  proxy: {
    '/api': {
      target: 'http://localhost:8787',
      changeOrigin: true,
      rewrite: (path) => path.replace(/^\/api/, ''),
    },
    '/ws': { target: 'ws://localhost:8787', ws: true },
  },
}

HMR 故障排查

症状	解决方法
完整重新加载而非 HMR	检查是否已加载 plugin-react
HMR 无法连接	如果位于反向代理之后，请设置 server.hmr.clientPort
编辑后状态过期	组件必须只导出一个组件
CSS 未更新	确认 @tailwindcss/vite 已添加到插件中

位于反向代理之后时：

server: {
  hmr: { protocol: 'ws', host: 'localhost', port: 5173, clientPort: 443 },
}

文件预热

server: {
  warmup: {
    clientFiles: ['./src/components/*.tsx', './src/routes/__root.tsx'],
  },
}

构建优化

默认浏览器目标

Vite 7 的目标为 baseline-widely-available（Chrome 107+、Edge 107+、Firefox 104+、Safari 16+）。覆盖设置：build.target: 'es2020' 或 ['chrome90', 'safari14']。

手动分块

build: {
  rollupOptions: {
    output: {
      manualChunks: {
        'react-vendor': ['react', 'react-dom'],
        'tanstack': ['@tanstack/react-router', '@tanstack/react-query'],
      },
    },
  },
}

按函数动态分块：

manualChunks(id) {
  if (id.includes('node_modules')) {
    if (id.includes('react')) return 'react-vendor'
    if (id.includes('@tanstack')) return 'tanstack'
    return 'vendor'
  }
}

Bundle 分析

pnpm add -D rollup-plugin-visualizer

import { visualizer } from 'rollup-plugin-visualizer'

// Add to plugins array
visualizer({ filename: 'stats.html', open: true, gzipSize: true })

有关分块策略、CSS 分割、资源内联、源映射和性能调优的详细信息，请参阅 build-optimization.md。

Rolldown 集成

什么是 rolldown-vite

rolldown-vite 是基于 Rust 的 Vite 打包器直接替代方案，由 Vite 团队开发（由 VoidZero 赞助）。它用一个基于 Rolldown 和 Oxc 工具集构建的高性能工具，同时替代 esbuild 和 Rollup。据报道，构建时间缩短了 3 到 16 倍，大型项目的内存用量最多减少 100 倍。

Rolldown 将成为 Vite 8 中的默认打包器（目前处于 beta 阶段）。现在使用 rolldown-vite，可为项目做好迁移准备。

注意： Vite 7 需要 Vitest 3.2+ 才能兼容。更早版本的 Vitest 无法使用。

安装

在 package.json 中，将 vite 别名指向 rolldown-vite：

{
  "devDependencies": {
    "vite": "npm:rolldown-vite@latest"
  }
}

对于将 Vite 作为对等依赖的 monorepo 或框架，请使用 overrides：

{
  "pnpm": {
    "overrides": {
      "vite": "npm:rolldown-vite@latest"
    }
  }
}

然后运行 pnpm install。无需更改配置——它可直接替代原有工具。

与标准 Vite 的主要区别

• 不依赖 esbuild——Oxc 负责所有转换和压缩（配置中仍会显示 minify: 'esbuild'，但底层引擎是 Oxc）
• 构建更快——基于 Rust 的原生打包，尤其适用于大型项目
• 插件 API 相同——大多数情况下，Rollup/Vite 插件无需更改即可使用
• 补丁版本可能导致问题——rolldown-vite 遵循 Vite 的主版本和次版本，但补丁版本独立发布

兼容性说明

大多数框架和 Vite 插件都能直接使用。请查看 rolldown-vite 仓库，了解已知问题和更新日志。过渡期间可能会出现有关不支持选项的警告。

环境 API

Vite 6 引入的实验性 API，在 Vite 7 中通过 buildApp 钩子得到改进。它支持通过单个 Vite 配置构建多个目标（浏览器、Node.js、边缘运行时）。

工作原理

每个环境都有独立的模块图、插件流水线和构建配置。@cloudflare/vite-plugin 利用此功能，在开发期间于 workerd 中运行 Worker 代码，从而匹配生产环境的行为。

buildApp 钩子（Vite 7）

框架可协调多个环境的构建。配置级形式（最常用）：

export default defineConfig({
  builder: {
    async buildApp(builder) {
      await builder.build(builder.environments.client)
      await builder.build(builder.environments.server)
    },
  },
})

插件钩子形式（适用于插件作者）：

{
  name: 'my-framework',
  buildApp: async (builder) => {
    const environments = Object.values(builder.environments)
    return Promise.all(
      environments.map((env) => builder.build(env))
    )
  },
}

多环境配置

export default defineConfig({
  environments: {
    client: {
      build: { outDir: 'dist/client' },
    },
    server: {
      build: { outDir: 'dist/server' },
    },
  },
})

对于大多数项目，@cloudflare/vite-plugin 或 @tanstack/react-start 会自动处理环境配置。直接使用 Environment API 适用于框架作者。

部署

Cloudflare Workers（通过 TanStack Start）

在插件中添加 cloudflare()，并创建 wrangler.jsonc：

// wrangler.jsonc
{
  "name": "my-app",
  "compatibility_date": "2025-01-01",
  "compatibility_flags": ["nodejs_compat"],
  "main": "./dist/server/index.js",
  "assets": { "directory": "./dist/client" }
}

pnpm vite build && pnpm wrangler deploy

静态 SPA

构建会生成 dist/。可部署到任意静态托管平台（Cloudflare Pages、Vercel、Netlify）。

预渲染（SSG）

tanstackStart({ prerender: { enabled: true, crawlLinks: true } })

最佳实践

1. 插件顺序——先添加框架插件，再添加实用工具，最后添加 react()
2. 使用 rolldown-vite——直接替代原有工具，构建速度快 3-16 倍
3. 在开发环境中设置 staleTime——避免 HMR 重新加载时不必要的重新获取
4. 预热关键文件——对频繁访问的模块使用 server.warmup
5. 拆分 vendor 代码块——将 react、@tanstack/* 拆分到稳定的代码块中，以便缓存
6. 绝不使用 transition-all——CSS 过渡仅指定具体属性
7. 在 ESM 配置文件中使用 import.meta.url 解析路径
8. 定期分析打包结果——部署前使用 rollup-plugin-visualizer
9. 严格遵守 VITE_ 前缀规则——仅用于公开值；密钥应放在服务端函数中
10. 为生产环境设置 build.sourcemap——使用 'hidden' 进行错误跟踪，同时不暴露源代码

Resources

• Vite Docs: https://vite.dev/guide/
• Vite 7 Blog: https://vite.dev/blog/announcing-vite7
• Migration Guide: https://vite.dev/guide/migration
• Build Options: https://vite.dev/config/build-options
• Server Options: https://vite.dev/config/server-options
• Env Variables: https://vite.dev/guide/env-and-mode
• Rolldown-Vite: https://voidzero.dev/posts/announcing-rolldown-vite
• Cloudflare Vite Plugin: https://developers.cloudflare.com/workers/vite-plugin/
• Plugin React: https://github.com/vitejs/vite-plugin-react
• GitHub: https://github.com/vitejs/vite