跳到主内容
版本：Next

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，则package将被硬链接到模块目录，而非软链接。

例如，下面的工作空间中的 package.json 会在card的node_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的依赖项。

与普通依赖项不同，注入的依赖项不会链接到目标文件夹，因此它们不会自动更新，例如在运行构建脚本后。 要将硬链接的文件夹内容更新为依赖包文件夹的最新状态，请再次调用 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
        }
    }
}

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

When set to true, the project will be symlinked from the publishConfig.directory location during local development.

示例：

{
  "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 将只会重写 qar@1 的 zoo 依赖。

An override may be defined as a reference to a direct dependency's spec. This is achieved by prefixing the name of the dependency with a $:

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

The referenced package does not need to match the overridden one:

{
  "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
          }
        }
      }
    }
  }
}
提示

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​

pnpm.peerDependencyRules.ignoreMissing​

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

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

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

Package name patterns may also be used:

{
  "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 is an array of package name patterns, any peer dependency matching the pattern will be resolved from any version, regardless of the range specified in peerDependencies. 例如：

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

The above setting will mute any warnings about peer dependency version mismatches related to @babel/ packages or eslint.

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​

This setting allows muting deprecation warnings of specific packages.

示例：

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

With the above configuration pnpm will not print deprecation warnings about any version of request and about v1 of express.

pnpm.patchedDependencies​

This field is added/updated automatically when you run pnpm patch-commit. It is a dictionary where the key should be the package name and exact version. The value should be a relative path to a patch file.

示例：

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

pnpm.allowNonAppliedPatches​

When true, installation won't fail if some of the patches from the patchedDependencies field were not applied.

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

pnpm.updateConfig​

pnpm.updateConfig.ignoreDependencies​

Sometimes you can't update a dependency. For instance, the latest version of the dependency started to use ESM but your project is not yet in ESM. Annoyingly, such a package will be always printed out by the pnpm outdated command and updated, when running pnpm update --latest. However, you may list packages that you don't want to upgrade in the ignoreDependencies field:

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

Patterns are also supported, so you may ignore any packages from a scope: @babel/*.

pnpm.auditConfig​

pnpm.auditConfig.ignoreCves​

A list of CVE IDs that will be ignored by the pnpm audit command.

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

pnpm.requiredScripts​

工作区的每个项目，都必须含有此数组中的所有脚本。 Otherwise, pnpm -r run <script name> will fail.

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

resolutions​

Same as pnpm.overrides. We read it for easier migration from Yarn.