pnpm重命名项目文件夹后报找不到模块错误如何安全操作

问题原因 #

pnpm 默认生成的虚拟存储目录（virtual store）会和项目所在的绝对路径绑定，第一次重命名文件夹时，pnpm 能检测到路径变动，弹出修改virtual-store-dir配置的提示；如果当时选择了忽略/记住操作，后续pnpm会直接读取缓存中留存的旧路径映射，不再弹出提示，直接返回模块找不到的报错。

安全重命名操作步骤 #

• 先关闭所有占用项目文件的进程，包括正在运行的dev服务、build脚本、代码编辑器中打开的项目终端等，避免文件锁定导致清理失败
• 直接在资源管理器/命令行中重命名项目文件夹到目标名称即可，不需要提前修改任何配置文件
• 清理项目本地旧的依赖关联文件：
  1. 删除项目根目录下的node_modules文件夹，类Unix系统可直接执行命令：rm -rf node_modules；Windows PowerShell可执行：Remove-Item -Recurse -Force node_modules
  2. 检查项目根目录.npmrc文件、package.json的pnpm配置段，如果存在写死旧绝对路径的virtual-store-dir配置，直接删除该配置项即可，推荐使用pnpm默认的相对路径配置，不会随项目移动/重命名失效
• 重新安装依赖：在项目根目录执行pnpm install
• 安装完成后正常执行启动、构建命令即可，不会再出现模块找不到的报错。

避坑提示 #

• 非必要不要手动把virtual-store-dir配置为绝对路径，若要自定义虚拟存储目录，尽量写相对于项目根目录的相对路径，比如设置为virtual-store-dir=.pnpm-virtual-store
• 后续如果需要移动项目文件夹位置，也可以按照上面的流程操作，不会出现依赖异常
• 如果执行完上述步骤仍有报错，可以执行pnpm store prune清理pnpm全局存储中过期的未引用依赖包，再重新执行install即可。

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