跳至主要内容
版本: 9.x

package.json

包的清单文件。它包含所有包的元数据，包括依赖项、标题、作者等。这是所有主要 Node.JS 包管理器（包括 pnpm）之间保留的标准。

engines​

您可以指定您的软件运行的 Node 和 pnpm 版本

{
    "engines": {
        "node": ">=10",
        "pnpm": ">=3"
    }
}

在本地开发期间，如果 pnpm 的版本与 engines 字段中指定的版本不匹配，pnpm 将始终以错误消息失败。

除非用户设置了 engine-strict 配置标志（参见 .npmrc），否则此字段仅为建议性，并且仅在您的包作为依赖项安装时才会产生警告。

dependenciesMeta​

用于在 dependencies、optionalDependencies 和 devDependencies 中声明的依赖项的附加元信息。

dependenciesMeta.*.injected​

如果对于本地依赖项将其设置为 true，则该包将被硬链接到虚拟存储（node_modules/.pnpm）并从虚拟存储符号链接到模块目录。

如果对于本地依赖项将其设置为 false 或未设置，则该包将直接从其在工作区中的位置符号链接到模块目录。

例如，以下工作区中的 package.json 将在 card 的 node_modules 目录中创建一个指向 button 的符号链接

{
  "name": "card",
  "dependencies": {
    "button": "workspace:1.0.0"
  }
}

但是，如果 button 在其对等依赖项中具有 react？如果单仓库中所有项目都使用相同版本的 react，则没问题。但是，如果 button 被使用 react@16 的 card 和使用 react@17 的 form 要求？如果不使用 inject，您将不得不选择一个 react 的单一版本并将其作为 button 的开发依赖项安装。但是，使用 injected 字段，您可以将 button 注入到一个包中，并且 button 将与该包的 react 版本一起安装。

因此，这将是 card 的 package.json

{
  "name": "card",
  "dependencies": {
    "button": "workspace:1.0.0",
    "react": "16"
  },
  "dependenciesMeta": {
    "button": {
      "injected": true
    }
  }
}

button 将被硬链接到 card 的依赖项中，并且 react@16 将被符号链接到 card/node_modules/button 的依赖项中。

这将是 form 的 package.json

{
  "name": "form",
  "dependencies": {
    "button": "workspace:1.0.0",
    "react": "17"
  },
  "dependenciesMeta": {
    "button": {
      "injected": true
    }
  }
}

button 将被硬链接到 form 的依赖项中，并且 react@17 将被符号链接到 form/node_modules/button 的依赖项中。

与普通依赖项相比，注入的依赖项不会符号链接到目标文件夹，因此它们不会自动更新，例如在运行构建脚本后。要将硬链接文件夹内容更新到依赖项包文件夹的最新状态，请再次调用 pnpm i。

请注意，button 包必须具有在安装时运行的任何生命周期脚本，以便 pnpm 检测更改并更新它。例如，该包可以在安装时重建："prepare": "pnpm run build"。任何脚本都可以，即使是没有任何副作用的简单无关命令，例如："prepare": "pnpm root"。

peerDependenciesMeta​

此字段列出与 peerDependencies 字段中列出的依赖项相关的某些额外信息。

peerDependenciesMeta.*.optional​

如果将其设置为 true，则选定的对等依赖项将被包管理器标记为可选。因此，省略它的使用者将不再被报告为错误。

例如

{
    "peerDependencies": {
        "foo": "1"
    },
    "peerDependenciesMeta": {
        "foo": {
            "optional": true
        },
        "bar": {
            "optional": true
        }
    }
}

请注意，即使 bar 未在 peerDependencies 中指定，它也被标记为可选。因此，pnpm 将假设任何版本的 bar 都可以。但是，foo 是可选的，但仅限于所需的版本规范。

publishConfig​

可以在打包之前覆盖清单中的某些字段。以下字段可能会被覆盖

要覆盖字段，请将字段的发布版本添加到 publishConfig 中。

例如，以下 package.json

{
    "name": "foo",
    "version": "1.0.0",
    "main": "src/index.ts",
    "publishConfig": {
        "main": "lib/index.js",
        "typings": "lib/index.d.ts"
    }
}

将发布为

{
    "name": "foo",
    "version": "1.0.0",
    "main": "lib/index.js",
    "typings": "lib/index.d.ts"
}

publishConfig.executableFiles​

默认情况下，出于可移植性原因，除了 bin 字段中列出的文件外，其他任何文件都不会在生成的包存档中标记为可执行文件。executableFiles 字段允许您声明必须设置可执行标志 (+x) 的其他字段，即使它们不能通过 bin 字段直接访问。

{
  "publishConfig": {
    "executableFiles": [
      "./dist/shim.js"
    ]
  }
}

publishConfig.directory​

您还可以使用 publishConfig.directory 字段来定制相对于当前 package.json 的发布子目录。

预计在指定的目录中有一个当前包的修改版本（通常使用第三方构建工具）。

在此示例中，"dist" 文件夹必须包含一个 package.json

{
  "name": "foo",
  "version": "1.0.0",
  "publishConfig": {
    "directory": "dist"
  }
}

publishConfig.linkDirectory​

  • 默认值：true
  • 类型：布尔值

当设置为 true 时，该项目将在本地开发期间从 publishConfig.directory 位置符号链接。

例如

{
  "name": "foo",
  "version": "1.0.0",
  "publishConfig": {
    "directory": "dist"
    "linkDirectory": true
  }
}

pnpm.overrides​

此字段允许您指示 pnpm 覆盖依赖项图中的任何依赖项。这对于强制所有包使用单个版本的依赖项、回溯修复或用 fork 替换依赖项很有用。

请注意，overrides 字段只能在项目的根目录中设置。

"pnpm"."overrides" 字段的示例

{
  "pnpm": {
    "overrides": {
      "foo": "^1.0.0",
      "quux": "npm:@myorg/quux@^1.0.0",
      "bar@^2.1.0": "3.0.0",
      "qar@1>zoo": "2"
    }
  }
}

您可以通过用“>”分隔包选择器和依赖项选择器来指定被覆盖依赖项所属的包，例如 qar@1>zoo 将仅覆盖 qar@1 的 zoo 依赖项，而不是任何其他依赖项。

覆盖可以定义为对直接依赖项规范的引用。这是通过在依赖项名称前添加 $ 来实现的

{
  "dependencies": {
    "foo": "^1.0.0"
  },
  "pnpm": {
    "overrides": {
      "foo": "$foo"
    }
  }
}

引用的包不需要与被覆盖的包匹配

{
  "dependencies": {
    "foo": "^1.0.0"
  },
  "pnpm": {
    "overrides": {
      "bar": "$foo"
    }
  }
}

pnpm.packageExtensions​

packageExtensions 字段提供了一种方法，可以使用附加信息扩展现有的包定义。例如，如果 react-redux 应该在 peerDependencies 中具有 react-dom 但没有，则可以使用 packageExtensions 修补 react-redux

{
  "pnpm": {
    "packageExtensions": {
      "react-redux": {
        "peerDependencies": {
          "react-dom": "*"
        }
      }
    }
  }
}

packageExtensions 中的键是包名称或包名称和语义版本范围，因此可以仅修补包的某些版本

{
  "pnpm": {
    "packageExtensions": {
      "react-redux@1": {
        "peerDependencies": {
          "react-dom": "*"
        }
      }
    }
  }
}

可以使用 packageExtensions 扩展以下字段：dependencies、optionalDependencies、peerDependencies 和 peerDependenciesMeta。

一个更大的例子

{
  "pnpm": {
    "packageExtensions": {
      "express@1": {
        "optionalDependencies": {
          "typescript": "2"
        }
      },
      "fork-ts-checker-webpack-plugin": {
        "dependencies": {
          "@babel/core": "1"
        },
        "peerDependencies": {
          "eslint": ">= 6"
        },
        "peerDependenciesMeta": {
          "eslint": {
            "optional": true
          }
        }
      }
    }
  }
}
提示

与 Yarn 一起，我们维护一个 packageExtensions 数据库，用于修补生态系统中损坏的包。如果您使用 packageExtensions，请考虑向 upstream 发送 PR 并将您的扩展贡献给 @yarnpkg/extensions 数据库。

pnpm.peerDependencyRules​

pnpm.peerDependencyRules.ignoreMissing​

pnpm 不会打印有关此列表中缺少的对等依赖项的警告。

例如，使用以下配置，如果依赖项需要 react 但未安装 react，pnpm 不会打印警告

{
  "pnpm": {
    "peerDependencyRules": {
      "ignoreMissing": ["react"]
    }
  }
}

也可以使用包名称模式

{
  "pnpm": {
    "peerDependencyRules": {
      "ignoreMissing": ["@babel/*", "@eslint/*"]
    }
  }
}

pnpm.peerDependencyRules.allowedVersions​

对于指定范围的对等依赖项，不会打印未满足的对等依赖项警告。

例如，如果您有一些依赖项需要 react@16，但您知道它们与 react@17 一起工作正常，那么您可以使用以下配置

{
  "pnpm": {
    "peerDependencyRules": {
      "allowedVersions": {
        "react": "17"
      }
    }
  }
}

这将告诉 pnpm 任何在对等依赖项中具有 react 的依赖项都应该允许安装 react v17。

也可以仅针对特定包的对等依赖项抑制警告。例如，使用以下配置，react v17 仅在 button v2 包的对等依赖项中或任何 card 包的依赖项中时才允许

{
  "pnpm": {
    "peerDependencyRules": {
      "allowedVersions": {
        "button@2>react": "17",
        "card>react": "17"
      }
    }
  }
}

pnpm.peerDependencyRules.allowAny​

allowAny 是一个包名称模式数组，任何与该模式匹配的对等依赖项都将从任何版本解析，而不管 peerDependencies 中指定的范围如何。例如

{
  "pnpm": {
    "peerDependencyRules": {
      "allowAny": ["@babel/*", "eslint"]
    }
  }
}

上述设置将静音任何与 @babel/ 包或 eslint 相关的对等依赖项版本不匹配的警告。

pnpm.neverBuiltDependencies​

此字段允许忽略特定依赖项的构建。在安装期间，不会执行列出包的“preinstall”、“install”和“postinstall”脚本。

"pnpm"."neverBuiltDependencies" 字段的示例

{
  "pnpm": {
    "neverBuiltDependencies": ["fsevents", "level"]
  }
}

pnpm.onlyBuiltDependencies​

允许在安装过程中执行的包名称列表。如果存在此字段，则只有列出的包才能运行安装脚本。

示例

{
  "pnpm": {
    "onlyBuiltDependencies": ["fsevents"]
  }
}

pnpm.onlyBuiltDependenciesFile​

此配置选项允许用户指定一个 JSON 文件，该文件列出了在 pnpm install 过程中允许运行安装脚本的唯一包。通过使用此选项，您可以增强安全性或确保只有特定依赖项在安装过程中执行脚本。

示例

{
  "dependencies": {
    "@my-org/policy": "1.0.0"
  },
  "pnpm": {
    "onlyBuiltDependenciesFile": "node_modules/@my-org/policy/onlyBuiltDependencies.json"
  }
}

JSON 文件本身应该包含一个包名称数组

node_modules/@my-org/policy/onlyBuiltDependencies.json
[
  "fsevents"
]

pnpm.allowedDeprecatedVersions​

此设置允许静默特定包的弃用警告。

示例

{
  "pnpm": {
    "allowedDeprecatedVersions": {
      "express": "1",
      "request": "*"
    }
  }
}

使用上述配置，pnpm 将不会打印有关任何版本的 request 和 v1 版本的 express 的弃用警告。

pnpm.patchedDependencies​

当您运行 pnpm patch-commit 时，此字段会自动添加/更新。它是一个字典，其中键应该是包名称和确切版本。值应该是补丁文件的相对路径。

示例

{
  "pnpm": {
    "patchedDependencies": {
      "[email protected]": "patches/[email protected]"
    }
  }
}

pnpm.allowNonAppliedPatches​

当设置为 true 时，如果 patchedDependencies 字段中的一些补丁未应用，安装将不会失败。

{
  "pnpm": {
    "patchedDependencies": {
      "[email protected]": "patches/[email protected]"
    },
    "allowNonAppliedPatches": true
}

pnpm.updateConfig​

pnpm.updateConfig.ignoreDependencies​

有时您无法更新依赖项。例如，依赖项的最新版本开始使用 ESM，但您的项目尚未使用 ESM。令人讨厌的是，这样的包将始终由 pnpm outdated 命令打印出来并更新，当运行 pnpm update --latest 时。但是，您可以在 ignoreDependencies 字段中列出您不想升级的包

{
  "pnpm": {
    "updateConfig": {
      "ignoreDependencies": ["load-json-file"]
    }
  }
}

也支持模式，因此您可以忽略来自范围的任何包：@babel/*。

pnpm.auditConfig​

pnpm.auditConfig.ignoreCves​

由 pnpm audit 命令忽略的 CVE ID 列表。

{
  "pnpm": {
    "auditConfig": {
      "ignoreCves": [
        "CVE-2022-36313"
      ]
    }
  }
}

pnpm.requiredScripts​

在此数组中列出的脚本将在工作区中的每个项目中都需要。否则，pnpm -r run <script name> 将失败。

{
  "pnpm": {
    "requiredScripts": ["build"]
  }
}

pnpm.supportedArchitectures​

您可以指定要为其安装可选依赖项的体系结构，即使它们与运行安装的系统的体系结构不匹配。

例如，以下配置指示为 Windows x64 安装可选依赖项

{
  "pnpm": {
    "supportedArchitectures": {
      "os": ["win32"],
      "cpu": ["x64"]
    }
  }
}

而此配置将为 Windows、macOS 和当前运行安装的系统的体系结构安装可选依赖项。它包括适用于 x64 和 arm64 CPU 的工件

{
  "pnpm": {
    "supportedArchitectures": {
      "os": ["win32", "darwin", "current"],
      "cpu": ["x64", "arm64"]
    }
  }
}

此外，supportedArchitectures 还支持指定系统的 libc。

pnpm.ignoredOptionalDependencies​

如果可选依赖项的名称包含在此数组中，则将跳过它。例如

{
  "pnpm": {
    "ignoredOptionalDependencies": ["fsevents", "@esbuild/*"]
  }
}

resolutions​

在功能上与 pnpm.overrides 相同，此字段旨在使从 Yarn 迁移变得更容易。

resolutions 和 pnpm.overrides 在包解析之前合并（pnpm.overrides 优先），这在您从 Yarn 迁移并需要调整一些包以供 pnpm 使用时非常有用。