如何在package.json中正确指定npm workspace作为项目依赖

核心问题是声明工作区依赖时没有使用npm workspaces要求的workspace:版本协议，直接写语义化版本号会让npm默认去公网registry查找对应包，自然无法匹配本地工作区。

正确配置步骤 #

1. 修改根目录package.json的依赖声明，所有本地工作区包的版本位统一用workspace:前缀，示例配置如下：

   {
     "name": "main-project",
     "version": "1.0.0",
     "workspaces": [
       "packages/*"
     ],
     "dependencies": {
       "workspace-a": "workspace:^",
       // 其余工作区依赖按相同规则声明即可
     }
   }
   

   版本位常用写法说明：
   • workspace:*：直接匹配本地工作区任意版本，本地开发阶段优先用，无需手动对齐各工作区版本号
   • workspace:^：匹配本地工作区符合semver兼容规则的版本，发布时会自动替换为工作区实际声明的版本号
2. 清理旧的安装缓存：删除根目录及各工作区下的node_modules文件夹，删除根目录的package-lock.json，避免旧的拉取记录干扰。
3. 在根目录重新执行npm install即可，npm会自动将本地工作区软链接到根目录node_modules下，不会再发起公网拉取请求。

针对「主项目作为独立外部项目依赖」场景的注意事项 #

npm在执行publish或npm pack操作时，会自动将所有workspace:前缀的版本号替换为对应工作区实际的语义化版本号，外部项目安装发布后的主项目包时，不会感知到workspace配置的存在，会按正常npm依赖逻辑拉取对应版本的子包，无需额外调整配置。

常见踩坑排查点 #

• 确认packages/*目录下每个工作区的package.json中name字段，和根目录依赖里声明的包名完全一致，大小写、拼写错误都会导致npm无法识别本地工作区
• 确认本地npm版本≥7.0.0，workspaces相关能力是npm 7之后才正式支持的，低版本npm无法识别对应配置，可执行npm -v查看版本，版本过低先执行npm install -g npm升级
• 执行安装时不要加--no-workspaces参数，该参数会强制npm忽略工作区配置

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