npm依赖软链接损坏表现为ERR_OSSL_EVP_UNSUPPORTED、ENOTDIR、ENOENT或“模块未找到”但实际存在，主因是npm link符号链接断裂、跨盘符/权限失效或package-lock.json路径失效；修复需切断旧链接、清空残留（含package-lock.json和缓存）、重建依赖树，禁用link改用registry安装或npm install ../pkg --no-save临时联调。
npm 依赖软链接损坏通常表现为 ERR_OSSL_EVP_UNSUPPORTED、ENOTDIR、ENOENT，或运行时提示“模块未找到”但 node_modules 中实际存在——这多因 npm link 留下的符号链接断裂、跨盘符/跨用户权限失效，或 package-lock.json 记录的 link 路径已不存在所致。修复核心是**切断旧链接、清空残留、重建可信依赖树**，而非单纯删除再装。
识别并移除失效的 npm link 软链接
软链接问题常隐藏在 node_modules 内部，尤其是本地 link 的包（如 npm link ../my-utils）。直接删除整个 node_modules 可能不够，因为 link 创建的符号链接可能绕过常规安装流程。
- 运行
npm ls -l | grep "link"查看当前项目中所有 link 关系，确认哪些包是通过npm link引入的 - 进入
node_modules目录，用ls -la（macOS/Linux）或dir /a:l（Windows PowerShell）检查可疑目录是否为 broken symlink（目标路径红色高亮或显示broken） - 对每个确认失效的 link 包，手动执行
rm -rf node_modules/包名（不要用npm unlink，它只改 registry 记录，不删文件）
清除 link 相关缓存与 lock 文件
package-lock.json 会记录 link 的绝对路径和完整性哈希；一旦源目录移动或重命名，该记录即失效，且 npm install 默认不会覆盖它。
- 删除
package-lock.json——这是必须步骤，不能跳过 - 运行
npm cache clean --force清理缓存，避免 npm 复用已损坏的 link 元数据 - 检查
npm config get prefix对应的全局node_modules，若曾用npm link全局注册过包，也需进入该目录手动清理对应 link 目录（如node_modules/my-utils → /old/path/my-utils）
重建干净依赖（禁用 link，优先走 registry 安装）
开发阶段使用 npm link 易引发环境不一致，生产构建或 CI 流程中应完全避免。修复后建议切换为更可控的方式。
立即学习“Java免费学习笔记（深入）”；
- 确保
package.json中相关依赖已改为标准版本声明（如"my-utils": "1.2.0"），而非留空或写"file:../my-utils" - 执行
rm -rf node_modules && npm install，让 npm 从 registry 下载真实 tarball 并解压，彻底绕过软链接 - 如确需本地联调，改用
npm install ../my-utils --no-save（临时安装不写入package.json）或yarn link（yarn 对 link 路径处理更鲁棒）
预防软链接损坏的实用习惯
软链接不是 bug，而是设计特性；问题出在误用和缺乏清理机制。
- 避免在 Windows 上跨驱动器使用
npm link（NTFS 符号链接限制多） - 团队协作时，禁用
npm link提交到 Git，改用workspaces或file:协议配合npm pack生成临时 tarball - CI 环境中始终添加
npm config set link false，强制禁用 link 行为 - 定期运行
depcheck --skip-missing，可发现被 link 替代但未在package.json声明的“隐性依赖”
