Vercel部署pnpm项目遇Symlink路径相同错误的排查与解决

错误场景 #

修改仓库名称后，在Vercel部署使用pnpm的项目时，遇到如下错误：

ERROR Symlink path is the same as the target path (/vercel/path0/node_modules/next)

完整部署日志：

Running build in Cleveland, USA (East) – cle1
Cloning github.com/myorg/myrepo (Branch: mybranch, Commit: 8dd529e)
Skipping build cache, deployment was triggered without cache.
Cloning completed: 1.683s
Running "vercel build"
Vercel CLI 31.2.3
Detected `pnpm-lock.yaml` version 6 generated by pnpm 8...
Installing dependencies...
Lockfile is up to date, resolution step is skipped
Progress: resolved 1, reused 0, downloaded 0, added 0
Packages: +1073
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Packages are hard linked from the content-addressable store to the virtual store.
  Content-addressable store is at: /vercel/.local/share/pnpm/store/v3
  Virtual store is at:             node_modules/.pnpm
Progress: resolved 1073, reused 0, downloaded 32, added 32
Progress: resolved 1073, reused 0, downloaded 120, added 119
Progress: resolved 1073, reused 0, downloaded 277, added 277
Progress: resolved 1073, reused 0, downloaded 361, added 360
Progress: resolved 1073, reused 0, downloaded 481, added 477
Progress: resolved 1073, reused 0, downloaded 631, added 628
Progress: resolved 1073, reused 0, downloaded 722, added 717
Progress: resolved 1073, reused 0, downloaded 849, added 847
Progress: resolved 1073, reused 0, downloaded 945, added 943
Progress: resolved 1073, reused 0, downloaded 1024, added 1020
Progress: resolved 1073, reused 0, downloaded 1068, added 1068
Progress: resolved 1073, reused 0, downloaded 1071, added 1070
Progress: resolved 1073, reused 0, downloaded 1072, added 1071
Progress: resolved 1073, reused 0, downloaded 1073, added 1073, done
 ERROR  Symlink path is the same as the target path (/vercel/path0/node_modules/next)
pnpm: Symlink path is the same as the target path (/vercel/path0/node_modules/next)
    at symlinkDir (/pnpm8/node_modules/pnpm/dist/pnpm.cjs:101313:15)
    at symlinkDirectRootDependency (/pnpm8/node_modules/pnpm/dist/pnpm.cjs:135270:58)
    at async /pnpm8/node_modules/pnpm/dist/pnpm.cjs:183785:11
    at async Promise.all (index 76)
    at async linkDirectDepsOfProject (/pnpm8/node_modules/pnpm/dist/pnpm.cjs:183783:7)
    at async Promise.all (index 0)
    at async linkDirectDeps (/pnpm8/node_modules/pnpm/dist/pnpm.cjs:183723:34)
    at async headlessInstall (/pnpm8/node_modules/pnpm/dist/pnpm.cjs:184134:26)
    at async _install (/pnpm8/node_modules/pnpm/dist/pnpm.cjs:190692:33)
    at async mutateModules (/pnpm8/node_modules/pnpm/dist/pnpm.cjs:190559:23)
Error: Command "pnpm install" exited with 1

错误含义 #

该错误说明pnpm在创建符号链接时，试图将/vercel/path0/node_modules/next链接到它自身，这是无效操作，直接导致依赖安装流程终止，部署失败。

产生原因 #

• 仓库名称修改后，本地生成的pnpm-lock.yaml残留了旧的路径关联信息，Vercel部署时解析路径出现冲突
• Vercel部署环境中，pnpm的虚拟存储或内容寻址存储与项目目录的路径映射异常
• package.json中可能重复声明了next依赖，或者lock文件存在循环链接的错误记录
• 本次部署跳过了缓存（日志显示Skipping build cache），pnpm重新安装时路径解析逻辑出错

解决方法 #

1. 重新生成pnpm lock文件 #

在本地项目执行以下命令，彻底重置依赖和lock文件：

rm -rf node_modules pnpm-lock.yaml
pnpm install

将更新后的pnpm-lock.yaml提交到GitHub仓库，重新触发Vercel部署。

2. 调整pnpm链接模式 #

在项目根目录创建或修改.npmrc文件，添加以下配置：

node-linker=hoisted

该配置让pnpm使用hoist模式安装依赖，避免符号链接路径冲突，适配Vercel的部署环境。

3. 清理Vercel部署缓存 #

在Vercel控制台的对应项目页面，点击"Redeploy"，取消勾选"Use existing Build Cache"选项，强制重新安装依赖。若问题依旧，可进入项目设置页面清除全部构建缓存。

4. 检查依赖声明 #

确认package.json中next依赖仅在dependencies或devDependencies中声明一次，没有重复或版本冲突的情况。

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