Skip to main content
Version: 8.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 字段中指定的版本不匹配，则它将始终失败并显示错误消息。

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

dependencyMeta.*.injected​

如果本地依赖设置为 true，则包将硬链接到虚拟存储（node_modules/.pnpm），并从虚拟存储符号链接到模块目录。

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

如果本地依赖设置为 false 或未设置，则包将直接从其在工作区中的位置符号链接到模块目录。

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

例如，工作区中的以下 package.json 将在 card 的 node_modules 目录中创建指向 button 的符号链接：

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

但是，如果 button 的对等依赖中包含 react 怎么办？如果 monorepo 中的所有项目都使用相同版本的 react，则没有问题。但是，如果 card 需要 button，而 card 使用 react@16 和 form 以及 react@17，该怎么办？如果不使用 inject，你必须选择一个版本的 react，并将其安装为 button 的开发依赖。但是，使用 injected 字段，你可以将 button 注入到包中，button 将与该包的 react 版本一起安装。

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

因此，这将是 card 的 package.json：

¥So this will be the package.json of card:

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

button 将硬链接到 card 的依赖，而 react@16 将符号链接到 card/node_modules/button 的依赖。

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

这将是 form 的 package.json：

¥And this will be the package.json of form:

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

button 将硬链接到 form 的依赖，而 react@17 将符号链接到 form/node_modules/button 的依赖。

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

与普通依赖不同，注入的依赖不会符号链接到目标文件夹，因此它们不会自动更新（例如，在运行构建脚本后）。要将硬链接文件夹内容更新为依赖包文件夹的最新状态，请再次调用 pnpm i。

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

请注意，button 包必须具有在安装时运行的任何生命周期脚本，以便 pnpm 检测到更改并进行更新。例如，软件包可以在安装时重建："prepare": "pnpm run build"。任何脚本都可以，即使是一个简单的、没有副作用的无关命令，例如："prepare": "pnpm root"。

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

此字段列出了与 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 字段允许你声明其他字段，即使这些字段无法通过 bin 字段直接访问，也必须设置可执行标志 (+x)。

¥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 覆盖依赖图中的任何依赖。这对于强制所有软件包使用依赖的单一版本、反向移植修复或用 fork 替换依赖非常有用。

¥This field allows you to instruct pnpm to override any dependency in the dependency graph. This is useful to enforce all your packages to use a single version of a dependency, backport a fix, or replace a dependency with a fork.

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

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

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​

已添加于：v8.9.0

¥Added in: v8.9.0

此配置选项允许用户指定一个 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.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​

已添加于：v8.10.0

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

例如，以下配置指示安装 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.

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.