Pnpm依赖路径过深超出Windows长度限制

前言
本文讨论的均是在Windows开发环境下出现的问题和处理方案

问题背景与现象描述#

NOTE
问题描述：在Windows系统下进行前端项目开发时，node_modules中依赖路径过长导致模块解析失败。该问题在使用Pnpm或深层依赖的TypeScript项目中尤为突出。由于Pnpm通过符号链接(Symlink)实现扁平化依赖管理，但其内部仍可能生成深层嵌套结构，尤其在跨包引用或版本冲突时，极易触发路径长度限制。
根本原因：
Windows MAX_PATH 限制：Windows传统API对文件路径限制为260字符（MAX_PATH），超出则无法访问
Node.js 模块解析机制：Node.js递归查找node_modules目录，路径越深，拼接后越容易超限
pnpm 的硬链接与嵌套结构：尽管pnpm优化了存储，但在某些场景下仍会创建深层嵌套（如peer dependency不兼容时）
TypeScript 编译器行为：TS编译期间需解析所有类型定义文件，频繁访问深层路径，加剧问题暴露概率

解决方案#

1. 缩短项目根路径#

终止当前Pnpm i命令，删除项目下的冗余文件：

# 删除依赖目录和锁文件
rm -rf node_modules pnpm-lock.yaml
# 若有pnpm本地缓存，也可删除
rm -rf .pnpm-store

缩短项目根路径后重新执行pnpm i

2. 启动Windows长路径支持(系统层面解除限制)#

PowerShell命令(管理员权限)，执行以下命令，修改注册表：

New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force

重启电脑，重新执行pnpm i

3. 添加pnpm配置#

编辑项目的.pnpmrc文件，没有则新建，添加如下配置：

# 1. 禁用符号链接，改用硬链接（避免路径拼接问题）
symlink=false
# 2. 强制使用隔离模式，减少嵌套层级
node-linker=isolated

删除旧的node_modules和lock文件，重新执行Pnpm i