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 提交到仓库。
name 和 version 是 package.json 里最重要的两个字段,没有它们你的包无法被安装。 name 和 version 字段一起用来创建唯一 id。
{ "name": "my-awesome-package" }
这是你的包的名字。它在 URL 中、作为命令行参数、作为 node_modules 里的目录名使用。
yarn add [name]
node_modules/[name] https://registry.npmjs.org/[name]/-/[name]-[version].tgz
必须少于或等于 214 个字符(对于限定域的包来说 @scope/)。
不能以句点 (.) 或者下划线 (_) 开头。
名字里不能有大写字母。
必须只使用 URL 安全的字符。
不要使用和 Node.js 核心模块相同的名字。
不要在名字里包含 js 或者 node 单词。
短小精悍,让人看到名字就大概了解包的,记住它也会被用在 require() 里。
保证名字在 里是唯一的。
{ "version": "1.0.0" }
包的当前版本号。
信息类字段
{ "description": "我的包的简短描述" }
Description 是帮助使用者了解包的的字符串,包管理器也会把这个字符串作为关键词。
{ "keywords": ["short", "relevant", "keywords", "for", "searching"] }
关键字是字符串数组,当在包管理器里包时很有用。
{ "license": "MIT", "license": "(MIT or GPL-3.0)", "license": "SEE LICENSE IN LICENSE_FILENAME.txt", "license": "UNLICENSED" }
所有包都应该指定许可证,以便让了解他们是在什么授权下使用此包,以及此包还有哪些附加限制。
鼓励使用开源 () 许可证,除非你有特别的原因不用它。 如果你开发的包是你工作的一部分,最好和公司讨论后再做决定。
license字段必须是以下之一:
如果你使用标准的许可证,需要有效地 。
如果你用多种标准许可证,需要有效的 。
如果你使用非标准的许可证, SEE LICENSE IN <名> 字符串指向你的包里顶级目录的 <名>。
如果你不想在任何条款下授权其他人使用你的私有或未公开的包, UNLICENSED 字符串。
类字段
各种指向项目文档、issues 上报,以及托管网站的字段。
{ "homepage": "https://your-package.org" }
homepage 是包的项目主页或者文档。
{ "bugs": "https://github.com/user/repo/issues" }
问题反馈系统的 URL,或者是 email 地址之类的。通过该途径向你反馈问题。
{ "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": { "name": "Your Name", "email": "you@example.com", "url": "http://your-website.com" }, "author": "Your Name <you@example.com> (http://your-website.com)" }
作者信息,人。
{ "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": ["filename.js", "directory/", "glob/*.{js,json}"] }
项目包含的,可以是单独的、整个夹,或者符匹配到的。
{ "main": "filename.js" }
项目的入口。
{ "bin": "bin.js", "bin": { "command-name": "bin/command-name.js", "other-command": "bin/other-command" } }
随着项目一起被安装的可执行。
{ "man": "./man/doc.1", "man": ["./man/doc.1", "./man/doc.2"] }
和项目相关的文档(man page)。
{ "directories": { "lib": "path/to/lib/", "bin": "path/to/bin/", "man": "path/to/man/", "doc": "path/to/doc/", "example": "path/to/example/" } }
当你的包安装时,你可以指定确切的位置来放二进制、man pages、文档、例子等。
任务类字段
包里还可以包含一些可执行脚本或者其他配置信息。
{ "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。
{ "con": { "port": "8080" } }
配置你的脚本的选项或参数。
依赖描述类字段
你的包很可能依赖其他包。你可以在你的 package.json 里指定那些依赖。
{ "dependencies": { "package-1": "^3.1.4" } }
这些是你的包的开发版和发布版都需要的依赖。
你可以指定确切的版本、最小的版本 (比如 >=) 或者版本范围 (比如 >= ... <)。
{ "devDependencies": { "package-2": "^0.4.2" } }
这些是只在你的包开发期间需要,但是生产环境不会被安装的包。
{ "peerDependencies": { "package-3": "^2.7.18" } }
平行依赖允许你说明你的包和其他包版本的兼容性。
{ "optionalDependencies": { "package-5": "^1.6.1" } }
可选依赖可以用于你的包,但不是必需的。如果可选包没有找到,安装还可以继续。
{ "bundledDependencies": ["package-4"] }
打包依赖是发布你的包时将会一起打包的包名数组。
{ "flat": true }
如果你的包只允许给定依赖的版本,你想强制和命令行上 yarn install --flat 相同的行为,把这个值设为 true。
请注意,如果你的 package.json 包含 "flat": true 并且其它包依赖你的包 (比如你在构建库,而不是应用), 其它那些包也需要在它们的 package.json "flat": true,或者在命令行上用 yarn install --flat 安装。
{ "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" } }
允许您覆盖特定嵌套依赖项的版本。 有关完整规范,请参见。
注意,yarn install --flat 命令将会在 package.json 里加入 resolutions 字段。
系统
你可以提供和你的包关联的系统级的信息,比如操作系统兼容性之类。
{ "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": ["darwin", "linux"], "os": ["!win32"] }
此选项指定你的包的操作系统兼容性,它会检查 process.platform。
{ "": ["x64", "ia32"], "": ["!arm", "!mips"] }
使用这个选项指定你的包将只能在某些 体系架构上运行,这会检查 process.arch。
发布
{ "private": true }
如果你不想你的包发布到包管理器,设置为 true。
{ "publishCon": { ... } }
这些配置值将在你的包发布时使用。比如,你可以给包打。
在 process.env 中定义的环境变量允许您配置 Yarn 的附加。
process.env.CHILD_CONCURRENCY=#number#
控制并行执行的子进程数以构建节点模块。
将此数字设置为 1,将会按顺序构建节点模块,这样可以避免在 Windows 中使用 node-gyp 时出现器。
.yarnrc 允许你配置更多的 Yarn 。 也可以用 con 命令来配置这些选项。 Yarn 会把你的 .yarnrc merge 进树里。
yarn-offline-mirror "./packages-cache"
离线维护你的包,这样可以让你的构建过程更加稳定。
必须是个相对路径,或者用 false 来禁用镜像(认值)。
yarn-offline-mirror-pruning true
控制离线镜像的。
值必须是布尔值,认值为 false。
yarn-path "./bin/yarn"
为了执行 yarn,可以让 yarn 指向另 Yarn 的二进制。 如果把 Yarn 绑定到存储库中,并且让每个人都使用同样的的版本以保持一致性的话,这是非常有用的。 这会在 Yarn 1.0 中介绍,所以所有开发者必须安装 Yarn >= 1.0 的版本。
该值必须是相对路径,或者用 false 来禁用它(认)。
disable-self-update-check true
在安装包时,如果你的 CLI 命令过时了,Yarn 会提供更新命令。可以禁用该检查。
值必须是布尔值,认值为 false。
child-concurrency #number#
控制并行执行的子进程数以构建节点模块。
将此数字设置为 1,将会按顺序构建节点模块,这样可以避免在 Windows 中使用 node-gyp 时出现器。
在 .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 需要比你配置在 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.lock 是产生的,而且应该完全被 Yarn 管理。 当你用 Yarn CLI //依赖,它将更新你的 yarn.lock 。 不要直接编辑这个,那样很容易弄坏某些东西。
安装期间 Yarn 将只使用顶级 yarn.lock ,并会忽略任何依赖里面的 yarn.lock 。 顶级 yarn.lock 包含 Yarn 需要锁定的整个依赖树里全部包版本的所有信息。
所有 yarn.lock 应该被提交到版本控制系统(例如 git 或者 mercurial)。 这允许 Yarn 跨所有机器安装相同的依赖树,无论它是你同事的笔记本还是 CI 服务器。
框架和库的作者也应该把 yarn.lock 提交到版本控制系统。 别担心发布 yarn.lock ,因为它对库的不会有任何影响。
参见 。