package.json

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

engines

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

  1. {
  2.     "engines": {
  3.         "node": ">=10",
  4.         "pnpm": ">=3"
  5.     }
  6. }

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

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

dependenciesMeta

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

dependenciesMeta.*.injected

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

例如，下面的工作空间中的 package.json 会在card的node_modules 目录中创建一个 button 的软链接：

  1. {
  2.   "name": "card",
  3.   "dependencies": {
  4.     "button": "workspace:1.0.0"
  5.   }
  6. }

但是如果 button 在其peer dependencies中含有 react 呢？ 如果 monorepo 中的所有项目都使用相同版本的 react，那么不会有什么问题。 但要是 card 依赖的 button 使用 react@16，而依赖的 form 却使用 react@17 呢？ 如果不使用 injection，您必须选择单一的 react 版本并将其作为button的 dev dependency 安装。 但是使用 injected 字段，您可以将 button 注入到一个package中，而 button 将与该package 中的 react版本一同安装。

因此，这将是 card 的 package.json：

  1. {
  2.   "name": "card",
  3.   "dependencies": {
  4.     "button": "workspace:1.0.0",
  5.     "react": "16"
  6.   },
  7.   "dependenciesMeta": {
  8.     "button": {
  9.       "injected": true
  10.     }
  11.   }
  12. }

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

而且，这将是 form 的 package.json：

  1. {
  2.   "name": "form",
  3.   "dependencies": {
  4.     "button": "workspace:1.0.0",
  5.     "react": "17"
  6.   },
  7.   "dependenciesMeta": {
  8.     "button": {
  9.       "injected": true
  10.     }
  11.   }
  12. }

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

peerDependenciesMeta

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

peerDependenciesMeta.*.optional

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

示例：

  1. {
  2.     "peerDependencies": {
  3.         "foo": "1"
  4.     },
  5.     "peerDependenciesMeta": {
  6.         "foo": {
  7.             "optional": true
  8.         },
  9.         "bar": {
  10.             "optional": true
  11.         }
  12.     }
  13. }

请注意，即使在peerDependencies中没有指定 bar, 但它也会被标记为可选的。 因此，pnpm 将假定任何版本的 bar 都是被允许的。 然而，foo 是可选的，但仅适用于所指定的版本。

publishConfig

在package打包之前，可以覆盖 manifest 中的某些字段。 以下字段可以被覆盖：

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

例如，下面的package.json:

  1. {
  2.     "name": "foo",
  3.     "version": "1.0.0",
  4.     "main": "src/index.ts",
  5.     "publishConfig": {
  6.         "main": "lib/index.js",
  7.         "typings": "lib/index.d.ts"
  8.     }
  9. }

将发布为：

  1. {
  2.     "name": "foo",
  3.     "version": "1.0.0",
  4.     "main": "lib/index.js",
  5.     "typings": "lib/index.d.ts"
  6. }

publishConfig.executableFiles

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

  1. {
  2.   "publishConfig": {
  3.     "executableFiles": [
  4.       "./dist/shim.js"
  5.     ]
  6.   }
  7. }

publishConfig.directory

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

预期会在指定目录中有当前package的修改后的版本（通常使用第三方构建工具）。

在这个例子中 "dist" 文件夹必须包含一个 package.json

  1. {
  2.   "name": "foo",
  3.   "version": "1.0.0",
  4.   "publishConfig": {
  5.     "directory": "dist"
  6.   }
  7. }

publishConfig.linkDirectory

添加于：v7.8.0

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

示例：

  1. {
  2.   "name": "foo",
  3.   "version": "1.0.0",
  4.   "publishConfig": {
  5.     "directory": "dist"
  6.   }
  7. }

pnpm.overrides

此字段允许您指示 pnpm 覆盖依赖关系图中的任何依赖项。 这对于您强制所有的packages使用单个版本的依赖项，或做后移植的修复，或用一个 fork 来替换依赖项时将十分有用。

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

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

  1. {
  2.   "pnpm": {
  3.     "overrides": {
  4.       "foo": "^1.0.0",
  5.       "quux": "npm:@myorg/quux@^1.0.0",
  6.       "bar@^2.1.0": "3.0.0",
  7.       "qar@1>zoo": "2"
  8.     }
  9.   }
  10. }

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

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

  1. {
  2.   "dependencies": {
  3.     "foo": "^1.0.0"
  4.   },
  5.   "overrides": {
  6.     "foo": "$foo"
  7.   }
  8. }

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

  1. {
  2.   "dependencies": {
  3.     "foo": "^1.0.0"
  4.   },
  5.   "overrides": {
  6.     "bar": "$foo"
  7.   }
  8. }

pnpm.packageExtensions

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

  1. {
  2.   "pnpm": {
  3.     "packageExtensions": {
  4.       "react-redux": {
  5.         "peerDependencies": {
  6.           "react-dom": "*"
  7.         }
  8.       }
  9.     }
  10.   }
  11. }

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

  1. {
  2.   "pnpm": {
  3.     "packageExtensions": {
  4.       "react-redux@1": {
  5.         "peerDependencies": {
  6.           "react-dom": "*"
  7.         }
  8.       }
  9.     }
  10.   }
  11. }

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

一个更大的例子：

  1. {
  2.   "pnpm": {
  3.     "packageExtensions": {
  4.       "express@1": {
  5.         "optionalDependencies": {
  6.           "typescript": "2"
  7.         }
  8.       },
  9.       "fork-ts-checker-webpack-plugin": {
  10.         "dependencies": {
  11.           "@babel/core": "1"
  12.         },
  13.         "peerDependencies": {
  14.           "eslint": ">= 6"
  15.         },
  16.         "peerDependenciesMeta": {
  17.           "eslint": {
  18.             "optional": true
  19.           }
  20.         }
  21.       }
  22.     }
  23.   }
  24. }

package.json - 图1提示

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

pnpm.peerDependencyRules

pnpm.peerDependencyRules.ignoreMissing

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

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

  1. {
  2.   "pnpm": {
  3.     "peerDependencyRules": {
  4.       "ignoreMissing": ["react"]
  5.     }
  6.   }
  7. }

包名也可以使用模式匹配

  1. {
  2.   "pnpm": {
  3.     "peerDependencyRules": {
  4.       "ignoreMissing": ["@babel/*", "@eslint/*"]
  5.     }
  6.   }
  7. }

pnpm.peerDependencyRules.allowedVersions

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

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

  1. {
  2.   "pnpm": {
  3.     "peerDependencyRules": {
  4.       "allowedVersions": {
  5.         "react": "17"
  6.       }
  7.     }
  8.   }
  9. }

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

pnpm.peerDependencyRules.allowAny

添加于：v7.3.0

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

  1. {
  2.   "pnpm": {
  3.     "peerDependencyRules": {
  4.       "allowAny": ["@babel/*", "eslint"]
  5.     }
  6.   }
  7. }

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

pnpm.neverBuiltDependencies

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

关于 "pnpm"."neverBuiltDependencies" 字段的一个例子:

  1. {
  2.   "pnpm": {
  3.     "neverBuiltDependencies": ["fsevents", "level"]
  4.   }
  5. }

pnpm.onlyBuiltDependencies

允许在安装期间执行安装的包名列表。 如果此字段存在，那么只有列出的软件包可以运行安装脚本。

示例：

  1. {
  2.   "pnpm": {
  3.     "onlyBuiltDependencies": ["fsevents"]
  4.   }
  5. }

pnpm.allowedDeprecatedVersions

添加于：v7.2.0

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

示例：

  1. {
  2.   "pnpm": {
  3.     "allowedDeprecatedVersions": {
  4.       "express": "1",
  5.       "request": "*"
  6.     }
  7.   }
  8. }

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

pnpm.patchedDependencies

添加于：v7.4.0

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

示例：

  1. {
  2.   "pnpm": {
  3.     "patchedDependencies": {
  4.       "express@4.18.1": "patches/express@4.18.1.patch"
  5.     }
  6.   }
  7. }

pnpm.allowNonAppliedPatches

添加于： v7.12.0

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

  1. {
  2.   "pnpm": {
  3.     "patchedDependencies": {
  4.       "express@4.18.1": "patches/express@4.18.1.patch"
  5.     }
  6.     "allowNonAppliedPatches": true
  7. }

pnpm.updateConfig

pnpm.updateConfig.ignoreDependencies

添加于：v7.13.0

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

  1. {
  2.   "pnpm": {
  3.     "updateConfig": {
  4.       "ignoreDependencies": ["load-json-file"]
  5.     }
  6.   }
  7. }

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

pnpm.auditConfig

pnpm.auditConfig.ignoreCves

添加于：v7.15.0

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

  1. {
  2.   "pnpm": {
  3.     "auditConfig": {
  4.       "ignoreCves": [
  5.         "CVE-2022-36313"
  6.       ]
  7.     }
  8.   }
  9. }

pnpm.requiredScripts

添加于：v7.19.0

Scripts listed in this array will be required in each project of the workspace. 否则， pnpm -r run <script name> 将失败。

  1. {
  2.   "pnpm": {
  3.     "requiredScripts": ["build"]
  4.   }
  5. }

resolutions

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