yarn.lock 你锁明白了吗?
共 6431字,需浏览 13分钟
·
2021-08-23 00:12
前言
你是否遇到过这种场景,项目拉下来后执行yarn install
安装依赖,yarn.lock 却提示有变更,我明明什么都没做呢,这是为啥?但是基于以往的经验(出过 case),yarn.lock 不应该有 diff 才对,一定是哪里出了问题!但是git diff yarn.lock
发现自己也看不明白(我好菜 😭)
举个 🌰
还原一下我出过的 Case 😭 项目里原本有个依赖foo
:
package.json 里定义的 foo@^1.0.1
yarn.lock 里的版本是 1.0.1
同学 A 是负责foo
这个库的开发,一次发版后,到项目里升级这个依赖到 1.1.0,但是提交代码时,只变更了 package.json,没有更新 yarn.lock
package.json foo@^1.0.1``foo@^1.1.0
yarn.lock 没变,还是 1.0.1
然后大家每次拉新代码并安装依赖后,本地总有个烦人的 yarn.lock 文件变更,大家心想应该是有人升级依赖的时候忘记提交 yarn.lock 了于是同学 B 行动了:
先看了下 foo 这个库现在有哪些版本,最新版本是 1.1.2
,跟 package.json 里定义的^1.1.0
差了两个版本,不能保证线上是1.1.0
,因为每次上线,都会去找符合^1.1.0
这个 version range 里的最新版本所以去看了下最后一次上线的构建日志,发现下载的是 1.1.2
于是提交了 yarn.lock,把版本锁在了 1.1.2
然后过了一天,拉群了 😭
1.1.2 版本有 bug,修复后发布了 1.1.3
但是项目里,由于 B 把版本锁在了 1.1.2,锁住了 bug 😭
同学 A 质问 B 为什么要锁别人的库的版本 😭
这个 case 记了几个 TODO
因为没有提交 yarn.lock,不确定同学 A 是通过 yarn upgrade
升级的版本,还是手动去改了 package.json,所以——不要手动修改 package.json 升级版本升级依赖后,一定要同时提交 package.json 和 yarn.lock
About yarn.lock
yarn.lock 的作用?
锁定唯一版本!
package.json 里定义的是版本区间,如 ^1.0.0
而 yarn.lock 里的 version
字段是唯一的版本号,如1.0.0
yarn.lock 长啥样?
里面都是一块一块的,每一块大概长下面这样:
core-js-compat@^3.0.0:
version "3.14.0"
resolved "https://registry.npmjs.org/core-js-compat/-/core-js-compat-3.14.0.tgz#b574dabf29184681d5b16357bd33d104df3d29a5"
integrity sha1-tXTavykYRoHVsWNXvTPRBN89KaU=
dependencies:
browserslist "^4.16.6"
semver "7.0.0"
Identifier(s)
第一行的core-js-compat@^3.0.0
是依赖的 identifier。和 package.json 里对应的包名和版本区间,用@
连接。这边的标题里带了(s)
,是因为多个 Identifier 最终可能都指向同一个版本(具体例子可以看下文### dependencies
里给出的例子)
version
第二行version
是实际安装的版本。通常是满足版本区间里的一个版本,比如上一行 identifier 里版本区间是^3.0.0
,这里实际安装的是3.14.0
,符合要求。但是为什么要说是“通常”呢,因为有例外,在后文### resolutions
部分会讲到。
resolved
第三行resolved
的是一个链接,是下载这个包的地址。这个 url 里的域名部分跟项目里配置的 .npmrc或你本地的 npm 配置的 registry有关。
integrity
第四行integrity
是对resolved
下载下来的文件进行完整性校验。如果出现 diff,说明同一个下载链接对应的文件被修改过。
dependencies
第五行dependencies
是这个包自己的依赖。如这里依赖的browserslist "^4.16.6"
,你想看下实际安装的哪个版本,就可以把它拼成 Identifierbrowserslist@^4.16.6"
,以此为关键字在 yarn.lock 中搜索,就能找到对应的“块”了。
browserslist@4.16.6, browserslist@^4.0.0, browserslist@^4.11.1, browserslist@^4.12.0, browserslist@^4.14.5, browserslist@^4.16.0, browserslist@^4.16.6, browserslist@^4.3.6, browserslist@^4.6.2, browserslist@^4.6.4, browserslist@^4.7.2, browserslist@^4.9.1:
version "4.16.6"
resolved "https://registry.npmjs.org/browserslist/-/browserslist-4.16.6.tgz#d7901277a5a88e554ed305b183ec9b0c08f66fa2"
integrity sha1-15ASd6WojlVO0wWxg+ybDAj2b6I=
dependencies:
caniuse-lite "^1.0.30001219"
colorette "^1.2.2"
electron-to-chromium "^1.3.723"
escalade "^3.1.1"
node-releases "^1.1.71"
上面这个例子第一行有多个 Identifiers,最终都指向第二行的version "4.16.6"
,可以检查下4.16.6
版本满足上面所有 Identifiers 里的版本区间:4.16.6
、^4.0.0
...
yarn.lock 是如何生成的?
yarn.lock 是自动生成的,你不应该去手动的修改。
依赖管理
比如我们的常规操作,都会自动更新 package.json 和 yarn.lock
新增依赖:
yarn add
升级依赖:
yarn upgrade
更多可参考https://classic.yarnpkg.com/en/docs/managing-dependencies
霸道的resolutions
假如你的项目依赖了foo
,foo
依赖了bar@^1.0.0
。假设bar
现在有两个版本1.0.0
和1.1.0
。很不幸,bar
在发布1.1.0
的时候没有做好向后兼容。导致foo
和bar@1.1.0
不能搭配使用。如果你可以等:
要么等 foo
把依赖bar
锁成1.0.0
并重新发版要么等 bar
修复兼容问题后重新发版
那如果你等不了呢,你已知foo
和bar@1.0.0
可以正常工作。如果你能锁住foo
对bar
的依赖就好了,但是这定义在foo
的 packge.json 里,你总不能去改 node_modules/foo/package.json 吧?这不合适。`resolutions`[1]可以解决你的问题,只要在你自己项目的 package.json 里定义:
"resolutions": {
"foo/bar": "1.0.0"
}
这里的 key"foo/bar"
表示foo
的直接依赖bar
,把版本区间重写成1.0.0
。如果foo
不是直接依赖的bar
(foo -> ... -> bar
),我还需要把中间的链路都捋清楚吗?不用那么麻烦!
"resolutions": {
"foo/**/bar": "1.0.0"
}
如果你的项目里有很多依赖直接/间接的依赖了bar
,每个定义的版本区间可能有差别,你知道某个版本可以让他们都能正常工作,而不用安装多个版本。也可以不用声明前缀部分,只写包名bar
。这样不管是哪里依赖到了bar
都会指向你声明的哪个版本。
"resolutions": {
"bar": "1.0.0"
}
执行yarn install
后,在 yarn.lock 里搜索bar@
:
bar@^1.0.0 bar@1.1.0 bar@^2.0.0:
version "1.0.0"
...
可以看到,resolutions
可以违背版本区间的限制,比如上例中 Identifiers 里的bar@1.1.0``bar@^2.0.0
。
如何避免出现问题?
yarn.lock 与 package.json 不 match
场景
只改动 package.json,忘记提交 yarn.lock
问题
执行yarn install
后,yarn.lock 有变更
如何解决
解决掉引入问题的人(PEACE & LOVE)
确认 diff 并提交变更后的 yarn.lock
确定是哪些依赖产生的 diff,并回归相关功能(成本有点大,而且如果依赖关系比较复杂,那是很难确认影响面的)
OR 🔐 成最后一次上线的版本(⚠️ 可能会 🔐 住 bug😭)
可以看到出现问题再解决还是很棘手的,而且有一定赌的成分,所以我们最好预防。
如何预防
即使现在项目是好的,我们是不是也应该防患于未然!
开发的同学 &&CR 共同把关 🙏🏻
阻塞构建 😈(有以下几种方案可选)
优点:简单粗暴 && 直观(不会出现因为对命令 or 参数理解存在误差造成不符合预期的情况) 缺点:慢!效率低!因为会把包括需要更新的依赖也下载完,本来应该在检测到需要更新的时候就停止的(目前没有想到什么好办法) resolutions
里修改版本,不会报错Classic yarn (version 1) 在 package.json 里移除依赖,也不会报错(v2 修复了这个问题,详见https://github.com/yarnpkg/yarn/issues/5840) `npm ci`[2]与
npm install
类似,但是在安装依赖的过程中如果发现 package-lock.json 不匹配,则会抛错并退出,而不去更新 lock file`yarn install --frozen-lockfile`[3]等价于
npm ci
,但是在测试过程中发现几个问题:✅
yarn install && git diff
`--exit-code`[4]yarn.lock
正常执行 install 命令安装依赖,再检查 lock file 有无 diff
把 lock file 删掉,整个重装
场景
当你更新了某个依赖后,发现项目跑不起来了,推测可能是依赖的问题。有没有尝试过把 yarn.lock + node_modules 都删了重新安装,幸运的话可能“问题就解决了”(解决了,但是好像没完全解决,反正项目跑起来了)
问题
把 yarn.lock 删掉后,原本锁住的版本都放开了,执行yarn install
的时候会根据 package.json 里定义的版本区间去找最新版。所以,可能会造成你预期外的依赖也被更新了,不幸的话可能会引入 bug。
解决思路
可以单独搞一个依赖empty-lock-lock
:
什么都不做(一个空的库),发版 1.0.0
定义一个 postinstall
脚本,直接抛错,发版1.0.1
在项目中安装依赖yarn add empty-lock-lock@1.0.0 --dev
,yarn.lock 里会锁定版本为1.0.0
。然后准备一个陷阱:
手动把 package.json 里的版本改成区间 ^1.0.0
手动修改 yarn.lock 里,把 Identifier 部分的 empty-lock-lock@1.0.0
也替换成empty-lock-lock@^1.0.0
修改后提交,可以再执行yarn install
验证下,yarn.lock 没有 diff,证明我们手动修改后的 package.json 和 yarn.lock 仍然是 match 的。等小白鼠上钩,如果把 yarn.lock 整个删掉了,再执行yarn install
,安装到empty-lock-lock
的时候,会根据 package.json 里定义的^1.0.0
版本区间里找最新的,这时候会找到1.0.1
版本,下载后触发postinstall
就报错啦!
THE END
希望通过本文,可以瞄到 yarn.lock 神秘的面纱下的一角,当下次再看到 yarn.lock 产生 diff 时不会那么迷茫和焦虑。如果各位大大在阅读过程中发现了问题,请务必按头改正!感恩 ❤️ 感谢团队内的小伙伴们一起探讨问题 && 提供小妙(笋)招。感恩 Plus ❤️❤️❤️
参考资料
https://robertcooper.me/post/how-yarn-lock-files-work-and-upgrading-dependencies
扩展阅读
package.json 中定义的各种依赖 🔗https://classic.yarnpkg.com/en/docs/package-json
参考资料
resolutions
: https://classic.yarnpkg.com/en/docs/selective-version-resolutions/#toc-how-to-use-it
npm ci
: https://docs.npmjs.com/cli/v7/commands/npm-ci
yarn install --frozen-lockfile
: https://stackoverflow.com/questions/58482655/what-is-the-closest-to-npm-ci-in-yarn
--exit-code
: https://git-scm.com/docs/git-diff#Documentation/git-diff.txt---exit-code