清单(package.json)
清单文件(也称为 package.json
,因为它们的名称)包含描述特定包独有的设置所需的所有内容。如果项目使用工作区功能,则将包含多个此类清单,因为每个工作区都通过其自己的清单进行描述。请注意,可以通过 initFields
设置设置这些字段的默认值。
name
包的名称。
用于在整个应用中识别它,尤其是在多个工作区之间。名称的第一部分(此处为 @scope/
)是可选的,用作命名空间)。
version
包的版本。
通常不会对你的项目产生任何影响,除非它是工作区 - 那么它的版本必须与指定的范围相匹配,工作区才能被选为解决方案候选。
packageManager
定义在处理此项目时应使用的包管理器。
Corepack 和类似工具使用此字段来检测项目中使用的 Yarn 版本 - 从某种意义上说,它与你的锁定文件具有相同的用途,但仅适用于 Yarn 本身。
Yarn 将在运行 yarn set version
时自动设置此值。
type
定义应如何解释 .js
文件。
Node.js v13.x option。可能的值是 commonjs
(默认值)和 module
。无论此选项如何,Yarn 3+ 在使用 PnP 时都会生成 .pnp.cjs
文件。
private
定义包是否要发布。
如果为 true,则该包被视为私有包,无论情况如何,Yarn 都会拒绝发布它。
license
SPDX 标识符定义软件包分发的许可证。
os
此包工作的平台集。
process.platform()
的值将在安装时与此集合进行比较。如果未找到匹配项,则将跳过包定义的任何安装后脚本。如果通过 optionalDependencies
条目完全依赖于包,则根本不会安装包。
cpu
此软件包工作的 CPU 架构集。
process.arch()
的值将在安装时与此集合进行比较。如果未找到匹配项,则将跳过包定义的任何安装后脚本。如果通过 optionalDependencies
条目完全依赖于包,则根本不会安装包。
libc
此软件包所依赖的 C 标准库集。
主机标准库将在安装时与此集合进行比较。如果未找到匹配项,则将跳过包定义的任何安装后脚本。如果通过 optionalDependencies
条目完全依赖包,则根本不会安装包。
main
通过裸标识符请求包时应解析的文件路径。
可以使用 publishConfig.main
字段在发布时修改此字段。
module
在 ES6 兼容的打包器环境中通过裸标识符需要包时应解析的文件的路径。
此字段应被视为已弃用,exports
是其官方替代品。
languageName
安装依赖时选择要使用的链接器的任意值。
这是一个内部包设置,除非你真的知道自己在做什么,否则不应触碰它。
bin
通过 yarn run bin-name
和 shell 环境公开的文件集。
如果设置为字符串,二进制值将是包名称(不包括其范围部分)。
scripts
通过 yarn run script-name
或作为生命周期钩子公开的脚本集。
Yarn 中的脚本由类似 POSIX 的 shell 执行,该 shell 实现了你希望在单行脚本中使用的大多数功能。例如,你可以使用 POSIX 语法分配环境变量,Yarn 将使其在 Linux、OSX 和 Windows 上工作。
dependencies
必须提供给当前包的依赖集,以便它正常工作。
有关更多信息,请参阅 protocol documentation。
optionalDependencies
Yarn 仅应在 os/cpu/libc 字段与主机平台的字段匹配时尝试安装的依赖集。
与常规依赖不同,optionalDependencies
中列出的依赖允许 postinstall
步骤失败 - 事实上,如果 os/cpu/libc 过滤器不覆盖主机平台,它们甚至根本不会安装。
请注意,optionalDependencies
只关心包是否应该安装/构建 - 它仍然应该是可解析的,否则就无法判断检索包元数据失败是否是故意的。
devDependencies
必须提供给当前包的依赖集,以便它作为工作区正常工作。
与常规依赖不同,devDependencies
中列出的依赖仅在软件包作为工作区项目的一部分安装时才是必需的 - 通常通过克隆项目存储库然后在其中运行 yarn install
。
peerDependencies
包必须从依赖树中的祖级继承的依赖集。
对等依赖的语义保证当包需要依赖时,它将返回与将返回到包祖级的对象实例完全相同的对象实例。此机制使对等依赖成为在多个包之间共享单例状态的最佳方式。
作为扩展,Yarn 支持 "默认的同级依赖":在 dependencies
和 peerDependencies
字段中列出的依赖将首先尝试解决对等依赖,但如果无法满足,将回退到常规依赖。
workspaces
引用项目工作区的文件夹 glob 模式数组。
工作区是 monorepos 使用的可选功能,用于将大型项目拆分为半独立的子项目,每个子项目都列出自己的一组依赖。workspaces
字段是与应成为应用工作区的所有目录匹配的 glob 模式列表。有关更多信息,请参阅 workspaces documentation。
dependenciesMeta
影响 dependencies
和 devDependencies
字段解释方式的额外设置。
在工作区项目的上下文中,大多数这些设置将影响 所有工作区,因此必须在项目的 根 中指定。除非另有说明,否则如果在工作区内发现 dependenciesMeta
字段,它将被忽略。
dependenciesMeta.built
定义是否运行安装后脚本。
如果为 false,则永远不会构建包(拒绝列表)。当 enableScripts
yarnrc 设置关闭时,此行为会反转 - 当发生这种情况时,只会构建 built
明确设置为 true
的包(允许列表);至于那些 built
明确设置为 false
的包,他们只会看到他们的构建脚本警告降级为简单通知。
dependenciesMeta.optional
定义依赖是否是可选的。
与 dependenciesMeta
中的大多数其他设置不同,optional
允许出现在依赖树的任何地方。它具有与 optionalDependencies
完全相同的效果 - 事实上,这就是 optionalDependencies
内部编译的结果。
dependenciesMeta.unplugged
定义包是否必须拔出。
如果为 true,则指定的包将在安装时自动拔出。这只适用于包含除 Javascript 之外的其他语言脚本的包(例如 nan
包含 C++ 标头)。
peerDependenciesMeta
影响 peerDependencies
字段解释方式的额外设置。
与 dependenciesMeta
不同,peerDependenciesMeta
允许出现在依赖树的任何部分。
peerDependenciesMeta.optional
定义当对等依赖无法满足时是否记录警告。
如果为 true,则包管理器将选定的对等依赖标记为可选,从而消除我们原本会触发的任何警告。
resolutions
覆盖特定依赖的解析。
此字段允许你指示 Yarn 使用特定解析度(特定软件包版本),而不是解析器通常选择的任何内容。这对于强制所有软件包使用依赖的单一版本或反向移植修复很有用。解析键的语法接受一个特定级别,因此以下所有示例都是正确的。
注意:当路径是相对的时,就像 file:
和 portal:
协议一样,它是相对于项目路径解析的。
注意:resolutions
字段只能在项目的根目录中设置,如果在任何其他工作区中使用,将生成警告。
preferUnplugged
定义包是否必须拔出。
虽然 Yarn 尝试直接从其 zip 存档中引用和加载包,但这可能并不总是可行的。启发式方法会尝试检测 zip 加载会出现问题的情况,并改为解压磁盘上的文件,但由于只是一种启发式方法,它可能会报告不正确的结果。
preferUnplugged
字段允许你作为包作者定义自己的包在存储为存档时是否有效。如果设置,它将覆盖默认的启发式方法。
publishConfig
影响软件包发布方式的额外设置。
publishConfig.access
定义发布包时要使用的访问权限。
有效值为 public
和 restricted
,但 restricted
通常需要注册付费计划(这取决于你使用的注册表)。
publishConfig.bin
替换软件包的 bin
字段,该字段在已发布的 tarball 中用于覆盖主 tarball。
publishConfig.browser
替换软件包的 browser
字段,该字段在已发布的 tarball 中用于覆盖主 tarball。
publishConfig.executableFiles
必须在已发布的 tarball 中标记为可执行 (+x) 的文件集。
publishConfig.main
替换软件包的 main
字段,该字段在已发布的 tarball 中用于覆盖主 tarball。
publishConfig.module
替换软件包的 module
字段,该字段在已发布的 tarball 中用于覆盖主 tarball。
publishConfig.provenance
定义在发布时是否为包生成 provenance 声明。覆盖所有其他 provenance 设置。
publishConfig.registry
如果存在,当包即将被推送到远程位置时,将替换配置中定义的任何注册表。
publishConfig.type
替换软件包的 type
字段,该字段在已发布的 tarball 中用于覆盖主 tarball。
installConfig
影响软件包安装方式的额外设置。
installConfig.hoistingLimits
定义可以提升包的最高点。
有关更多信息,请参阅 nmHoistingLimits
。
installConfig.selfReferences
定义工作区是否允许自己要求。
有关更多信息,请参阅 nmSelfReferences
。