清单(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 支持 "peer dependencies with default":在 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.registry
如果存在,当包即将被推送到远程位置时,将替换配置中定义的任何注册表。
publishConfig.type
替换软件包的 type
字段,该字段在已发布的 tarball 中用于覆盖主 tarball。
installConfig
影响软件包安装方式的额外设置。
installConfig.hoistingLimits
定义可以提升包的最高点。
有关更多信息,请参阅 nmHoistingLimits
。
installConfig.selfReferences
定义工作区是否允许自己要求。
有关更多信息,请参阅 nmSelfReferences
。