跳到主内容
版本:7.x

package.json

一个包的清单文件。 它包含包的所有元数据,包括依赖项、标题、作者等等。 这是所有主要的 Node.JS 包管理工具,包括 pnpm 的保留标准。

engines

你可以指定你的软件能够运行的 Node 版本和 pnpm 版本:

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

在本地开发时, 如果其版本与 engines 字段中指定的版本不匹配,pnpm 将始终失败并报错。

当你的包作为依赖被安装时,除非用户已设置 engine-strict 配置标志 (参阅 .npmrc),否则此字段仅供参考,且只会产生警告。

dependenciesMeta

用于在 dependencies, optionalDependenciesdevDependencies 中声明的依赖项的补充元信息。

dependenciesMeta.*.injected

如果对本地依赖项将此设置为 true,则package将被硬链接到模块目录,而非软链接。

例如,下面的工作空间中的 package.json 会在 cardnode_modules 目录中创建一个 button 的软链接:

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

但是,如果 button 在其对等依赖项中有 react 该怎么办? 如果 monorepo 中的所有项目都使用相同版本的 react,那么没问题。 但是,如果 card 使用 React@16Form 以及 React@17需要 button 该怎么办? 如果不使用 Inject,您必须选择 React 的单个版本并将其安装为 Button的开发依赖项。 但是使用 injected 字段,您可以将 button 注入到包中,并且 button 将与该包的 React 版本一起安装。

所以这将是 cardpackage.json

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

button 将被硬链接进 card 的依赖项中,同时 react@16 会被软链接到 card/node_modules/button 的依赖项中。

所以这将是 cardpackage.json

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

button 将被硬链接进 form 的依赖项中,同时 react@17 会被软链接到 form/node_modules/button 的依赖项中。

peerDependenciesMeta

此字段列出了一些与 peerDependencies 字段中列出的依赖关系相关的额外信息。

peerDependenciesMeta.*.optional

如果设置为 true,所选的 peer dependency 将被包管理工具标记为可选的。 因此,消费方省略它将不再是 被报告为错误。

示例:

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

请注意,即使在peerDependencies中没有指定 bar, 但它也会被标记为可选的。 因此,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

添加于:v7.8.0

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

示例:

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

pnpm.overrides

此字段允许您指示 pnpm 覆盖依赖关系图中的任何依赖项。 这对于您强制所有的packages使用单个版本的依赖项,或做后移植的修复,或用一个 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"
}
}
}

你可以指定覆写依赖的package,通过用">"来从依赖的选择器分离出package的选择器。例如,qar@1>zoo 将只会重写zooqar@1依赖。

一个overide可以被定义为直接依赖项的规则的引用。 这通过依赖名称前缀一个$实现:

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

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

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

pnpm.packageExtensions

这个 packageExtension 字段提供了一种用额外信息扩展现有package定义的方法。 例如,如果react-redux 本应该在它的 peerDependencies 中包含 react-dom ,但却没有,则可以用 packageExtensions 来填补上react-redux

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

packageExtensions 中的键是package名称或 semver 的package名称,因此可以只修改package的某些版本:

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

以下字段可以使用 packageExtensions 被扩展:dependencies optionalDependencies peerDependenciespeerDependenciesMeta

一个更大的例子:

{
"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,请考虑向上游发送 PR 并将您的该扩展贡献给 @yarnpkg/extensions 数据库。

pnpm.peerDependencyRules

pnpm.peerDependencyRules.ignoreMissing

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

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

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

包名也可以使用模式匹配

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

pnpm.peerDependencyRules.allowedVersions

对于指定版本范围的 peerDependency,将不会打印未满足版本范围的警告。

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

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

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

It is also possible to suppress the warnings only for peer dependencies of specific packages. For instance, with the following configuration react v17 will be only allowed when it is in the peer dependencies of the button v2 package or in the dependencies of any card package:

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

pnpm.peerDependencyRules.allowAny

Added in: v7.3.0

allowAny 是一个匹配包名的数组,任何匹配该模式的peerDependencies将可被解析为任意版本,与 peerDependencies里指定的范围无关。 例如:

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

上述设置将禁用任何与 @babel/eslint 有关的 peer dependency版本不匹配的警告。

pnpm.neverBuiltDependencies

This field allows to ignore the builds of specific dependencies. The "preinstall", "install", and "postinstall" scripts of the listed packages will not be executed during installation.

An example of the "pnpm"."neverBuiltDependencies" field:

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

pnpm.onlyBuiltDependencies

A list of package names that are allowed to be executed during installation. If this field exists, only the listed packages will be able to run install scripts.

示例:

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

pnpm.allowedDeprecatedVersions

Added in: v7.2.0

这个设置允许忽略特定包的弃用警告。

示例:

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

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

pnpm.patchedDependencies

添加于:v7.4.0

当您运行 pnpm patch-commit时,会自动添加/更新此字段。 它是一个字典dictionary,其中key是包名+准确的版本号。 值value应该是一个指向patch文件的相对路径

示例:

{
"pnpm": {
"patchedDependencies": {
"express@4.18.1": "patches/express@4.18.1.patch"
}
}
}

pnpm.allowNonAppliedPatches

Added in: v7.12.0

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

{
"pnpm": {
"patchedDependencies": {
"express@4.18.1": "patches/express@4.18.1.patch"
}
"allowNonAppliedPatches": true
}

pnpm.updateConfig

pnpm.updateConfig.ignoreDependencies

Added in: v7.13.0

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

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

还支持使用模式匹配,因此您可以忽略任何在范围内的包: @babel/*

pnpm.auditConfig

pnpm.auditConfig.ignoreCves

Added in: v7.15.0

pnpm audit 命令将忽略列表中的CVE ID

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

pnpm.requiredScripts

Added in: v7.19.0

工作区的每个项目,都必须含有此数组中的所有脚本。 否则, pnpm -r run <script name> 将失败。

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

resolutions

pnpm.overrides 相同。 我们读取它是为了更容易地从 Yarn 中迁移。