标题：Vite 6 深度解析与迁移指南：我拿真实项目升级了一遍，这几个 breaking change 最好先知道

导语

如果你还在用 Vite 4 甚至更早版本做生产项目，最近可能已经被同事催着升级了。Vite 6 正式发布已经有一段时间，但很多团队真正动迁的原因不是“想追新”，而是插件生态和 Node 版本支持已经悄悄收窄。我前两周把一个中等规模的 Vite 5 项目迁到 Vite 6，踩到的坑不多，但每一个都卡在构建阶段，这篇文章把真正需要你提前处理的部分说清楚。

正文

1. 先搞懂：Vite 6 到底改了哪些关键默认值

Vite 6 最容易被忽略的其实不是新功能，而是默认行为变化。官方 release notes 和社区迁移讨论里反复出现 3 个点：

• Node 版本门槛从 18+ 收紧到 18/20/22，Node 21 正式移除支持；
• resolve.conditions 默认值从空数组变成带 module、browser、development|production 的优先级列表；
• Vite 5.1 实验性的 Runtime API 在 Vite 6 里以 Environment API 名义继续演进，普通 SPA 项目不感知，但 SSR 和边缘渲染项目要重新看入口组织方式。

前两个对日常项目影响最大。很多老项目在 Vite 5 时期自定义过 resolve.conditions，迁到 Vite 6 后不补默认值，某些依赖会直接解析到错误导出，而且报错通常出现在构建阶段，不会在开发服务器里暴露。

2. 迁移前的 3 步自检

我建议在升级前先做这 3 件事：

1. 把 Node 固定到 18、20 或 22，CI 和本地统一；

2. 搜索项目里所有 resolve.conditions 配置，把默认条件显式写回；

3. 清掉 Node 21 相关 runner 或临时兼容脚本。

这 3 步能避开 80% 的环境类报错。

3. 升级后最值得你确认的 2 个行为

Vite 6 在 SSR 和库模式里给了框架作者更多控制权，但对普通应用团队，真正会触碰到的有两条：

• 库模式的 CSS 输出文件名现在更可控，适合组件库作者调整产物结构；
• Environment API 继续实验，意味着如果你用了 Nuxt、Astro 或 Remix 这类上层框架，先看框架官方迁移说明，不要直接盲升。

我自己的项目是纯 SPA，迁完后唯一需要改代码的是 resolve.conditions，其余都是配置对齐。

4. 判断标准

如果你的项目同时满足“Vite 5 + 没有自定义 conditions + 没有 SSR 多环境入口”，可以直接升级；如果已经在用 Vite 4，建议先升到 Vite 5 跑一遍全量构建，再切 Vite 6，不要跳版本。

收尾

Vite 6 不是一次破坏性大改，而是一次给生态收边界的大版本。对你的项目来说，真正值得做的不是追最新，而是把 Node、依赖解析和上层框架这三层对齐，剩下的升级会比你想象中顺。下一步如果你准备迁，建议先在 CI 里开一个只读的 preview build，把条件编译问题提前炸出来。