package.json
一个包的清单文件。 它包含包的所有元数据,包括依赖项、标题、作者等等。 这是所有主要的 Node.js 包管理工具,包括 pnpm 的保留标准。
engines
你可以指定你的软件能够运行的 Node 版本和 pnpm 版本:
{
"engines": {
"node": ">=10",
"pnpm": ">=3"
}
}
在本地开发时, 如果其版本与 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
该怎么办? 如果 monorepo 中的所有项目都使用相同版本的 react
,那么没问题。 但是,如果 card
使用 React@16
和 Form
以及 React@17
需要 button
该怎么办? 如果不使用 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
的依赖项中。
所以这将是 card
的 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,所选的 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
- 默认值: true
- 类型:Boolean
当设置为 true
时,项目将在本地开发期间从 publishConfig.directory
位置进行符 号链接。
示例:
{
"name": "foo",
"version": "1.0.0",
"publishConfig": {
"directory": "dist"
"linkDirectory": true
}
}
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
将只会重写zoo
的qar@1
依赖。
一个overide可以被定义为直接依赖的规则的引用。 这通过依赖名称前缀一个$
实现:
{
"dependencies": {
"foo": "^1.0.0"
},
"pnpm": {
"overrides": {
"foo": "$foo"
}
}
}
被引用的包不必匹配需要覆盖的包:
{
"dependencies": {
"foo": "^1.0.0"
},
"pnpm": {
"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
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
,请考虑向上游发送 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。
也可以仅抑制特定包的对等依赖项的警告。 例如,以下配置下 react
v17 仅在其位于 button
v2 包的对等依赖项中或任何 card
包的依赖项中时才被允许:
{
"pnpm": {
"peerDependencyRules": {
"allowedVersions": {
"button@2>react": "17",
"card>react": "17"
}
}
}
}
pnpm.peerDependencyRules.allowAny
allowAny
是一个匹配包名的数组,任何匹配该模式的peerDependencies将可被解析为任意版本,与 peerDependencies
里指定的范围无关。 例如:
{
"pnpm": {
"peerDependencyRules": {
"allowAny": ["@babel/*", "eslint"]
}
}
}
上述设置将禁用任何与 @babel/
或 eslint
有关的 peer dependency版本不匹配的警告。
pnpm.neverBuiltDependencies
此字段允许忽略特定依赖项的构建。 安装期间不会执行所列包的 “preinstall”、“install” 和 “postinstall” 脚本。
一个 "pnpm"."neverBuiltDependencies"
字段的例子:
{
"pnpm": {
"neverBuiltDependencies": ["fsevents", "level"]
}
}
pnpm.onlyBuiltDependencies
允许在安装期间执行安装的包名列表。 如果此字段存在,那么只有列出的软件包可以运行安装脚本。
示例:
{
"pnpm": {
"onlyBuiltDependencies": ["fsevents"]
}
}
pnpm.onlyBuiltDependenciesFile
添加于:v8.9.0
此配置选项允许用户指定一个 JSON 文件,该文件列出了在 pnpm 安装过程中允许运行安装脚本的唯一包。 通过使用它,你可以增强安全性或确保在安装过程中只有特定的依赖项执行脚本。
示例:
{
"dependencies": {
"@my-org/policy": "1.0.0"
},
"pnpm": {
"onlyBuiltDependenciesFile": "node_modules/@my-org/policy/onlyBuiltDependencies.json"
}
}
JSON 文件本身应包含一组包名称:
[
"fsevents"
]
pnpm.allowedDeprecatedVersions
此项设置允许忽略特定依赖包的 deprecation 警告。
示例:
{
"pnpm": {
"allowedDeprecatedVersions": {
"express": "1",
"request": "*"
}
}
}
使用上述配置,pnpm 将不会显示和任何版本的 request
以及 v1 版本的 express
有关的警告。
pnpm.patchedDependencies
当您运行 pnpm patch-commit时,会自动添加/更新此字段。 它是一个字典dictionary,其中key是包名+准确的版本号。 值value应该是一个指向patch文件的相对路径
示例:
{
"pnpm": {
"patchedDependencies": {
"express@4.18.1": "patches/express@4.18.1.patch"
}
}
}
pnpm.allowNonAppliedPatches
当设置为 true
时,如果 patchedDependencies
字段中的某些补丁未被应用,安装不会失败。
{
"pnpm": {
"patchedDependencies": {
"express@4.18.1": "patches/express@4.18.1.patch"
},
"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
添加于:v8.10.0
您可以指定要安装的可选依赖项的架构,即使它们与运行安装的系统的架构不匹配。
例如,以下配置指示安装 Windows x64 的可选依赖项:
{
"pnpm": {
"supportedArchitectures": {
"os": ["win32"],
"cpu": ["x64"]
}
}
}
而此配置将为 Windows、macOS 以及当前正在运行安装的系统架构安装可选依赖项。 它包括 x64 和 arm64 CPU 的工件:
{
"pnpm": {
"supportedArchitectures": {
"os": ["win32", "darwin", "current"],
"cpu": ["x64", "arm64"]
}
}
}
另外, supportedArchitectures
还支持指定系统的 libc
。
resolutions
该字段的功能与 pnpm.overrides
相同,旨在使从 Yarn 迁移变得更容易。
resolutions
和 pnpm.overrides
在包解析之前被合并( pnpm.overrides
优先),这在你从 Yarn 迁移并且需要仅为 pnpm 调整一些包时非常有用。