跳到主内容
版本:Next

package.json

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

字段

engines

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

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

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

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

dependenciesMeta

dependenciesMeta.*.injected

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

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

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

但是如果 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

{
"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的依赖项。

peerDependenciesMeta

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

peerDependenciesMeta.*.optional

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

例如:

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

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

publishConfig

package打包之前,可以覆盖 manifest 中的某些字段。 以下字段可以被覆盖:

要覆盖字段,请将字段的要发布的版本添加到 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 字段中列出的文件以外,在生成的package的 archive 包中的文件不会被标记为可执行文件。 executableFiles 字段允许您声明必须设置可执行标志 (+x) 的额外的字段,即使它们不能通过 bin 字段直接访问。

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

publishConfig.directory

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

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

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

{
"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依赖。

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
}
}
}
}
}
}
tip

Together with Yarn, we maintain a database of packageExtensions to patch broken packages in the ecosystem. If you use packageExtensions, consider sending a PR upstream and contributing your extension to the @yarnpkg/extensions database.

pnpm.peerDependencyRules.ignoreMissing

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

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

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

pnpm.peerDependencyRules.allowedVersions

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

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

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

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

pnpm.neverBuiltDependencies

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

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

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

pnpm.onlyBuiltDependencies

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

示例:

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