跳到主内容
版本：8.x

package.json

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

engines​

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

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

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

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

dependenciesMeta​

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

dependenciesMeta.*.injected​

If this is set to true for a local dependency, the package will be hard linked to the virtual store (node_modules/.pnpm) and symlinked from the virtual store to the modules directory.

If this is set to false or not set for a local dependency, the package will be symlinked directly from its location in the workspace to the module directory.

For instance, the following package.json in a workspace will create a symlink to button in the node_modules directory of card:

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

But what if button has react in its peer dependencies? If all projects in the monorepo use the same version of react, then no problem. But what if button is required by card that uses react@16 and form with react@17? Without using inject, you'd have to choose a single version of react and install it as dev dependency of button. But using the injected field you can inject button to a package, and button will be installed with the react version of that package.

So this will be the package.json of card:

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

button will be hard linked into the dependencies of card, and react@16 will be symlinked to the dependencies of card/node_modules/button.

And this will be the package.json of form:

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

button will be hard linked into the dependencies of form, and react@17 will be symlinked to the dependencies of form/node_modules/button.

In contrast to normal dependencies, injected ones are not symlinked to the destination folder, so they are not updated automatically, e.g. after running the build script. To update the hard linked folder contents to the latest state of the dependency package folder, call pnpm i again.

Note that the button package must have any lifecycle script that runs on install in order for pnpm to detect the changes and update it. For example, the package can be rebuilt on install: "prepare": "pnpm run build". Any script would work, even a simple unrelated command without side effects, like this: "prepare": "pnpm root".

peerDependenciesMeta​

This field lists some extra information related to the dependencies listed in the peerDependencies field.

peerDependenciesMeta.*.optional​

If this is set to true, the selected peer dependency will be marked as optional by the package manager. Therefore, the consumer omitting it will no longer be reported as an error.

示例：

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

Note that even though bar was not specified in peerDependencies, it is marked as optional. pnpm will therefore assume that any version of bar is fine. However, foo is optional, but only to the required version specification.

publishConfig​

It is possible to override some fields in the manifest before the package is packed. The following fields may be overridden:

To override a field, add the publish version of the field to publishConfig.

For instance, the following package.json:

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

Will be published as:

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

publishConfig.executableFiles​

By default, for portability reasons, no files except those listed in the bin field will be marked as executable in the resulting package archive. The executableFiles field lets you declare additional fields that must have the executable flag (+x) set even if they aren't directly accessible through the bin field.

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

publishConfig.directory​

You also can use the field publishConfig.directory to customize the published subdirectory relative to the current package.json.

It is expected to have a modified version of the current package in the specified directory (usually using third party build tools).

在这个例子中 "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"
  }
}

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。

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​

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​

Added in: v8.9.0

This configuration option allows users to specify a JSON file that lists the only packages permitted to run installation scripts during the pnpm install process. By using this, you can enhance security or ensure that only specific dependencies execute scripts during installation.

示例：

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

The JSON file itself should contain an array of package names:

node_modules/@my-org/policy/onlyBuiltDependencies.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​

Added in: v8.10.0

You can specify architectures for which you'd like to install optional dependencies, even if they don't match the architecture of the system running the install.

For example, the following configuration tells to install optional dependencies for Windows x64:

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

Whereas this configuration will install optional dependencies for Windows, macOS, and the architecture of the system currently running the install. It includes artifacts for both x64 and arm64 CPUs:

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

Additionally, supportedArchitectures also supports specifying the libc of the system.

resolutions​

Functionally identical to pnpm.overrides, this field is intended to make it easier to migrate from Yarn.

resolutions and pnpm.overrides get merged before package resolution (with pnpm.overrides taking precedence), which can be useful when you're migrating from Yarn and need to tweak a few packages just for pnpm.