为何执行pnpm install后，我的cz-vinyl包被标记为version: link:？

问题背景 #

已发布至NPM的包cz-vinyl（v2.5.0）在自身package.json中声明了对自己的依赖"cz-vinyl": "2.5.0"，且通过exports字段导出了TypeScript类型。但在项目的czvinyl.config.ts中导入类型时，出现错误：

Cannot find module 'cz-vinyl' or its corresponding type declarations.ts(2307)

排查发现pnpm将node_modules/cz-vinyl链接到本地源码而非NPM分发文件，pnpm-lock.yaml中该包版本显示为link:。此问题在Renovate提交依赖更新PR后出现，可通过以下步骤复现：

• 克隆仓库：git clone https://github.com/tal-rofe/cz-vinyl.git
• 按Renovate的修改方式手动调整package.json
• 执行命令：pnpm install --recursive --lockfile-only --ignore-scripts --ignore-pnpmfile
• 查看pnpm-lock.yaml的变更

问题原因 #

pnpm默认存在本地包优先解析机制：当当前仓库package.json的name字段与依赖中的包名完全一致时，pnpm会自动将该依赖解析为本地源码的软链接，而非从NPM仓库拉取已发布的正式版本。

Renovate修改package.json后，触发了pnpm的这一解析逻辑，导致原本应拉取NPM分发产物的依赖被替换为本地源码链接。由于本地源码的文件结构、打包状态通常与NPM分发的产物不一致（比如类型文件未在源码目录中单独输出，或exports配置在开发环境下的行为不同），最终导致TypeScript无法找到对应的类型声明。

解决方法 #

以下几种方案可让pnpm强制使用NPM分发的cz-vinyl包：

1. 明确指定依赖为NPM源 #

直接修改package.json中的依赖声明，在版本前添加npm:前缀，强制pnpm从NPM拉取该版本：

{
  "dependencies": {
    "cz-vinyl": "npm:2.5.0"
  }
}

2. 使用pnpm的packageExtensions配置 #

在项目根目录的package.json中添加pnpm字段，通过packageExtensions强制覆盖依赖解析规则：

{
  "pnpm": {
    "packageExtensions": {
      "cz-vinyl": {
        "dependencies": {
          "cz-vinyl": "npm:2.5.0"
        }
      }
    }
  }
}

3. 禁用全局工作区包链接（单包项目适用） #

在项目的.npmrc文件中添加以下配置，禁用pnpm自动链接工作区包的行为：

link-workspace-packages=false

注意：此配置会全局禁用工作区包链接，不适合monorepo项目，仅推荐单包场景使用。

验证步骤 #

修改配置后，执行以下命令更新锁文件：

pnpm install --recursive --lockfile-only --ignore-scripts --ignore-pnpmfile

查看pnpm-lock.yaml，确认cz-vinyl的版本已从link:变为2.5.0，之后检查czvinyl.config.ts中的类型导入是否恢复正常。

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