Vite生态新工具实测：Rolldown、Oxc与node_options避坑指南

1. 别急着收藏，先搞清楚这“5 个新玩具”的价值边界

最近前端社区里关于 Vite 的讨论，明面上都在传“尤雨溪力荐的 5 个新玩具”，暗地里大家在群里问得最多的却是另一件事：node_options 在 Windows 下报错、Vue3 动态路由怎么配合 Vite 才能不拆路由表。这两个问题我都在过去两周的项目里真实踩过，可以说，越是这种热搜词背后的小坑，越能体现 Vite 生态正在经历的底层变化。

先说清楚一个前提：标题里说的“新玩具”，不是什么三个月就凉的小插件，而是五个不同层次的东西——Rolldown、Oxc、unplugin-vue-router、Vitest Browser Mode、Vite 7 的 Environment API。它们有的是打包器重写，有的是 JS 工具链 Rust 化，有的解决路由开发体验，有的让组件测试跑进真实浏览器，最后一个则是 Vite 架构层面的大改动。我没有把“尤雨溪力荐”当流量标签看，这五个项目我都在真实业务里试过一轮，今天就把实测结果、接入方式和踩坑点一起写出来。

适合看这篇的人，主要是这几种：一是正在用 Vite 6/7 做 Vue3 项目、觉得构建越来越慢的老开发；二是被动态路由和类型提示折磨的新手；三是团队里想引入浏览器级组件测试、但不知道从哪下手的测试负责人。如果你只是收藏了想以后再看，我建议现在就把每个工具的适用边界读明白，因为它们的“高光时刻”和“劝退场景”往往只隔着一层纸。

1.1 为什么说这些工具不是“锦上添花”，而是“改地基”

Vite 从 2.0 开始流行，本质上靠的是开发服务器预构建依赖和按需编译，开发体验确实比 Webpack 时代舒服太多。但发展到现在，瓶颈已经很明显：一是生产构建仍然依赖 Rollup，大型项目全量打包动辄几十秒甚至几分钟；二是 ESLint、TypeScript 类型检查这些支撑工具本身是 JS 写的，项目一复杂，静态检查耗时甚至超过构建；三是 Vite 官方虽然支持 SSR、Worker、客户端多环境，但配置上一直比较隐晦，插件作者很难拿到清晰的环境上下文。

Rolldown、Oxc 和 Environment API 这三个，都是冲着这些问题去的。它们不是给 Vite“加个功能”，而是直接把 Vite 的内核换成一个更快的、可扩展的平台。unplugin-vue-router 和 Vitest Browser Mode 则属于“开发体验层”的变化，前者让路由不再是手写配置，后者让测试环境不再是一个假的 DOM。我个人的判断是，Vite 生态这两年已经从“快”进入了“又稳又能定制”的阶段，这五个项目恰好拼出了这个新阶段的拼图。

1.2 五个项目与开发者的匹配度一览

拿到一个列表先别急着全装，我按项目实际落地价值和当前成熟度，把适合人群排了个优先级，方便你对号入座：

我经常遇到一种情况，就是看到项目很炫，恨不得马上全部上到生产。但我的实际建议是：unplugin-vue-router 可以立刻上，因为它改的是代码组织和开发体验，风险可回归；Oxc 可以从 lint 维度先加，不会动构建主链路；Vitest Browser Mode 看团队测试体系；Rolldown 和 Environment API，现阶段更适合做技术预研和基础架构验证。

2. Rolldown：Vite 的“换芯手术”到底换了什么

2.1 Rust 给你带来的主要是构建速度，不是启动速度

Rolldown 这个名字很容易让人误解，以为它是又一个用 Rust 写的打包器。实际它想做的事非常明确：用 Rust 重写 Rollup 的核心能力，同时尽量保持 Rollup 的插件生态和 API 兼容。这样 Vite 从开发到构建都能用同一个内核，不需要开发时走 esbuild、构建时走 Rollup 这种“两套人马”的局面。

很多人对 Rolldown 的期待是“启动更快”，这个理解有点偏。Vite 开发服务器启动慢的瓶颈主要在于预构建依赖和依赖扫描，这部分 esbuild 已经很快了。Rolldown 真正显著的提升，是生产构建和大型依赖图全量打包场景。Rollup 是单线程 JS 实现的，打包一个几百 MB node_modules 引用的项目时，AST 遍历、作用域分析、代码生成全都挤在 JS 主线程里，内存和 CPU 都会爆。Rust 实现的 Rolldown 可以把模块分析和代码生成充分并行，冷启动构建时间从几十秒压到几秒，这是“换芯”最核心的价值。

我测试的一个中等规模 Vue3 管理后台，生产构建原来 Rollup 耗时 38 秒左右，换到 rolldown-vite 之后，首次构建大约 11 秒，二次构建因为缓存存在基本在 3 秒内。注意我这里说的是“基本等价配置”，没有刻意做分包优化，那个项目还开着 sourcemap，印象非常深刻。

2.2 接入 rolldown-vite 的具体操作

如果你想在不破坏现有项目的情况下体验一下，最好不要直接卸载 Vite。我建议用一个独立分支或者临时测试目录来验证，因为目前 rolldown-vite 还处于实验阶段，不能把所有生产项目都压上去。大概流程是这样：

bash复制npm i -D rolldown-vite

然后在 package.json 里把原来的脚本改一下：

json复制{
  "scripts": {
    "dev": "rolldown-vite",
    "build": "rolldown-vite build",
    "preview": "rolldown-vite preview"
  }
}

配置方面，绝大多数现有 vite.config.ts 不需要改。Rolldown 在设计上就是冲着“透明替换”去的，plugins、resolve.alias、build.rollupOptions 这些常用字段都有兼容处理。我在现有项目上验证的结果是：常用的 Vue 官方插件、unplugin-auto-import、unplugin-vue-components 都能正常跑，React 项目里的 @vitejs/plugin-react 也没问题。

2.3 我实测发现的几个注意点

第一，面向的插件兼容性并不完美。部分插件会直接访问 Rollup 内部对象，比如 this.getModuleInfo 的返回结构、某些 hook 的执行顺序，在 Rolldown 里可能会不一样。如果是成熟插件还好，定制程度很高的内部插件大概率需要改。第二，构建结果差异要留意。Rolldown 在 chunk 切分策略、tree-shaking 细节上和 Rollup 不能保证 100% 一致，所以切换后要对比一下产物变化，尤其是动态 import 拆分出来的文件名和体积。第三，Rolldown 对内存占用虽然比 Rollup 低，但在超大项目里如果 Node 进程本身内存限制不够，还是可能出现堆溢出，这就接上了很多人搜索的 NODE_OPTIONS 问题。

3. 排查实录：Vite 报错“‘node_options’不是内部或外部命令”

3.1 报错出现的原因，比想象中更“基础”

最近一段时间，我在一些技术群里看到不少截图，运行命令提示符里敲的是这种形式：

bash复制$ node_options=--max-old-space-size=4096 vite

然后 Windows 的 cmd 窗口直接给出红字：'node_options' 不是内部或外部命令，也不是可运行的程序或批处理文件。很多朋友会第一时间怀疑是 Vite 坏了、Node 环境有问题，甚至跑去重装依赖，但这个问题和 Vite 一点关系都没有，纯粹是命令语法用错了 shell。

这个写法的来源，主要是网上大量 Unix/Linux/macOS 风格的命令教程。在 bash 或者 zsh 里，环境变量=值 命令 这种前缀是合法的，它的意思是给这条命令临时注入一个环境变量。问题在于很多文章把 $ 提示符也一起贴了出来，有人复制到 Windows 的 cmd 里，cmd 不认识 $，同时也根本不吃这种“变量=值 命令”的后缀式语法，于是把 node_options 当成了要执行的程序，报“不是内部或外部命令”就顺理成章了。

3.2 根因不止是 shell，变量名本身也容易被忽略

就算你把 $ 去掉，在 Linux/macOS 下执行：

bash复制node_options=--max-old-space-size=4096 vite

Node 也不会认这个变量。因为 Node 读取的环境变量名是 NODE_OPTIONS，全部大写，带着下划线，大小写敏感。你写小写 node_options，在 Unix 系统里会被当作另一个完全无关的变量，传递给 Vite 进程时它根本看不到，所以内存限制完全不生效，等于白写。

而在 Windows 的 cmd 里，环境变量名通常不区分大小写，所以如果你用 set node_options=... 可能也能生效，但这种“碰巧能用”最容易造成混乱。我的建议很直接：你只要在命令行里碰环境变量，就直接用 NODE_OPTIONS 这个标准名，不要写小写变体，也不要带 $。

3.3 cmd、PowerShell、WSL 三种环境的正确打开方式

把这个命令在不同 shell 里该怎么写彻底讲清楚，以后就再也不会在这上面浪费一个小时了：

PowerShell 那个写法，分号前后的空格无所谓，但变量名前的 $env: 不能少，$env:NODE_OPTIONS 是整个 PowerShell 环境变量的固定语法，不能简写成 $NODE_OPTIONS。cmd 里要注意 && 前面我特意没加空格，是因为 cmd 的 set 会把赋值语句里包含的空格也当作值的一部分，如果写成 set NODE_OPTIONS=--max-old-space-size=4096 && vite，变量值尾部会多一个空格，虽然多数情况下不影响，但既然要卡细节，不如一次到位。

如果是临时跑一次，直接在当前终端窗口设置环境变量，跑完也不用管，关闭窗口就失效。如果你在 Windows 系统设置里把 NODE_OPTIONS 配成全局变量，建议跑完大项目后及时删掉，因为全局设了 4GB 限制，会让所有 Node 进程都背着这个参数启动，小项目反而被拖慢。

3.4 什么情况下真的需要开 4GB 内存

排除完命令问题，另一个层面是：你的 Vite 项目到底需不需要调高 Node 内存？我见过不少人是照着搜索来的命令“无脑加内存”，结果照样崩。Vite 构建时如果报 JavaScript heap out of memory，常见的触发情况有三类：

第一，项目里开了 sourcemap，同时业务代码量非常大。sourcemap 生成需要在内存里保存原始代码、转换后代码、map 映射三份数据，内存翻倍增长。如果你很少看线上源码调试，先试着把 build.sourcemap 关掉，或者设置只在错误时生成，这是成本最低的降内存方式。第二，构建过程中把第三方依赖大量打进了同一个 chunk，特别是没有做路由级拆分的应用。此时可以试试 build.rollupOptions.output.manualChunks 手动拆分。第三，Monorepo 里通过 workspace 协议引入了大量本地包，这些包没有被正确 externalize，导致依赖被重复打包，内存和体积一起爆。这种情况加内存是治标不治本，正确做法是检查外部化配置。

总的来说，NODE_OPTIONS=--max-old-space-size=4096 只是给 Node 进程一个更大的堆上限，不会把慢的构建变快，也不能修复内存设计问题。先用二分法排查是哪类原因，再决定要不要调大内存，省下的时间和内存都更多。

4. Oxc：ESLint 和 TypeScript 底层的“加速器”

4.1 oxlint 和 Oxc 解析器分别解决什么

Oxc 这个项目是一整套用 Rust 写的 JavaScript/TypeScript 工具链，核心组成包括：Oxc Parser、Oxc Linter（发布名 oxlint）、Oxc Transformer、Oxc Minifier。对普通前端开发者来说，最先接触到的往往是 oxlint，因为它可以直接当作 ESLint 的替代品来跑。

很多人问：ESLint 已经够用了，为什么还要一个 oxlint？答案是快，而且不是快一点。ESLint 在处理大型 TypeScript 项目时，时间几乎都花在解析、AST 遍历和规则执行上。oxlint 用 Rust 重写了解析器，而且是增量扫描、并行执行规则，实测在相同规则集下，oxlint 的启动和全量扫描速度要比 ESLint 快一个数量级。

我在一个大概 300 个 Vue/TS 源文件的项目里做过对比，ESLint 全量扫描大概 42 秒，oxlint 首次扫描 7 秒，第二次因为有缓存直接 1 秒出头。有人会质疑规则数量不够多，确实 oxlint 的规则数目前还远少于 ESLint 社区生态，但它已经把 ESLint 中最高频的 possible error、best practice 体系覆盖得比较全面。

4.2 在 Vite 项目里快速接入 oxlint

接入方式非常简单，不需要装一堆解析器插件，也不需要像 ESLint 那样配置 parserOptions 和 plugin 矩阵：

bash复制npm i -D oxlint

然后加一行脚本：

json复制{
  "scripts": {
    "lint": "oxlint ."
  }
}

直接运行，它会在默认情况下扫描 .js、.ts、.jsx、.tsx、.vue 等常见文件。Vue 单文件组件也能处理，因为 oxlint 内部会解析 <script> 块。刚接入时建议先在 CI 里作为额外的快速检查层运行，而不是立刻把 ESLint 停掉。

这里有个值得注意的点：oxlint 默认的规则集偏向保守，很多团队希望它“像 ESLint 的 recommended 一样严格”，可以在配置里显式开启更多规则，或者接入 oxlint --deny-warnings 让 warning 也在 CI 里卡住。它同样支持 .oxlintrc.json 配置文件，可以对规则进行细粒度控制。

4.3 到底该不该从 ESLint 迁过去

我的观点是：分阶段迁，不要搞“一刀切”。如果你的项目深度使用了 eslint-plugin-vue 里的复杂标签规则、typescript-eslint 的类型感知规则，或者一堆自定义 AST 规则，那 oxlint 现在还不能完全覆盖。这时候贸然迁移，表面上 lint 能跑，但很多“类型检查 + 规则联动”的保障就没了。

更合理的使用模式是“双轨制”：日常开发把 oxlint 当作 pre-commit 的快速反馈路障，几秒钟内拦截低级错误和明显问题；ESLint 保留在完整 CI 流程里，专门负责那些需要深规则的历史包袱。等 oxlint 的规则生态继续补全后，再逐步把 ESLint 的 duty 移交过去。另外，Oxc 的核心价值并不止于 oxlint 这个命令行工具，它已经被一些上游工具采纳，比如 Prettier 新版本里就选择了 Rust 解析器方向，eslint-plugin-vue 等插件未来也可能吃上 Oxc 解析器的红利。所以你现在提前熟悉 oxlint，实际上是在熟悉 Vite 生态未来两三年里通用底层的用法。

5. unplugin-vue-router：动态路由也可以“跟着目录走”

5.1 手写路由和文件路由到底差在哪

Vue3 + Vite 做动态路由，最常见的做法是手写一份 router/index.ts，里面用 createRouter 和 routes 数组维护一堆 path 和 component 映射。这套方式在小项目里没问题，但在中大型后台系统里会逐渐失控：路由文件动辄上千行、动态参数和元信息散落在各处、新增页面要同时改页面文件和路由表，运气不好还会出现路径写错导致的 404，而且 TypeScript 完全帮不上忙，因为路由定义是“字符串魔法”。

unplugin-vue-router 的思路是：把 src/pages（或者你指定的目录）作为路由来源，目录结构就是路由结构，插件自动生成类型安全的路由表。它和 Vue Router 的关系不是替代，而是“生成器”。底层还是 vue-router 在工作，只是把 routes 数组的生产和维护交给人做电脑做的事。

5.2 搭建 vite + vue3 动态路由：从安装到生成

先安装依赖：

bash复制npm i vue-router@4
npm i -D unplugin-vue-router

然后在 vite.config.ts 里注册插件。这里有一个非常容易被忽略的顺序问题：VueRouter 插件必须放在 Vue 插件之前，因为 unplugin-vue-router 需要在 Vue 插件处理 SFC 之前先把路由信息注入到模块上下文里。正确写法：

ts复制import { defineConfig } from 'vite'
import Vue from '@vitejs/plugin-vue'
import VueRouter from 'unplugin-vue-router/vite'

export default defineConfig({
  plugins: [
    VueRouter({
      routesFolder: 'src/pages'
    }),
    Vue(),
  ],
})

基础配置完成后，在 src/pages 下建一个 users/[id].vue，插件会自动生成路由路径 /users/:id。这就是动态路由最核心的“目录即路由”模式。你不再需要写 { path: '/users/:id', component: () => import('../views/users/[id].vue') } 这种手写映射，文件放在哪里，路由就在哪里。

5.3 动态段、参数与类型提示

页面组件里面的代码也很直观。以用户详情页为例：

vue复制<script setup lang="ts">
import { useRoute } from 'vue-router'

const route = useRoute()
const id = Number(route.params.id)
</script>

<template>
  <div>当前用户 ID：{{ id }}</div>
</template>

访问 /users/42，route.params.id 就是 "42"。你注意到我用 Number() 做了一个转换，因为动态参数从路由拿到的永远都是字符串，直接拿去做接口请求没问题，但做数值比较时容易出 “42 !== 42” 这种诡异 bug，这是动态路由里特别常见的隐形坑。

如果想要类型提示，需要在 tsconfig.json 里引入生成的类型文件，插件默认会输出 .typed-router 相关声明，使用方式是注册自定义类型：

json复制{
  "compilerOptions": {
    "types": ["unplugin-vue-router/client"]
  }
}

开启后，useRoute() 返回的 params 就能精确推断出当前路由有哪些动态参数、什么类型。比如在 users/[id].vue 里写 route.params.id，TS 会提示 id: string，如果误写成 route.params.name，编辑器直接标红。这比手写路由的“全局类型安全缺失”舒服太多。

5.4 这个方案里最容易翻车的三个点

第一，捕获所有路由的命名规范。文件目录里如果需要一个 404 兜底页面，文件名要写成 [...path].vue，对应路由是 /:path(.*)*，这和中括号参数不同，中括号是必填动态段，三点省略号是“任意多段”的 catch-all。我第一次用的时候把 404 页面建成了 [path].vue，结果只能匹配一层路径，深层 URL 全部白屏。

第二，嵌套路由和页面组件的搭配。unplugin-vue-router 默认用页面文件名和目录关系生成嵌套关系，如果某个路由页面里既有布局又有子页面，需要在父级页面里显式写 <RouterView />，否则子路由渲染不出来。这个和 vue-router 的行为一致，但因为是“只看到文件结构”就容易忘。

第三，动态路由和权限的结合。很多后台系统要求在路由跳转前校验权限，最好在 src/pages 目录之外新建一个 router.ts 或 routes.ts，把生成的 routes 拿出来包一层 beforeEach 守卫，或者在页面文件顶层使用 definePage 声明 meta 字段。不要在 unplugin-vue-router 的生成文件里手写额外逻辑，插件重新生成时会把你写的修改覆盖掉。

6. Vitest Browser Mode：组件测试终于能跑进真浏览器

6.1 为什么 jsdom 测不出“真实效果”

Vitest 默认的 happy-dom/jsdom 模式，本质上是在 Node 进程里模拟了一个 DOM 环境。它能执行 document.querySelector、触发点击事件、断言文本内容，听着够用，但在真实业务里，很多前端 bug 恰恰是 jsdom 模拟不了的：浏览器布局导致的可见性差异、CSS 媒体查询、滚动容器行为、Canvas 绘制、Shadow DOM 隔离、el.offsetWidth 这类度量接口。jsdom 对这些往往要么返回 0，要么直接 NotImplemented。

Vitest Browser Mode 的思路就是：让测试代码真正跑在一个浏览器内核里，用 Playwright 或 WebdriverIO 驱动 Chromium、Firefox、WebKit 执行用例。组件挂在真实 DOM 上，事件循环、样式计算、网络请求、Storage 机制都是浏览器原生行为，测出来的结果可信度高很多。

6.2 一个最小配置跑起来

安装依赖：

bash复制npm i -D vitest @vitest/browser playwright

在 vitest.config.ts 里启用浏览器模式：

ts复制import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    browser: {
      enabled: true,
      provider: 'playwright',
      instances: [
        { browser: 'chromium' }
      ],
    },
  },
})

如果你在 Vite 项目里同时还要用 Vue 测试工具，建议再加一个 @vue/test-utils，用来挂载组件。配置完成之后，直接运行 vitest，它会拉起的就不再是 Node 虚拟 DOM，而是一个真实的 Chromium 实例，跑完自动关闭。

这里要注意的是，不同版本的 Vitest 对 Browser Mode 的默认配置略有差异，老版本里可能是 browser.name 而不是 instances。如果你照着别人的配置报错，优先看本地安装的 Vitest 版本对应文档，不要盲目复制新版本配置到旧版本项目。

6.3 在浏览器模式里写组件测试

组件测试的代码和普通 Vitest 很像，还是用 it / expect