.pnpmfile.cjs

pnpm 允许你通过特殊函数（钩子）直接钩子到安装过程。钩子可以在名为 .pnpmfile.cjs.h 的文件中声明。

¥pnpm lets you hook directly into the installation process via special functions (hooks). Hooks can be declared in a file called .pnpmfile.cjs.

默认情况下，.pnpmfile.cjs 应位于与锁定文件相同的目录中。例如，在具有共享锁定文件的 workspace 中，.pnpmfile.cjs 应该位于 monorepo 的根目录中。

¥By default, .pnpmfile.cjs should be located in the same directory as the lockfile. For instance, in a workspace with a shared lockfile, .pnpmfile.cjs should be in the root of the monorepo.

钩子

¥Hooks

长话短说

¥TL;DR

钩子功能	过程	用途
hooks.readPackage(pkg, context): pkg	pnpm 解析依赖的包清单后调用	允许你改变依赖的 package.json
hooks.afterAllResolved(lockfile, context): lockfile	解决依赖后调用。	允许你改变锁定文件。

hooks.readPackage(pkg, context): pkg | Promise<pkg>

允许你在解析之后和解析之前改变依赖的 package.json。这些突变不会保存到文件系统中，但是，它们会影响锁定文件中解析的内容，从而影响安装的内容。

¥Allows you to mutate a dependency's package.json after parsing and prior to resolution. These mutations are not saved to the filesystem, however, they will affect what gets resolved in the lockfile and therefore what gets installed.

请注意，如果你已经解决了要修改的依赖，则需要删除 pnpm-lock.yaml。

¥Note that you will need to delete the pnpm-lock.yaml if you have already resolved the dependency you want to modify.

提示

如果需要将 package.json 的更改保存到文件系统，则需要使用 pnpm patch 命令并修补 package.json 文件。例如，如果你想删除依赖的 bin 字段，这可能很有用。

¥If you need changes to package.json saved to the filesystem, you need to use the pnpm patch command and patch the package.json file. This might be useful if you want to remove the bin field of a dependency for instance.

参数

¥Arguments

• pkg - 包的清单。来自注册表的响应或 package.json 内容。

  ¥pkg - The manifest of the package. Either the response from the registry or the package.json content.

• context - 步骤的上下文对象。方法 #log(msg) 允许你使用该步骤的调试日志。

  ¥context - Context object for the step. Method #log(msg) allows you to use a debug log for the step.

用法

¥Usage

示例 .pnpmfile.cjs（更改依赖的依赖）：

¥Example .pnpmfile.cjs (changes the dependencies of a dependency):

function readPackage(pkg, context) {
  // Override the manifest of foo@1.x after downloading it from the registry
  if (pkg.name === 'foo' && pkg.version.startsWith('1.')) {
    // Replace bar@x.x.x with bar@2.0.0
    pkg.dependencies = {
      ...pkg.dependencies,
      bar: '^2.0.0'
    }
    context.log('bar@1 => bar@2 in dependencies of foo')
  }
  
  // This will change any packages using baz@x.x.x to use baz@1.2.3
  if (pkg.dependencies.baz) {
    pkg.dependencies.baz = '1.2.3';
  }
  
  return pkg
}

module.exports = {
  hooks: {
    readPackage
  }
}

已知的限制

¥Known limitations

通过 readPackage 从依赖清单中删除 scripts 字段不会阻止 pnpm 构建依赖。构建依赖时，pnpm 从包的存档中读取包的 package.json，该值不受钩子影响。为了忽略包的构建，请使用 pnpm.neverBuiltDependencies 字段。

¥Removing the scripts field from a dependency's manifest via readPackage will not prevent pnpm from building the dependency. When building a dependency, pnpm reads the package.json of the package from the package's archive, which is not affected by the hook. In order to ignore a package's build, use the pnpm.neverBuiltDependencies field.

hooks.afterAllResolved(lockfile, context): lockfile | Promise<lockfile>

允许你在序列化之前更改锁定文件输出。

¥Allows you to mutate the lockfile output before it is serialized.

参数

¥Arguments

• lockfile - 序列化为 pnpm-lock.yaml 的锁定文件解析对象。

  ¥lockfile - The lockfile resolutions object that is serialized to pnpm-lock.yaml.

• context - 步骤的上下文对象。方法 #log(msg) 允许你使用该步骤的调试日志。

  ¥context - Context object for the step. Method #log(msg) allows you to use a debug log for the step.

使用示例

¥Usage example

.pnpmfile.cjs

function afterAllResolved(lockfile, context) {
  // ...
  return lockfile
}

module.exports = {
  hooks: {
    afterAllResolved
  }
}

已知限制

¥Known Limitations

There are none - 可以通过此函数修改锁定文件可以完成的任何操作，你甚至可以扩展锁定文件的功能。

¥There are none - anything that can be done with the lockfile can be modified via this function, and you can even extend the lockfile's functionality.

相关配置

¥Related Configuration

ignore-pnpmfile

• 默认：false

  ¥Default: false

• 类型：布尔值

  ¥Type: Boolean

.pnpmfile.cjs 将被忽略。当你想要确保在安装过程中不执行任何脚本时，与 --ignore-scripts 一起有用。

¥.pnpmfile.cjs will be ignored. Useful together with --ignore-scripts when you want to make sure that no script gets executed during install.

pnpmfile

• 默认：.pnpmfile.cjs

  ¥Default: .pnpmfile.cjs

• 类型：path

  ¥Type: path

• 示例：.pnpm/.pnpmfile.cjs

  ¥Example: .pnpm/.pnpmfile.cjs

本地 pnpmfile 的位置。

¥The location of the local pnpmfile.

global-pnpmfile

• 默认：null

  ¥Default: null

• 类型：path

  ¥Type: path

• 示例：~/.pnpm/global_pnpmfile.cjs

  ¥Example: ~/.pnpm/global_pnpmfile.cjs

全局 pnpmfile 的位置。安装期间所有项目都会使用全局 pnpmfile。

¥The location of a global pnpmfile. A global pnpmfile is used by all projects during installation.

注意

建议使用本地 pnpmfiles。仅当你在不使用 pnpm 作为主包管理器的项目上使用 pnpm 时，才使用全局 pnpmfile。

¥It is recommended to use local pnpmfiles. Only use a global pnpmfile if you use pnpm on projects that don't use pnpm as the primary package manager.