部署Next.js应用到Vercel时遇ERR_PNPM_NO_MATCHING_VERSION错误求助

问题根源 #

nextra@2.13.4依赖的@tanstack/react-virtual@3.10.0错误声明了对@tanstack/virtual-core@3.10.0的需求，但该版本并未发布至npm仓库。本地能正常安装是因为pnpm缓存或pnpm-lock.yaml锁定了兼容版本，而Vercel部署时默认重新解析依赖，导致版本匹配失败。

可行修复方案 #

方案1：锁定nextra至无问题的稳定版本 #

将package.json中nextra和nextra-theme-docs的latest改为指定版本（如2.13.3，该版本依赖的@tanstack/react-virtual不会请求未发布的core包）：

{
  "dependencies": {
    "next": "14.2.5",
    "nextra": "2.13.3",
    "nextra-theme-docs": "2.13.3",
    "react": "^18.3.0",
    "react-dom": "^18.3.0"
  }
}

执行pnpm install更新pnpm-lock.yaml后提交代码，重新触发Vercel部署。

方案2：用pnpm overrides强制指定兼容版本 #

在package.json中添加pnpm.overrides字段，强制让@tanstack/react-virtual使用已发布的@tanstack/virtual-core@3.9.0：

{
  "pnpm": {
    "overrides": {
      "@tanstack/react-virtual>@tanstack/virtual-core": "3.9.0"
    }
  },
  "dependencies": {
    // 保留原有依赖配置
  }
}

执行pnpm install更新锁文件后提交部署。

方案3：确保Vercel使用本地pnpm-lock.yaml #

• 确认pnpm-lock.yaml已提交至Git仓库
• 在Vercel部署设置中：
  • 确保Install Command为pnpm install（不要添加--no-lockfile参数）
  • 开启Use Install Cache选项（默认开启，请勿关闭）

这样Vercel会优先使用本地锁文件中锁定的依赖版本，避免重新解析时的版本冲突。

方案4：对齐本地与Vercel的pnpm版本 #

若本地与Vercel使用的pnpm版本不一致，可能导致依赖解析差异：

• 在package.json中添加packageManager字段指定版本：

{
  "packageManager": "pnpm@9.6.0" // 替换为你本地使用的pnpm版本
}

• 或在Vercel项目的Build & Development Settings中，将PNPM Version设置为与本地一致的版本。

内容的提问来源于stack exchange，提问作者Ethan