正文

升级 Vite 7 时，很多项目不是卡在 React、Vue、Svelte 或 TypeScript，而是卡在一行看似普通的版本报错上：

有些团队更困惑：我已经是 Node 20 了，为什么 20.18 还不行？我已经是 Node 22 了，为什么 22.11 也不行？

答案不只是“Vite 变严格了”。真正原因是：Vite 7 正式进入更彻底的 ESM-only 发布阶段，而它需要 Node.js 对 require(esm) 的无 flag 支持。 Vite 官方在 Vite 7 发布说明中明确写到，Vite 7 现在要求 Node.js 20.19+ 或 22.12+，并且放弃了 Node.js 18，因为 Node 18 已经进入 EOL；同时，这些版本范围能让 Node.js 在不加实验 flag 的情况下支持 require(esm)，从而允许 Vite 7 以 ESM-only 形式发布，但又不阻断 CommonJS 模块通过 Vite JavaScript API 使用它。

You are using Node.js 18.x.x.
Vite requires Node.js version 20.19+ or 22.12+.
Please upgrade your Node.js version.

Vite 7 为什么突然要求 Node 20.19+ / 22.12+？

先说结论：不是所有 Node 20 都能满足 Vite 7，也不是所有 Node 22 都能满足 Vite 7。

Vite 7 的 Node 版本要求是：

Vite 官方仓库的 package.json 中也能看到这个 engines.node 范围。

这意味着：

所以，升级卡住的核心不是“Node 主版本太低”，而是小版本刚好差一点。

{
  "node": "^20.19.0 || >=22.12.0"
}

真正的关键：require(esm) 是什么？

过去 JavaScript 工具链长期存在两套模块系统：

现代前端生态越来越偏向 ESM。Vite 本身也一直是推动 ESM 开发体验的重要工具。但现实问题是：很多旧插件、脚本、配置工具、测试工具，仍然运行在 CommonJS 环境中。

这就带来一个痛点：如果 Vite 只发布 ESM，CommonJS 项目还能不能 require('vite')？

在较旧的 Node.js 中，CommonJS 直接 require() 一个原生 ES Module，经常会遇到类似 ERR_REQUIRE_ESM 的问题。Node 20.19.0 的发布说明指出，require(esm) 在 Node 20.x 中已默认启用，不再需要 --experimental-require-module；启用后，Node.js 使用 require() 加载 ES Module 时不再抛出 ERR_REQUIRE_ESM，但如果被加载的 ES Module 或依赖中包含 top-level await，仍可能抛出 ERR_REQUIRE_ASYNC_MODULE。

Node 22.12.0 也做了同类变化：require(esm) 在 Node 22.x 中不再需要实验 flag，并且 Node 文档说明可以通过 process.features.require_module 检查当前 Node 实例是否支持该能力。

这就是 Vite 7 要求 Node 20.19+ / 22.12+ 的真正原因。

它不是随便卡版本，而是为了确保运行时具备关键模块能力。

// CommonJS
const vite = require('vite')

// ESM
import { createServer } from 'vite'

为什么 Node 20.18 不行？只差 0.01 也不行吗？

是的，不行。

Node 20.19.0 是一个很特殊的小版本。Node 官方说明，虽然 Node 20 当时已经处于维护模式，通常只预期发布 patch，但因为 require(esm) 对生态影响很大，Node 团队特意把这个能力回移到了 20.19.0。

换句话说：

这也是很多人卡住的地方。大家以为“我已经是 Node 20 LTS，应该没问题”，但 Vite 7 看的不是“20”这个大版本，而是20.19.0 这个关键分界线。

Node 20.18.x ❌ 没有默认可用的 require(esm)
Node 20.19.x ✅ 有默认可用的 require(esm)

为什么 Node 22.11 也不行？

原因类似。

Node 22.12.0 的发布说明写明，require(esm) 在该版本中不再需要 --experimental-require-module flag。

所以：

很多部署平台、CI 镜像、旧 Docker 镜像会默认给你 Node 22，但不一定是 22.12+。这时本地能跑，线上构建却失败，或者本地失败、CI 成功，都是很常见的情况。

Node 22.11.x ❌ 低于 Vite 7 要求
Node 22.12.x ✅ 满足 Vite 7 要求

Node 18 为什么被 Vite 7 放弃？

Vite 7 放弃 Node 18，既是技术选择，也是生态周期选择。

Vite 7 迁移指南明确写到：Vite 不再支持已经 EOL 的 Node.js 18，现在要求 Node.js 20.19+ / 22.12+。

Node 官方也说明，当一个 Node 主版本进入 EOL 后，就不再接收更新，包括安全补丁；这会带来安全风险、工具链破损、生态漂移和合规问题。

所以对 Vite 来说，继续支持 Node 18 意味着：

而前端工具链的趋势很明显：新版本工具会更快放弃 EOL Node，转向更新的运行时能力。

• 要继续照顾旧模块系统边界。
• 要保留更多兼容代码。
• 要增加维护成本。
• 要拖慢 ESM-only 生态迁移。

常见报错不一定只有一种

升级 Vite 7 后，常见错误可能包括：

也可能是：

还可能是某些间接依赖先把 Vite 7 拉进来了，导致你明明没主动升级 Vite，却突然安装失败。

这通常发生在：

• 框架升级，例如 React Router、SvelteKit、Astro、Storybook、Vitest 等依赖 Vite 的工具。
• 包管理器更新 lockfile。
• CI 使用了不同 Node 版本。
• Docker 镜像还停在 node:20.18 或 node:22.11。
• 本地终端和 IDE 内置终端使用了不同 Node。

Vite requires Node.js version 20.19+ or 22.12+

error vite@7.x.x: The engine "node" is incompatible with this module.
Expected version "^20.19.0 || >=22.12.0".

升级前先查四个地方

node -v

v20.19.0

v22.12.0

node -v
npm -v
pnpm -v
yarn -v
which node
which npm

Get-Command node
Get-Command npm

- uses: actions/setup-node@v4
  with:
    node-version: 22.12.0

- uses: actions/setup-node@v4
  with:
    node-version: 22

FROM node:20

FROM node:20.18

FROM node:22.12-alpine

FROM node:22-alpine

推荐解决方案：不要只升级本机，要统一全链路

只在自己电脑上执行：

只能解决本地问题，不能解决团队问题。

更完整的做法是把 Node 版本写进项目配置。

nvm install 22
nvm use 22

22.12.0

nvm install
nvm use

22.12.0

{
  "engines": {
    "node": "^20.19.0 || >=22.12.0"
  }
}

engine-strict=true

Vite 7 升级不只是 Node：还要顺手检查这些变化

虽然这篇文章重点讲 Node 版本，但 Vite 7 还有其他升级点。

Vite 7 迁移指南提到，默认浏览器构建目标从旧的 'modules' 改为 'baseline-widely-available'，对应的默认浏览器版本也更新为 Chrome 107、Edge 107、Firefox 104、Safari 16.0。

此外，Vite 7 还移除了 Sass legacy API 支持，并清理了一些废弃特性，例如 splitVendorChunkPlugin、旧的 transformIndexHtml hook 写法等。

所以，升级顺序建议是：

如果你使用 npm：

如果你使用 yarn：

node -v
pnpm why vite
pnpm up vite
pnpm install
pnpm build
pnpm test

npm ls vite
npm install vite@latest
npm run build
npm test

yarn why vite
yarn add vite@latest
yarn build
yarn test

实战排查清单

FAQ：Vite 7 和 Node 版本常见问题

rm -rf node_modules package-lock.json
npm install

rm -rf node_modules pnpm-lock.yaml
pnpm install

结论：Vite 7 卡住，不是版本刁难，而是生态转向 ESM 的信号

《Vite 7 升级卡住：为什么要求 Node 20.19+ / 22.12+》这个问题的核心答案是：Vite 7 要以 ESM-only 方式发布，同时仍要尽量兼容 CommonJS 调用场景，因此它需要 Node.js 默认支持 require(esm)。

Node 20.19 和 Node 22.12 正好是关键分界线。低于这个版本，即使只是差一个小版本，也可能不满足 Vite 7 的底层运行条件。

所以，正确的升级姿势不是只改 vite 版本，而是统一升级整条链路：

把这些地方统一到 Node 22.12+ 或更新 LTS 后，Vite 7 升级通常会顺畅很多。对团队来说，这次升级也不是单纯修一个报错，而是一次把前端工程基础设施拉回现代 ESM 生态的好机会。

本地 Node
包管理器
CI/CD
Docker 镜像
部署平台
团队版本管理文件

参考来源

相关文章