Yarn portal协议使用异常：本地包仍从npm registry安装

问题描述 #

• 执行yarn add vexflow-repl@portal:../../vexflow-repl时，package.json无变化，包依旧从npm registry拉取，无法使用本地最新代码
• 改用yarn add file:../../vexflow-repl能成功加载本地包，但会产生文件重复和额外开销
• 运行环境：Windows系统

可能原因 #

1. Windows路径格式不兼容：Yarn的portal协议对路径分隔符敏感，正斜杠/在Windows环境下可能未被正确解析
2. Yarn版本bug：部分旧版本Yarn在Windows上处理portal协议时存在路径解析问题
3. 缓存干扰：本地已缓存该包的registry版本，Yarn优先读取缓存而非解析portal路径

解决方案 #

1. 调整路径格式 #

在Windows终端（Cmd/PowerShell）中使用反斜杠路径执行命令：

yarn add vexflow-repl@portal:..\..\vexflow-repl

如果用Git Bash等类Unix终端，保持正斜杠路径即可。

2. 清除缓存后重新安装 #

• 先清除Yarn缓存：

yarn cache clean

• 移除已安装的registry版本：

yarn remove vexflow-repl

• 重新用portal协议安装：

yarn add vexflow-repl@portal:../../vexflow-repl

3. 升级Yarn到最新稳定版 #

旧版本Yarn可能存在Windows下portal协议的兼容性问题，升级后可修复：

yarn set version stable

4. 手动修改package.json #

直接编辑项目的package.json，添加依赖配置：

"dependencies": {
  "vexflow-repl": "portal:../../vexflow-repl"
}

保存后执行yarn install，让Yarn解析该依赖。

补充说明 #

Portal协议通过创建符号链接（Windows下为junction）引用本地包，不会复制文件到node_modules，能避免file协议的冗余问题。如果上述方案仍无效，可检查本地包的package.json是否存在格式错误，确保main或module入口配置正确。

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