Skip to main content
Version: 9.x

package.json

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

¥The manifest file of a package. It contains all the package's metadata, including dependencies, title, author, et cetera. This is a standard preserved across all major Node.JS package managers, including pnpm.

engines​

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

¥You can specify the version of Node and pnpm that your software works on:

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

在本地开发过程中，如果 pnpm 的版本与 engines 字段中指定的版本不匹配，pnpm 将始终失败并显示错误消息。

¥During local development, pnpm will always fail with an error message if its version does not match the one specified in the engines field.

除非用户设置了 engine-strict 配置标志（请参阅 .npmrc），否则此字段仅供参考，并且仅在你的软件包作为依赖安装时才会产生警告。

¥Unless the user has set the engine-strict config flag (see .npmrc), this field is advisory only and will only produce warnings when your package is installed as a dependency.

dependenciesMeta​

用于 dependencies、optionalDependencies 和 devDependencies 内声明的依赖的附加元信息。

¥Additional meta information used for dependencies declared inside dependencies, optionalDependencies, and devDependencies.

dependenciesMeta.*.injected​

如果对于作为本地工作区包的依赖将其设置为 true，则将通过在虚拟存储 (node_modules/.pnpm) 中创建硬链接副本来安装该包。

¥If this is set to true for a dependency that is a local workspace package, that package will be installed by creating a hard linked copy in the virtual store (node_modules/.pnpm).

如果将其设置为 false 或未设置，则将通过创建指向工作区中包的源目录的 node_modules 符号链接来安装依赖。这是默认设置，因为它速度更快，并确保对依赖的任何修改都将立即对其使用者可见。

¥If this is set to false or not set, then the dependency will instead be installed by creating a node_modules symlink that points to the package's source directory in the workspace. This is the default, as it is faster and ensures that any modifications to the dependency will be immediately visible to its consumers.

例如，假设以下 package.json 是本地工作区包：

¥For example, suppose the following package.json is a local workspace package:

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

button 依赖通常通过在 card 的 node_modules 目录中创建符号链接来安装，指向 button 的开发目录。

¥The button dependency will normally be installed by creating a symlink in the node_modules directory of card, pointing to the development directory for button.

但是如果 button 在其 peerDependencies 中指定了 react 呢？如果 monorepo 中的所有项目都使用相同版本的 react，那么就没有问题。但是，如果使用 react@16 的 card 和使用 react@17 的 form 需要 button，该怎么办？通常你必须选择 react 的单个版本并使用 devDependencies 或 button 指定它。符号链接没有提供一种方法来让不同的消费者（例如 card 和 form）以不同的方式满足 react 对等依赖。

¥But what if button specifies react in its peerDependencies? If all projects in the monorepo use the same version of react, then there is no problem. But what if button is required by card that uses react@16 and form that uses react@17? Normally you'd have to choose a single version of react and specify it using devDependencies of button. Symlinking does not provide a way for the react peer dependency to be satisfied differently by different consumers such as card and form.

injected 字段通过在虚拟存储中安装 button 的硬链接副本来解决此问题。为此，可以按如下方式配置 package.json 或 card：

¥The injected field solves this problem by installing a hard linked copies of button in the virtual store. To accomplish this, the package.json of card could be configured as follows:

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

而 package.json 或 form 可以配置如下：

¥Whereas the package.json of form could be configured as follows:

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

通过这些更改，我们说 button 是 card 和 form 的 "注入依赖"。当 button 导入 react 时，它将在 card 的上下文中解析为 react@16，但在 form 的上下文中解析为 react@17。

¥With these changes, we say that button is an "injected dependency" of card and form. When button imports react, it will resolve to react@16 in the context of card, but resolve to react@17 in the context of form.

由于注入的依赖会生成其工作区源目录的副本，因此每当修改代码时都必须以某种方式更新这些副本；否则，新状态将不会反映给消费者。当使用 pnpm --recursive run build 之类的命令构建多个项目时，此更新必须在重建每个注入的包之后但在重建其使用者之前发生。对于简单的用例，可以通过再次调用 pnpm install 来完成，也许使用 package.json 生命周期脚本（例如 "prepare": "pnpm run build"）来重建该项目。pnpm-sync 和 pnpm-sync-dependencies-meta-injected 等第三方工具提供了更强大、更高效的解决方案来更新注入的依赖以及监视模式支持。

¥Because injected dependencies produce copies of their workspace source directory, these copies must be updated somehow whenever the code is modified; otherwise, the new state will not be reflected for consumers. When building multiple projects with a command such as pnpm --recursive run build, this update must occur after each injected package is rebuilt but before its consumers are rebuilt. For simple use cases, it can be accomplished by invoking pnpm install again, perhaps using a package.json lifecycle script such as "prepare": "pnpm run build" to rebuild that one project. Third party tools such as pnpm-sync and pnpm-sync-dependencies-meta-injected provide a more robust and efficient solution for updating injected dependencies, as well as watch mode support.

peerDependenciesMeta​

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

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

peerDependenciesMeta.*.optional​

如果将此设置为 true，则选定的对等依赖将被包管理器标记为可选。因此，消费者忽略它将不再被报告为错误。

¥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.

例如：

¥For example:

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

请注意，即使 peerDependencies 中未指定 bar，它也被标记为可选。因此，pnpm 将假定任何版本的 bar 都可以。然而，foo 是可选的，但仅限于所需的版本规范。

¥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:

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

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

例如下面的 package.json：

¥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​

默认情况下，出于可移植性的原因，除了 bin 字段中列出的文件之外，不会在生成的包存档中将任何文件标记为可执行文件。executableFiles 字段允许你声明必须设置可执行标志 (+x) 的其他字段，即使它们不能通过 bin 字段直接访问。

¥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​

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

¥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

¥In this example the "dist" folder must contain a package.json

{
  "name": "foo",
  "version": "1.0.0",
  "publishConfig": {
    "directory": "dist"
  }
}

publishConfig.linkDirectory​

  • 默认：true

    ¥Default: true

  • 类型：布尔值

    ¥Type: Boolean

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

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

例如：

¥For example:

{
  "name": "foo",
  "version": "1.0.0",
  "publishConfig": {
    "directory": "dist",
    "linkDirectory": true
  }
}

pnpm.overrides​

该字段允许你指示 pnpm 覆盖依赖图中的任何依赖。这对于强制所有包使用依赖的单一版本、反向移植修复、用分支替换依赖或删除未使用的依赖非常有用。

¥This field allows you to instruct pnpm to override any dependency in the dependency graph. This is useful for enforcing all your packages to use a single version of a dependency, backporting a fix, replacing a dependency with a fork, or removing an unused dependency.

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

¥Note that the overrides field can only be set at the root of the project.

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

¥An example of the "pnpm"."overrides" field:

{
  "pnpm": {
    "overrides": {
      "foo": "^1.0.0",
      "quux": "npm:@myorg/quux@^1.0.0",
      "bar@^2.1.0": "3.0.0",
      "qar@1>zoo": "2"
    }
  }
}

你可以通过用 ">" 将软件包选择器与依赖选择器分开来指定覆盖依赖所属的软件包，例如 qar@1>zoo 将仅覆盖 qar@1 的 zoo 依赖，而不会覆盖任何其他依赖。

¥You may specify the package the overridden dependency belongs to by separating the package selector from the dependency selector with a ">", for example qar@1>zoo will only override the zoo dependency of qar@1, not for any other dependencies.

覆盖可以定义为对直接依赖规范的引用。这是通过在依赖名称前加上 $ 前缀来实现的：

¥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"
    }
  }
}

添加于：v9.12.0

¥Added in: v9.12.0

如果你发现对某个包的使用不需要其依赖之一，则可以使用 - 将其删除。例如，如果包 foo@1.0.0 需要一个名为 bar 的大型包来实现你不使用的功能，则删除它可以减少安装时间：

¥If you find that your use of a certain package doesn’t require one of its dependencies, you may use - to remove it. For example, if package foo@1.0.0 requires a large package named bar for a function that you don’t use, removing it could reduce install time:

{
  "pnpm": {
    "overrides": {
      "foo@1.0.0>bar": "-"
    }
  }
}

此功能对于 optionalDependencies 尤其有用，因为大多数可选包都可以安全跳过。

¥This feature is especially useful with optionalDependencies, where most optional packages can be safely skipped.

pnpm.packageExtensions​

packageExtensions 字段提供了一种使用附加信息扩展现有包定义的方法。例如，如果 react-redux 的 peerDependencies 中应该有 react-dom，但它没有，则可以使用 packageExtensions 修补 react-redux：

¥The packageExtensions fields offer a way to extend the existing package definitions with additional information. For example, if react-redux should have react-dom in its peerDependencies but it has not, it is possible to patch react-redux using packageExtensions:

{
  "pnpm": {
    "packageExtensions": {
      "react-redux": {
        "peerDependencies": {
          "react-dom": "*"
        }
      }
    }
  }
}

packageExtensions 中的键是包名称或包名称和 semver 范围，因此可以仅修补包的某些版本：

¥The keys in packageExtensions are package names or package names and semver ranges, so it is possible to patch only some versions of a package:

{
  "pnpm": {
    "packageExtensions": {
      "react-redux@1": {
        "peerDependencies": {
          "react-dom": "*"
        }
      }
    }
  }
}

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

¥The following fields may be extended using packageExtensions: dependencies, optionalDependencies, peerDependencies, and peerDependenciesMeta.

一个更大的例子：

¥A bigger example:

{
  "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 数据库。

¥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 不会打印有关此列表中缺少对等依赖的警告。

¥pnpm will not print warnings about missing peer dependencies from this list.

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

¥For instance, with the following configuration, pnpm will not print warnings if a dependency needs react but react is not installed:

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

还可以使用包名称模式：

¥Package name patterns may also be used:

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

pnpm.peerDependencyRules.allowedVersions​

对于指定范围的对等依赖，不会打印未满足的对等依赖警告。

¥Unmet peer dependency warnings will not be printed for peer dependencies of the specified range.

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

¥For instance, if you have some dependencies that need react@16 but you know that they work fine with react@17, then you may use the following configuration:

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

这将告诉 pnpm，任何在其对等依赖中发生反应的依赖都应该允许安装 react v17。

¥This will tell pnpm that any dependency that has react in its peer dependencies should allow react v17 to be installed.

还可以仅针对特定包的对等依赖抑制警告。例如，使用以下配置，仅当 react v17 位于 button v2 包的对等依赖或任何 card 包的依赖中时，才允许使用 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 中指定的范围如何。例如：

¥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. For instance:

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

上述设置将消除有关与 @babel/ 包或 eslint 相关的对等依赖版本不匹配的任何警告。

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

pnpm.neverBuiltDependencies​

该字段允许忽略特定依赖的构建。列出的软件包的 "preinstall"、"install" 和 "postinstall" 脚本在安装过程中不会执行。

¥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.

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

¥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.

示例：

¥Example:

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

pnpm.onlyBuiltDependenciesFile​

此配置选项允许用户指定一个 JSON 文件，该文件列出了在 pnpm 安装过程中允许运行安装脚本的唯一包。通过使用它，你可以增强安全性或确保在安装过程中只有特定的依赖执行脚本。

¥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.

示例：

¥Example:

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

JSON 文件本身应包含一组包名称：

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

node_modules/@my-org/policy/onlyBuiltDependencies.json
[
  "fsevents"
]

pnpm.allowedDeprecatedVersions​

此设置允许静音特定包的弃用警告。

¥This setting allows muting deprecation warnings of specific packages.

示例：

¥Example:

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

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

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

pnpm.patchedDependencies​

当你运行 pnpm patch-commit 时，此字段会自动添加/更新。它是一个字典，其中键应该是包名称和确切版本。该值应该是补丁文件的相对路径。

¥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.

示例：

¥Example:

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

pnpm.allowNonAppliedPatches​

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

¥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​

有时你无法更新依赖。例如，最新版本的依赖开始使用 ESM，但你的项目尚未使用 ESM。令人烦恼的是，当运行 pnpm update --latest 时，这样的包总是会被 pnpm outdated 命令打印出来并更新。但是，你可以在 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"]
    }
  }
}

还支持模式，因此你可以忽略某个范围内的任何包：@babel/*。

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

pnpm.auditConfig​

pnpm.auditConfig.ignoreCves​

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

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

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

pnpm.auditConfig.ignoreGhsas​

添加于：v9.10.0

¥Added in: v9.10.0

pnpm audit 命令将忽略的 GHSA 代码列表。

¥A list of GHSA Codes that will be ignored by the pnpm audit command.

{
  "pnpm": {
    "auditConfig": {
      "ignoreGhsas": [
        "GHSA-42xw-2xvc-qx8m",
        "GHSA-4w2v-q235-vp99",
        "GHSA-cph5-m8f7-6c5x",
        "GHSA-vh95-rmgr-6w4m"
      ]
    }
  }
}

pnpm.requiredScripts​

工作区的每个项目都需要此数组中列出的脚本。否则，pnpm -r run <script name> 将会失败。

¥Scripts listed in this array will be required in each project of the workspace. Otherwise, pnpm -r run <script name> will fail.

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

pnpm.supportedArchitectures​

你可以指定要安装可选依赖的体系结构，即使它们与运行安装的系统的体系结构不匹配。

¥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.

例如，以下配置指示安装 Windows x64 的可选依赖：

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

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

而此配置将为 Windows、macOS 以及当前运行安装的系统架构安装可选依赖。它包括 x64 和 arm64 CPU 的工件：

¥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"]
    }
  }
}

另外，supportedArchitectures 还支持指定系统的 libc。

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

pnpm.ignoredOptionalDependencies​

如果可选依赖的名称包含在此数组中，则会跳过该依赖。例如：

¥If an optional dependency has its name included in this array, it will be skipped. For example:

{
  "pnpm": {
    "ignoredOptionalDependencies": ["fsevents", "@esbuild/*"]
  }
}

pnpm.executionEnv.nodeVersion​

添加于：v9.6.0

¥Added in: v9.6.0

指定项目运行时应使用哪个确切的 Node.js 版本。pnpm 将自动安装指定版本的 Node.js 并使用它来运行 pnpm run 命令或 pnpm node 命令。

¥Specifies which exact Node.js version should be used for the project's runtime. pnpm will automatically install the specified version of Node.js and use it for running pnpm run commands or the pnpm node command.

例如：

¥For example:

{
  "pnpm": {
    "executionEnv": {
      "nodeVersion": "16.16.0"
    }
  }
}

resolutions​

该字段的功能与 pnpm.overrides 相同，旨在更轻松地从 Yarn 迁移。

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

resolutions 和 pnpm.overrides 在包解析之前合并（pnpm.overrides 优先），这在你从 Yarn 迁移并且需要仅针对 pnpm 调整一些包时非常有用。

¥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.