Yarn 配置
使用Yarn中需要了解Yarn 配置的操作方法。
接下来通过讲解Yarn 配置中会用到的文件：package.json、envvars、.yarnrc、yarn.lock，一一进行详细的解答。
配置你的包
Yarn 使用 package.json 文件来标识每个包，并配置 yarn 在那个包里的运行方式。
pet-kitten 包的配置可以在 pet-kitten/package.json 找到：
{
"name": "pet-kitten",
"version": "0.1.0",
"main": "pet.js",
"dependencies": {
"hand": "1.0.0"
}
}
使用 yarn.lock 文件来固化依赖
除了 package.json 文件，yarn 也使用 <0>yarn.lock</0> 文件来确保依赖解析又快又稳。 你无需编辑这个文件，yarn自己搞定。
为了保证你应用的行为保持一致，你应该把 yarn.lock 文件提交到代码仓库。
package.json
name 和 version 是 package.json 文件里最重要的两个字段，没有它们你的包无法被安装。 name 和 version 字段一起用来创建一个唯一 id。
name
{
"name": "my-awesome-package"
}
这是你的包的名字。它在 URL 中、作为命令行参数、作为 node_modules 里的目录名使用。
yarn add [name]
node_modules/[name] https://registry.npmjs.org/[name]/-/[name]-[version].tgz
规则
必须少于或等于 214 个字符（对于限定域的包来说包括 @scope/）。
不能以句点 (.) 或者下划线 (_) 开头。
名字里不能有大写字母。
必须只使用 URL 安全的字符。
Tips
不要使用和 Node.js 核心模块相同的名字。
不要在名字里包含 js 或者 node 单词。
短小精悍，让人看到名字就大概了解包的功能，记住它也会被用在 require() 调用里。
保证名字在 registry 里是唯一的。
version
{
"version": "1.0.0"
}
包的当前版本号。
信息类字段
description
{
"description": "我的包的简短描述"
}
Description 是帮助使用者了解包的功能的字符串，包管理器也会把这个字符串作为搜索关键词。
keywords
{
"keywords": ["short", "relevant", "keywords", "for", "searching"]
}
关键字是一个字符串数组，当在包管理器里搜索包时很有用。
license
{
"license": "MIT",
"license": "(MIT or GPL-3.0)",
"license": "SEE LICENSE IN LICENSE_FILENAME.txt",
"license": "UNLICENSED"
}
所有包都应该指定许可证，以便让用户了解他们是在什么授权下使用此包，以及此包还有哪些附加限制。
鼓励使用开源 (OSI-approved) 许可证，除非你有特别的原因不用它。 如果你开发的包是你工作的一部分，最好和公司讨论后再做决定。
license字段必须是以下之一：
如果你使用标准的许可证，需要一个有效地 SPDX 许可证标识。
如果你用多种标准许可证，需要有效的 SPDX 许可证表达式2.0语法表达式。
如果你使用非标准的许可证，一个 SEE LICENSE IN <文件名> 字符串指向你的包里顶级目录的一个 <文件名>。
如果你不想在任何条款下授权其他人使用你的私有或未公开的包，一个 UNLICENSED 字符串。
链接类字段
各种指向项目文档、issues 上报，以及代码托管网站的链接字段。
homepage
{
"homepage": "https://your-package.org"
}
homepage 是包的项目主页或者文档首页。
bugs
{
"bugs": "https://github.com/user/repo/issues"
}
问题反馈系统的 URL，或者是 email 地址之类的链接。用户通过该途径向你反馈问题。
repository
{
"repository": { "type": "git", "url": "https://github.com/user/repo.git" },
"repository": "github:user/repo",
"repository": "gitlab:user/repo",
"repository": "bitbucket:user/repo",
"repository": "gist:a1b2c3d4e5f"
}
repository 是代码托管的位置。
项目维护类字段
项目的维护者。
author
{
"author": {
"name": "Your Name",
"email": "you@example.com",
"url": "http://your-website.com"
},
"author": "Your Name <you@example.com> (http://your-website.com)"
}
作者信息，一个人。
contributors
{
"contributors": [
{ "name": "Your Friend", "email": "friend@example.com", "url": "http://friends-website.com" }
{ "name": "Other Friend", "email": "other@example.com", "url": "http://other-website.com" }
],
"contributors": [
"Your Friend <friend@example.com> (http://friends-website.com)",
"Other Friend <other@example.com> (http://other-website.com)"
]
}
贡献者信息，可能很多人。
文件类信息
指定包含在项目中的文件，以及项目的入口文件。
files
{
"files": ["filename.js", "directory/", "glob/*.{js,json}"]
}
项目包含的文件，可以是单独的文件、整个文件夹，或者通配符匹配到的文件。
main
{
"main": "filename.js"
}
项目的入口文件。
bin
{
"bin": "bin.js",
"bin": {
"command-name": "bin/command-name.js",
"other-command": "bin/other-command"
}
}
随着项目一起被安装的可执行文件。
man
{
"man": "./man/doc.1",
"man": ["./man/doc.1", "./man/doc.2"]
}
和项目相关的文档页面（man page）。
directories
{
"directories": {
"lib": "path/to/lib/",
"bin": "path/to/bin/",
"man": "path/to/man/",
"doc": "path/to/doc/",
"example": "path/to/example/"
}
}
当你的包安装时，你可以指定确切的位置来放二进制文件、man pages、文档、例子等。
任务类字段
包里还可以包含一些可执行脚本或者其他配置信息。
scripts
{
"scripts": {
"build-project": "node build-project.js"
}
}
脚本是定义自动化开发相关任务的好方法，比如使用一些简单的构建过程或开发工具。 在 "scripts" 字段里定义的脚本，可以通过 yarn run <script> 命令来执行。 例如，上述 build-project 脚本可以通过 yarn run build-project 调用，并执行 node build-project.js。
有一些特殊的脚本名称。 如果定义了 preinstall 脚本，它会在包安装前被调用。 出于兼容性考虑，install、postinstall 和 prepublish 脚本会在包完成安装后被调用。
start 脚本的默认值为 node server.js。
config
{
"config": {
"port": "8080"
}
}
配置你的脚本的选项或参数。
依赖描述类字段
你的包很可能依赖其他包。你可以在你的 package.json 文件里指定那些依赖。
dependencies
{
"dependencies": {
"package-1": "^3.1.4"
}
}
这些是你的包的开发版和发布版都需要的依赖。
你可以指定一个确切的版本、一个最小的版本 (比如 >=) 或者一个版本范围 (比如 >= ... <)。
devDependencies
{
"devDependencies": {
"package-2": "^0.4.2"
}
}
这些是只在你的包开发期间需要，但是生产环境不会被安装的包。
peerDependencies
{
"peerDependencies": {
"package-3": "^2.7.18"
}
}
平行依赖允许你说明你的包和其他包版本的兼容性。
optionalDependencies
{
"optionalDependencies": {
"package-5": "^1.6.1"
}
}
可选依赖可以用于你的包，但不是必需的。如果可选包没有找到，安装还可以继续。
bundledDependencies
{
"bundledDependencies": ["package-4"]
}
打包依赖是发布你的包时将会一起打包的一个包名数组。
flat
{
"flat": true
}
如果你的包只允许给定依赖的一个版本，你想强制和命令行上 yarn install --flat 相同的行为，把这个值设为 true。
请注意，如果你的 package.json 包含 "flat": true 并且其它包依赖你的包 (比如你在构建一个库，而不是应用)， 其它那些包也需要在它们的 package.json 加上 "flat": true，或者在命令行上用 yarn install --flat 安装。
resolutions
{
"resolutions": {
"transitive-package-1": "0.0.29",
"transitive-package-2": "file:./local-forks/transitive-package-2",
"dependencies-package-1/transitive-package-3": "^2.1.1"
}
}
允许您覆盖特定嵌套依赖项的版本。 有关完整规范，请参见选择性版本解析 RFC。
注意，yarn install --flat 命令将会自动在 package.json 文件里加入 resolutions 字段。
系统
你可以提供和你的包关联的系统级的信息，比如操作系统兼容性之类。
engines
{
"engines": {
"node": ">=4.4.7 <7.0.0",
"zlib": "^1.2.8",
"yarn": "^0.14.0"
}
}
engines 指定使用你的包客户必须使用的版本，这将检查 process.versions 以及当前 yarn 版本。
此检查遵守正常的 semver 规则，但有一个例外。 It allows prerelease versions to match semvers that do not explicitly specify a prerelease. For example, 1.4.0-rc.0 matches >=1.3.0, while it would not match a typical semver check.
os
{
"os": ["darwin", "linux"],
"os": ["!win32"]
}
此选项指定你的包的操作系统兼容性，它会检查 process.platform。
cpu
{
"cpu": ["x64", "ia32"],
"cpu": ["!arm", "!mips"]
}
使用这个选项指定你的包将只能在某些 CPU 体系架构上运行，这会检查 process.arch。
发布
private
{
"private": true
}
如果你不想你的包发布到包管理器，设置为 true。
publishConfig
{
"publishConfig": {
...
}
}
这些配置值将在你的包发布时使用。比如，你可以给包打标签。
envvars
在 process.env 中定义的环境变量允许您配置 Yarn 的附加功能。
CHILD_CONCURRENCY
process.env.CHILD_CONCURRENCY=#number#
控制并行执行的子进程数以构建节点模块。
将此数字设置为 1，将会按顺序构建节点模块，这样可以避免在 Windows 中使用 node-gyp 时出现链接器错误。
.yarnrc
.yarnrc 文件允许你配置更多的 Yarn 功能。 也可以用 config 命令来配置这些选项。 Yarn 会把你的 .yarnrc merge 进文件树里。
yarn-offline-mirror
yarn-offline-mirror "./packages-cache"
离线维护你的包，这样可以让你的构建过程更加稳定。
必须是个相对路径，或者用 false 来禁用镜像（默认值）。
yarn-offline-mirror-pruning
yarn-offline-mirror-pruning true
控制离线镜像的自动删除。
值必须是一个布尔值，默认值为 false。
yarn-path
yarn-path "./bin/yarn"
为了执行 yarn，可以让 yarn 指向另一个 Yarn 的二进制文件。 如果把 Yarn 绑定到存储库中，并且让每个人都使用同样的的版本以保持一致性的话，这是非常有用的。 这会在 Yarn 1.0 中介绍，所以所有开发者必须安装 Yarn >= 1.0 的版本。
该值必须是相对路径，或者用 false 来禁用它（默认）。
disable-self-update-check
disable-self-update-check true
在安装包时，如果你的 CLI 命令过时了，Yarn 会提供更新命令。可以在这里禁用该检查。
值必须是一个布尔值，默认值为 false。
child-concurrency
child-concurrency #number#
控制并行执行的子进程数以构建节点模块。
将此数字设置为 1，将会按顺序构建节点模块，这样可以避免在 Windows 中使用 node-gyp 时出现链接器错误。
CLI 参数
在 .yarnrc 设置 --<command>.<flag> <value> 和执行 yarn <command> --<flag> <value> 一样。
示例︰
$> cat .yarnrc --install.check-files true
和执行 yarn install --check-files 一样
示例 2：
$> cat .yarnrc --cache-folder /tmp/yarn-cache/ $> yarn cache dir /tmp/yarn-cache/v1
yarn.lock
为了跨机器安装得到一致的结果，Yarn 需要比你配置在 package.json 中的依赖列表更多的信息。 Yarn 需要准确存储每个安装的依赖是哪个版本。
为了做到这样，Yarn 使用一个你项目根目录里的 yarn.lock 文件。这些 “lockfile” 看起来像这样的：
# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.# yarn lockfile v1package-1@^1.0.0: version "1.0.3" resolved "https://registry.npmjs.org/package-1/-/package-1-1.0.3.tgz#a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0"package-2@^2.0.0: version "2.0.1" resolved "https://registry.npmjs.org/package-2/-/package-2-2.0.1.tgz#a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0" dependencies: package-4 "^4.0.0"package-3@^3.0.0: version "3.1.9" resolved "https://registry.npmjs.org/package-3/-/package-3-3.1.9.tgz#a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0" dependencies: package-4 "^4.5.0"package-4@^4.0.0, package-4@^4.5.0: version "4.6.3" resolved "https://registry.npmjs.org/package-4/-/package-4-2.6.3.tgz#a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0"
这可以媲美其他像 Bundler 或 Cargo 这样的包管理器的 lockfiles。它类似于 npm 的 npm-shrinkwrap.json，然而他并不是有损的并且它能创建可重现的结果。
用 Yarn 管理
你的 yarn.lock 文件是自动产生的，而且应该完全被 Yarn 管理。 当你用 Yarn CLI 增加／升级／删除依赖，它将自动更新你的 yarn.lock 文件。 不要直接编辑这个文件，那样很容易弄坏某些东西。
只用于当前包
安装期间 Yarn 将只使用顶级 yarn.lock 文件，并会忽略任何依赖里面的 yarn.lock 文件。 顶级 yarn.lock 包含 Yarn 需要锁定的整个依赖树里全部包版本的所有信息。
提交到版本控制系统
所有 yarn.lock 文件应该被提交到版本控制系统（例如 git 或者 mercurial）。 这允许 Yarn 跨所有机器安装相同的依赖树，无论它是你同事的笔记本还是 CI 服务器。
框架和库的作者也应该把 yarn.lock 提交到版本控制系统。 别担心发布 yarn.lock 文件，因为它对库的用户不会有任何影响。