Vite 8 升级怎么做：Rolldown、Oxc 与 CommonJS 兼容的迁移清单

不少项目把 Vite 从 7 升级到 8 后，最容易碰到的不是依赖装不上的问题，而是构建明明跑通了，某个旧包在页面里直接变成 undefined，或是原先设置好的分包规则悄无声息就失效了。Vite 8 把底层构建链路全面切换到 Rolldown 与 Oxc，升级前先把现有旧配置和少数 CommonJS 依赖梳理标记好，后续排查回归会轻松很多。

先理清这次升级会碰到哪些边界场景

Vite 官方的 v7 迁移说明里已经明确标注：Vite 8 的默认 build.target 对应更新的浏览器基线，依赖预构建流程交给 Rolldown 处理，JavaScript 转换和压缩能力逐步切换到 Oxc 实现。这次升级不是单纯改个版本号就行，反而是个把“旧配置凑合用能跑”改成“新配置可以长期维护”的好机会。

这步不用急着批量改配置。先在 Vite 7 所在分支跑一遍生产构建，保存 dist/ 的体积报告和两三个核心页面的截图。后续迁移出现差异的时候，这组基准数据可比“感觉页面没毛病”靠谱得多。

第一步：在独立分支升级 Vite，保留好可直接对比的构建命令

先新建专属的迁移分支，把升级范围限定在构建工具链本身。要是你很久没整理项目配置了，也可以先只升级 Vite 一个依赖，让自动抛出的报错把那些和构建工具深度耦合的插件、选项都暴露出来。下面的命令只负责安装新版本和跑构建，别把其他不相关的大版本依赖升级混到同一个提交里。

npm install -D vite@^8
npm run build
npm run preview

构建跑通之后，优先打开最容易暴露问题的几类路由：懒加载页面、依赖老旧组件库的页面，还有带动态导入逻辑的页面。浏览器控制台没报错只能说明一半情况，还要额外核对接口请求、首屏样式和一个真实交互流程，比如数据筛选、表单提交或是弹窗关闭这类常规操作。

先把目标浏览器范围明确写出来

Vite 8 调整了默认的浏览器兼容基线。如果你的产品还需要覆盖更老旧的浏览器，别指望默认值会自动帮你保留旧语法，应该由团队在 vite.config.ts 里明确声明目标范围，再用真实设备或是对应浏览器版本做验证。要是项目没有这类历史兼容负担，直接保留默认基线反而能少维护一份冗余配置。

import { defineConfig } from 'vite'

export default defineConfig({
  build: {
    target: 'baseline-widely-available',
  },
})

这种显式声明写法的价值不在于改变默认行为，而是把兼容决策暴露在代码评审环节。后续要是某个客户环境提出特殊兼容要求，要改的配置位置也非常清晰。

第二步：把旧的 esbuild 配置逐项替换成 Rolldown 或 Oxc 的对应语义

Vite 对一部分旧配置项保留了自动转换逻辑，所以升级完的第一天大概率不会马上出问题。不过兼容层已经给出了明确的迁移方向：预构建相关设置逐步迁移到 optimizeDeps.rolldownOptions 体系，代码转换相关设置逐步迁移到 oxc 体系。处理的时候不要机械替换字段名，先想清楚这项配置原本是用来解决什么问题的。

• 之前为了指定扩展名、解析字段或是插件顺序写的预构建配置，优先查阅 Rolldown 官方文档的对应解析能力。
• 之前为了处理 JSX、注入全局变量或是自定义转换范围写的配置项，优先核对 Oxc 的对应语义。
• 如果项目用到的第三方插件调用了 Vite 的旧转换辅助函数，先确认插件是否已经发布兼容新版本，不要自己在项目里把插件代码复制一份硬改。

有个很实用的小方法，可以全局搜索把高风险配置位置都列出来：

rg "esbuildOptions|transformWithEsbuild|manualChunks|commonjsOptions" .
npm run build

搜不到结果不代表升级完全没问题，只能说明最明显的旧配置入口不在当前仓库里。依赖树里的第三方插件仍然可能保留旧的执行逻辑，所以构建完成后的页面回归测试绝对不能省。

第三步：单独验证 CommonJS 包的默认导入逻辑

Vite 8 对 CommonJS 默认导入采用了更统一的处理规则，对绝大多数现代依赖来说是好事，但也可能让一些年代久远的包暴露出 module.exports 与 default 的行为假设差异。典型表现就是构建完全成功，页面第一次调用某个老 SDK 的时候才抛出“不是函数”或是取不到属性的报错。

可以把可疑的依赖放到一段临时开发检查代码里，确认它的值的实际形态，不要只凭 import 语法猜结果：

import legacyClient from 'legacy-client'

console.log({
  kind: typeof legacyClient,
  keys: Object.keys(legacyClient ?? {}),
})

如果确认是模块互操作的差异，优先升级这个依赖包或是改用它官方文档推荐的导入形式。Vite 也提供了临时兼容开关可以恢复旧的行为，不过这个开关只适合做过渡方案，不能当成长期默认配置。把受影响的包名、对应的页面路径和修复方式都记录到迁移文档里，后续清理遗留逻辑的时候会更有依据。

分包规则与插件钩子要核对产物，别只对着配置看

Vite 8 中 build.rollupOptions 会逐步转向 build.rolldownOptions 实现；对象形式声明的 manualChunks 已经不再适配新架构，函数形式的写法也进入了弃用路线。过去靠固定 vendor 包名实现长缓存的项目，升级后可以重新梳理下分包的核心目标：是为了压缩首屏体积、延长静态资源缓存时长，还是为了解决特定的循环依赖问题，目标不一样，对应的替代策略也完全不同。

我更建议把检查拆成两个层面做。第一层先看构建日志和产物清单，确认没有体积异常增大的单个 chunk；第二层打开浏览器网络面板，确认首屏只加载必要的资源。要是底层构建工具替换之后产物体积有小幅波动，先定位到变化的来源，再判断要不要优化，不用为了让数字和旧版本完全一致就直接回滚升级。

回归检查按“构建、运行、产物”三个环节收尾

1. 构建：生产构建和预览模式启动都没有报错；逐一检查插件抛出的警告，看是不是涉及已经弃用的选项。
2. 运行：访问首屏、懒加载路由和引入老旧依赖的页面，至少走一遍完整的核心交互流程。
3. 产物：对比升级前后入口 chunk、公共依赖 chunk 与 CSS 文件的体积，确认没有资源重复打包或是文件缺失的异常。
4. 回退：发布窗口期内保留上一版的构建产物和依赖锁文件，要是线上出现导入类问题可以快速恢复服务。

迁移相关的提交最好只包含构建链路的变更。等所有检查都做完之后，再把后续长期不需要用到的兼容开关和旧配置删掉。这样真出问题的时候，排查范围不会被无关的业务改动干扰。

相关问题

Vite 8 升级后为什么构建通过了页面却报错？

常见原因是 CommonJS 默认导入、插件转换逻辑或是分包结果发生了变化。先从报错路由对应的依赖和 import 写法查起，再对比升级前后的网络请求和控制台输出的信息。

旧的 esbuild 配置可以一直保留吗？

部分设置还能自动兼容转换，但官方已经标注了逐步弃用的方向。等升级稳定之后，还是要按配置原本的用途迁移到 Rolldown 或是 Oxc 的对应能力，减少未来升级的额外成本。

必须立刻改掉所有 manualChunks 配置吗？

对象形式的写法需要优先调整；其余规则也可以等对比完产物差异之后再规划迁移。不要只为了消除控制台警告就随意修改分包逻辑，先想清楚你要实现的缓存和加载目标是什么。

浏览器兼容范围应该在哪里确认？

以产品对外承诺的支持范围和真实用户的使用环境为准。Vite 的默认兼容基线会随版本更新调整，如果团队有明确的兼容要求，要在配置和测试环境里把目标范围明确写出来。

迁移时记住这四件事

Vite 8 的升级核心是把旧的构建习惯重新对齐到 Rolldown 与 Oxc 的新体系：先留存好 Vite 7 的基准数据，再逐项处理配置、插件和 CommonJS 依赖，最后用真实路由和产物对比完成校验。这样升级完留下的是清晰可维护的工程边界，而不是一堆暂时压住警告的临时开关。

Vite 官方迁移说明：Migration from v7；需要继续处理旧版本兼容的话，可以从文档里的 Vite 7 迁移入口逐级核对。