Skip to main content

清单(package.json)

清单文件(也称为 package.json,因为它们的名称)包含描述特定包独有的设置所需的所有内容。如果项目使用工作区功能,则将包含多个此类清单,因为每个工作区都通过其自己的清单进行描述。请注意,可以通过 initFields 设置设置这些字段的默认值。

name

包的名称。

用于在整个应用中识别它,尤其是在多个工作区之间。名称的第一部分(此处为 @scope/)是可选的,用作命名空间)。

name: "@scope/name",

version

包的版本。

通常不会对你的项目产生任何影响,除非它是工作区 - 那么它的版本必须与指定的范围相匹配,工作区才能被选为解决方案候选。

version: "1.2.3",

packageManager

定义在处理此项目时应使用的包管理器。

Corepack 和类似工具使用此字段来检测项目中使用的 Yarn 版本 - 从某种意义上说,它与你的锁定文件具有相同的用途,但仅适用于 Yarn 本身。

Yarn 将在运行 yarn set version 时自动设置此值。

packageManager: "yarn@4.0.0",

type

定义应如何解释 .js 文件。

Node.js v13.x option。可能的值是 commonjs(默认值)和 module。无论此选项如何,Yarn 3+ 在使用 PnP 时都会生成 .pnp.cjs 文件。

type: "commonjs" | "module",

private

定义包是否要发布。

如果为 true,则该包被视为私有包,无论情况如何,Yarn 都会拒绝发布它。

private: true,

license

SPDX 标识符定义软件包分发的许可证。

license: "MIT",

os

此包工作的平台集。

process.platform() 的值将在安装时与此集合进行比较。如果未找到匹配项,则将跳过包定义的任何安装后脚本。如果通过 optionalDependencies 条目完全依赖于包,则根本不会安装包。

os: [
"linux",
"darwin",
"win32",
],

cpu

此软件包工作的 CPU 架构集。

process.arch() 的值将在安装时与此集合进行比较。如果未找到匹配项,则将跳过包定义的任何安装后脚本。如果通过 optionalDependencies 条目完全依赖于包,则根本不会安装包。

cpu: [
"x64",
"ia32",
"arm64",
],

libc

此软件包所依赖的 C 标准库集。

主机标准库将在安装时与此集合进行比较。如果未找到匹配项,则将跳过包定义的任何安装后脚本。如果通过 optionalDependencies 条目完全依赖包,则根本不会安装包。

libc: [
"glibc",
"musl",
],

main

通过裸标识符请求包时应解析的文件路径。

可以使用 publishConfig.main 字段在发布时修改此字段。

main: "./sources/index.js",

module

在 ES6 兼容的打包器环境中通过裸标识符需要包时应解析的文件的路径。

此字段应被视为已弃用,exports 是其官方替代品。

module: "./sources/index.mjs",

languageName

安装依赖时选择要使用的链接器的任意值。

这是一个内部包设置,除非你真的知道自己在做什么,否则不应触碰它。

languageName: "node",

bin

通过 yarn run bin-name 和 shell 环境公开的文件集。

如果设置为字符串,二进制值将是包名称(不包括其范围部分)。

bin: {
my-bin: "./dist/my-bin.js",
},

scripts

通过 yarn run script-name 或作为生命周期钩子公开的脚本集。

Yarn 中的脚本由类似 POSIX 的 shell 执行,该 shell 实现了你希望在单行脚本中使用的大多数功能。例如,你可以使用 POSIX 语法分配环境变量,Yarn 将使其在 Linux、OSX 和 Windows 上工作。

test: "NODE_OPTIONS='--max-old-space-size=2048' jest",
build: "webpack-cli --config ./webpack.config.js",
count-words: "echo \"$@\" | wc -w",
},

dependencies

必须提供给当前包的依赖集,以便它正常工作。

有关更多信息,请参阅 protocol documentation

webpack: "^5.0.0",
},

optionalDependencies

Yarn 仅应在 os/cpu/libc 字段与主机平台的字段匹配时尝试安装的依赖集。

与常规依赖不同,optionalDependencies 中列出的依赖允许 postinstall 步骤失败 - 事实上,如果 os/cpu/libc 过滤器不覆盖主机平台,它们甚至根本不会安装。

请注意,optionalDependencies 只关心包是否应该安装/构建 - 它仍然应该是可解析的,否则就无法判断检索包元数据失败是否是故意的。

fsevents: "^5.0.0",
},

devDependencies

必须提供给当前包的依赖集,以便它作为工作区正常工作。

与常规依赖不同,devDependencies 中列出的依赖仅在软件包作为工作区项目的一部分安装时才是必需的 - 通常通过克隆项目存储库然后在其中运行 yarn install

webpack: "^5.0.0",
},

peerDependencies

包必须从依赖树中的祖级继承的依赖集。

对等依赖的语义保证当包需要依赖时,它将返回与将返回到包祖级的对象实例完全相同的对象实例。此机制使对等依赖成为在多个包之间共享单例状态的最佳方式。

作为扩展,Yarn 支持 "peer dependencies with default":在 dependenciespeerDependencies 字段中列出的依赖将首先尝试解决对等依赖,但如果无法满足,将回退到常规依赖。

react: "*",
react-dom: "*",
},

workspaces

引用项目工作区的文件夹 glob 模式数组。

工作区是 monorepos 使用的可选功能,用于将大型项目拆分为半独立的子项目,每个子项目都列出自己的一组依赖。workspaces 字段是与应成为应用工作区的所有目录匹配的 glob 模式列表。有关更多信息,请参阅 workspaces documentation

"packages/*",
],

dependenciesMeta

影响 dependenciesdevDependencies 字段解释方式的额外设置。

在工作区项目的上下文中,大多数这些设置将影响 所有工作区,因此必须在项目的 中指定。除非另有说明,否则如果在工作区内发现 dependenciesMeta 字段,它将被忽略。

dependenciesMeta.built

定义是否运行安装后脚本。

如果为 false,则永远不会构建包(拒绝列表)。当 enableScripts yarnrc 设置关闭时,此行为会反转 - 当发生这种情况时,只会构建 built 明确设置为 true 的包(允许列表);至于那些 built 明确设置为 false 的包,他们只会看到他们的构建脚本警告降级为简单通知。

built: false,

dependenciesMeta.optional

定义依赖是否是可选的。

dependenciesMeta 中的大多数其他设置不同,optional 允许出现在依赖树的任何地方。它具有与 optionalDependencies 完全相同的效果 - 事实上,这就是 optionalDependencies 内部编译的结果。

optional: false,

dependenciesMeta.unplugged

定义包是否必须拔出。

如果为 true,则指定的包将在安装时自动拔出。这只适用于包含除 Javascript 之外的其他语言脚本的包(例如 nan 包含 C++ 标头)。

unplugged: true,
},
},

peerDependenciesMeta

影响 peerDependencies 字段解释方式的额外设置。

dependenciesMeta 不同,peerDependenciesMeta 允许出现在依赖树的任何部分。

peerDependenciesMeta.optional

定义当对等依赖无法满足时是否记录警告。

如果为 true,则包管理器将选定的对等依赖标记为可选,从而消除我们原本会触发的任何警告。

optional: true,
},
},

resolutions

覆盖特定依赖的解析。

此字段允许你指示 Yarn 使用特定解析度(特定软件包版本),而不是解析器通常选择的任何内容。这对于强制所有软件包使用依赖的单一版本或反向移植修复很有用。解析键的语法接受一个特定级别,因此以下所有示例都是正确的。

注意:当路径是相对的时,就像 file:portal: 协议一样,它是相对于项目路径解析的。

注意:resolutions 字段只能在项目的根目录中设置,如果在任何其他工作区中使用,将生成警告。

relay-compiler: "3.0.0",
},

preferUnplugged

定义包是否必须拔出。

虽然 Yarn 尝试直接从其 zip 存档中引用和加载包,但这可能并不总是可行的。启发式方法会尝试检测 zip 加载会出现问题的情况,并改为解压磁盘上的文件,但由于只是一种启发式方法,它可能会报告不正确的结果。

preferUnplugged 字段允许你作为包作者定义自己的包在存储为存档时是否有效。如果设置,它将覆盖默认的启发式方法。

files

将包含在已发布 tarball 中的文件 glob 模式数组。

文件模式遵循与 .gitignore 类似的语法,但相反:包括文件、目录或 glob 模式(***/* 等)将使文件在打包时包含在 tarball 中。省略该字段将使其默认为 ["*"],这意味着它将包含所有文件。

如果缺少此字段,Yarn 将使用项目的 .gitignore 来生成打包列表,或者如果可用则使用 .npmignore 文件。

某些特殊文件和目录也是 includedexcluded,无论它们是否存在于 files 数组中。

"dist/**/*",
"lib/**/*",
],

publishConfig

影响软件包发布方式的额外设置。

publishConfig.access

定义发布包时要使用的访问权限。

有效值为 publicrestricted,但 restricted 通常需要注册付费计划(这取决于你使用的注册表)。

access: "public" | "restricted",

publishConfig.bin

替换软件包的 bin 字段,该字段在已发布的 tarball 中用于覆盖主 tarball。

bin: "./build/bin.js",

publishConfig.browser

替换软件包的 browser 字段,该字段在已发布的 tarball 中用于覆盖主 tarball。

browser: "./build/browser.js",

publishConfig.executableFiles

必须在已发布的 tarball 中标记为可执行 (+x) 的文件集。

"./dist/shim.js",
],

publishConfig.main

替换软件包的 main 字段,该字段在已发布的 tarball 中用于覆盖主 tarball。

main: "./build/index.js",

publishConfig.module

替换软件包的 module 字段,该字段在已发布的 tarball 中用于覆盖主 tarball。

module: "./build/index.mjs",

publishConfig.registry

如果存在,当包即将被推送到远程位置时,将替换配置中定义的任何注册表。

registry: "https://npm.pkg.github.com",

publishConfig.type

替换软件包的 type 字段,该字段在已发布的 tarball 中用于覆盖主 tarball。

type: "./build/index.d.ts",
},

installConfig

影响软件包安装方式的额外设置。

installConfig.hoistingLimits

定义可以提升包的最高点。

有关更多信息,请参阅 nmHoistingLimits

hoistingLimits: "workspaces" | "dependencies" | "none",

installConfig.selfReferences

定义工作区是否允许自己要求。

有关更多信息,请参阅 nmSelfReferences

},