# 投票 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` 之前：插件：[ tanstackStart(), // 或 tanstackRouter() 用于 SPA 尾风CSS(), React(), // 始终在框架插件中排在最后 ] 错误的顺序会导致路由生成失败和 HMR 损坏。 ### Vite 7 仅限 ESM Vite 7 仅作为 ESM 分发。您的“vite.config.ts”必须使用“import”/“export”语法。配置文件中不支持 CJS `require()`。 Node.js 20.19+ 原生支持 `require(esm)`，因此 CJS 消费者仍然可以请求 Vite。 ### 没有 `tailwind.config.js` Tailwind CSS v4 使用 CSS 优先配置。切勿创建 `tailwind.config.js`/`tailwind.config.ts`。使用`@tailwindcss/vite`插件并通过`@theme`，`@utility`，`@plugin`在CSS中配置。 ### 环境变量需要 VITE_ 前缀只有前缀为“VITE_”的变量才会通过“import.meta.env”暴露给客户端代码。仅服务器机密不得使用此前缀。为了类型安全，请在“vite-env.d.ts”中增强“ImportMetaEnv”。 ### splitVendorChunkPlugin 已删除在 Vite 7 中删除。使用 `build.rollupOptions.output.manualChunks` 进行自定义块分割。 ## 配置 ### vite.config.ts（带有 TanStack Start 的完整堆栈）从“vite”导入{defineConfig} 从 '@tanstack/react-start/plugin/vite' 导入 { tanstackStart } 从 '@cloudflare/vite-plugin' 导入 { cloudflare } 从“@tailwindcss/vite”导入 tailwindcss 从“@vitejs/plugin-react”导入反应导出默认的defineConfig({ 插件：[ tanstackStart(), 云耀（），尾风CSS(), 反应（）， ], 解决：{ 别名：{ '@': 新 URL('./src', import.meta.url).pathname, }, }, }) ### vite.config.ts（带有 TanStack 路由器的 SPA）从“vite”导入{defineConfig} 从 '@tanstack/router-plugin/vite' 导入 { tanstackRouter } 从“@tailwindcss/vite”导入 tailwindcss 从“@vitejs/plugin-react”导入反应导出默认的defineConfig({ 插件：[ tanstackRouter({ autoCodeSplitting: true }), 尾风CSS(), 反应（）， ], 解决：{ 别名：{ '@': 新 URL('./src', import.meta.url).pathname, }, }, }) ### React 编译器反应（{ 通天塔：{ 插件：[['babel-plugin-react-compiler', {}]], }, }) 安装：`pnpm add -D babel-plugin-react-compiler`。自动记忆组件和挂钩 - 无需手动“useMemo”/“useCallback”。 ### 路径别名使用“import.meta.url”进行 ESM 兼容解析（ESM 中没有“__dirname”）：解决：{ 别名：{ '@': 新 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`中输入增强：接口 ImportMetaEnv { 只读 VITE_API_URL：字符串 } 接口导入元{ 只读环境：ImportMetaEnv } ## 插件生态系统 ### @vitejs/plugin-react 提供快速刷新（HMR for React）、JSX 转换和可选的 Babel 插件管道。始终将框架插件放在最后。从“@vitejs/plugin-react”导入反应 React() // 零配置默认值 React({ fastRefresh: false }) // 禁用调试 HMR 问题 ### @tailwindcss/vite Tailwind CSS v4 的原生 Vite 集成。替换基于 PostCSS 的设置 - 不需要 `postcss.config.js`。从“@tailwindcss/vite”导入 tailwindcss tailwindcss() // 零配置，从CSS读取@theme ### @tanstack/router-plugin/vite TanStack Router 的基于文件的路由生成。必须出现在`react()`之前。从 '@tanstack/router-plugin/vite' 导入 { tanstackRouter } tanstackRouter({ autoCodeSplitting: true }) ### @tanstack/react-start/plugin/vite TanStack Start 的全栈插件。内部包含路由器插件 - 不要同时添加两者。从 '@tanstack/react-start/plugin/vite' 导入 { tanstackStart } tanstackStart() // 默认 SSR tanstackStart({ spa: {enabled: true } }) // SPA 模式（无 SSR） ### @cloudflare/vite-plugin 在开发期间在“workerd”内运行 Worker 代码，以匹配生产行为。使用Vite的Environment API进行运行时集成。从 '@cloudflare/vite-plugin' 导入 { cloudflare } cloudflare() // 默认读取 wrangler.jsonc // 编程配置（不需要牧马人文件）云耀（{ 配置：{ 名称：'我的工人'，兼容性标志：['nodejs_compat']， }, }) ## 开发服务器 ### 代理配置服务器：{ 代理：{ '/api': { 目标：'http://localhost:8787', 更改来源：true，重写： (path) => path.replace(/^\/api/, ''), }, '/ws': { 目标: 'ws://localhost:8787', ws: true }, }, } ### HMR 故障排除症状|修复 ---|--- 完全重载而不是 HMR |检查“plugin-react”是否已加载 HMR 未连接 |如果位于反向代理后面，则设置 `server.hmr.clientPort` 编辑后的陈旧状态 |组件必须导出单个组件 CSS 未更新 |确保`@tailwindcss/vite`在插件中在反向代理后面：服务器：{ hmr: { 协议: 'ws', 主机: 'localhost', 端口: 5173, clientPort: 443 }, } ### 文件预热服务器：{ 热身：{ clientFiles: ['./src/components/*.tsx', './src/routes/__root.tsx'], }, } ## 构建优化 ### 默认浏览器目标 Vite 7 的目标是“基线广泛可用”（Chrome 107+、Edge 107+、Firefox 104+、Safari 16+）。覆盖：`build.target：'es2020'`或`['chrome90'，'safari14']`。 ### 手动块构建：{ 汇总选项：{ 输出：{ 手动块：{ 'react-vendor': ['react', 'react-dom'], 'tanstack': ['@tanstack/react-router', '@tanstack/react-query'], }, }, }, } 按功能动态拆分：手动块（id）{ if (id.includes('node_modules')) { if (id.includes('react')) 返回 'react-vendor' if (id.includes('@tanstack')) 返回 'tanstack' 返回“供应商” } } ### 捆绑分析 pnpm add -D rollup-plugin-visualizer 从“rollup-plugin-visualizer”导入{可视化工具} // 添加到插件数组可视化工具（{ 文件名：'stats.html'，打开：true，gzipSize：true }）有关详细的分块策略、CSS 分割、资产内联、源映射和性能调整，请参阅 [build-optimization.md]()。 ## 滚动集成 ### 什么是 rolldown-vite `rolldown-vite` 是 Vite 捆绑器的基于 Rust 的直接替代品，由 Vite 团队开发（由 VoidZero 赞助）。它用基于 Rolldown 和 Oxc 工具包构建的单一高性能工具取代了 esbuild 和 Rollup。据报道，大型项目的构建时间减少了 3 至 16 倍，内存使用量减少了多达 100 倍。 Rolldown 将成为 Vite 8（目前处于测试阶段）中的默认捆绑器。今天使用“rolldown-vite”为您的项目过渡做好准备。 **注意：** Vite 7 需要 Vitest 3.2+ 才能兼容。早期的 Vitest 版本将无法工作。 ### 安装在 `package.json` 中，将 `vite` 别名为 `rolldown-vite`： { “开发依赖项”：{ "vite": "npm:rolldown-vite@latest" } } 对于 monorepos 或以 Vite 作为对等依赖项的框架，请使用覆盖： { “pnpm”：{ “覆盖”：{ "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) 框架协调构建多个环境。配置级形式（最常见）：导出默认的defineConfig({ 建造者：{ 异步构建应用程序（构建器）{ 等待 builder.build(builder.environments.client) 等待 builder.build(builder.environments.server) }, }, }) 插件挂钩形式（针对插件作者）： { 名称：'我的框架'， buildApp：异步（构建器）=> { const 环境 = Object.values(builder.environments) 返回 Promise.all( 环境.map((env) => builder.build(env)) ） }, } ### 多环境配置导出默认的defineConfig({ 环境：{ 客户：{ 构建：{ outDir：'dist / client'}， }, 服务器：{ 构建：{ outDir：'dist /服务器'}， }, }, }) 对于大多数项目，“@cloudflare/vite-plugin”或“@tanstack/react-start”会自动处理环境配置。直接环境 API 供框架作者使用。 ## 部署 ### Cloudflare Workers（通过 TanStack Start）将 `cloudflare()` 添加到插件并创建 `wrangler.jsonc`： // 牧马人.jsonc { “名称”：“我的应用程序”， “兼容性日期”：“2025-01-01”， “compatibility_flags”：[“nodejs_compat”]， “主要”：“./dist/server/index.js”， “资产”：{“目录”：“./dist/client”} } pnpm vite 构建 && pnpm Wrangler 部署 ### 静态 SPA 构建生成 `dist/`。部署到任何静态主机（Cloudflare Pages、Vercel、Netlify）。 ### 预渲染 (SSG) tanstackStart({ 预渲染：{ 启用：true，crawlLinks：true } }) ## 最佳实践 1. **插件顺序** \- 首先是框架插件，然后是实用程序，最后是 `react()` 2. **使用 rolldown-vite** \- 直接替换，构建速度提高 3-16 倍 3. **在 dev** 中设置`staleTime` - 避免在 HMR 重新加载期间不必要的重新获取 4. **预热关键文件** \- 对频繁访问的模块使用 `server.warmup` 5. **分割供应商块** \- 将 `react`、`@tanstack/*` 分离成稳定的块以进行缓存 6. **永远不要使用 `transition-all`** \- 仅用于 CSS 转换的特定属性 7. **使用`import.meta.url`**在ESM配置文件中进行路径解析 8. **定期分析捆绑包** \- 在部署之前使用 `rollup-plugin-visualizer` 9. **保留`VITE_`前缀纪律** \-仅公开价值观；秘密存在于服务器功能中 10. **为生产设置`build.sourcemap` ** \- `'hidden'` 用于错误跟踪而不暴露源代码 ## 资源 * **Vite 文档** : * **Vite 7 博客** : * **迁移指南** : * **构建选项** : * **服务器选项** : * **环境变量** : * **Rolldown-Vite** : * **Cloudflare Vite 插件** : * **插件 React** : * **GitHub**：

迅速地

包含技能