本地安装的npm包未创建符号链接，如何解决？

以下是逐步排查和修复方案：

1. 修正npm link的使用步骤 #

你之前的操作最后执行了npm i ./my_modules/mypackage，这会覆盖npm link创建的符号链接，改为复制本地包文件。正确流程应该是：

• 进入本地包目录：cd my_modules/mypackage
• 执行npm link（将本地包注册到全局npm链接库）
• 返回项目根目录：cd ../..
• 执行npm link mypackage（将全局链接的包映射到项目的node_modules）
  完成后检查node_modules/mypackage是否为符号链接，此时无需再执行npm install本地路径的命令。

2. 检查并修改npm配置 #

• 查看prefer-symlink配置（控制npm是否优先创建符号链接）：

  npm config get prefer-symlink
  

• 如果返回false，执行以下命令开启：

  npm config set prefer-symlink true
  

• 检查用户或项目根目录下的.npmrc文件，确保没有symlink=false或package-lock=false这类会干扰链接的配置。

3. 清理缓存与lock文件 #

• 先卸载项目中的本地包：

  npm uninstall mypackage
  

• 删除项目根目录的package-lock.json和node_modules文件夹
• 清理npm缓存：

  npm cache clean --force
  

• 重新按正确的npm link步骤操作，或直接尝试强制链接安装：

  npm install ./my_modules/mypackage --link
  

4. 检查本地包的package.json配置 #

• 确保本地包的package.json中name字段准确为mypackage，与项目依赖中声明的名称一致
• 若本地包设置了"private": true，尝试临时注释该配置后重新链接，部分场景下私有包的链接行为会受限制
• 检查本地包是否有prepare脚本，若该脚本会执行构建操作，可能导致npm自动复制构建产物而非创建链接，可临时注释该脚本测试。

5. 系统权限与文件系统检查 #

• Windows环境：
  • 确保终端以管理员身份运行（创建符号链接需要管理员权限）
  • 确认项目所在磁盘为NTFS格式（FAT32不支持符号链接）
• macOS/Linux环境：
  • 检查项目目录和本地包目录的读写权限，执行：

    chmod -R 755 my_modules/mypackage
    chmod -R 755 ./node_modules
    

  • 确保当前用户拥有创建符号链接的权限（一般默认拥有，特殊权限限制场景需调整）

6. 排除其他工具干扰 #

• 确认未使用yarn、pnpm等其他包管理器，不同工具的本地包处理逻辑不同，保持统一使用npm
• 若使用monorepo工具（如lerna、pnpm workspace），检查其配置是否覆盖了npm的链接行为，需调整对应配置以支持本地包符号链接。

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