dsh 插件版本锁定，决定了你的插件集合是「能照原样重建」还是「只能口头描述一遍」。这篇讲团队真的能坚持下来的 lockfile 最佳实践、如何在不把自己挡在补丁之外的前提下锁定插件版本范围、caret 与 tilde 版本符号在 dsh 清单里到底做了什么，以及让一次可复现的插件安装在一台新机器上成立的那几步。
为什么精确版本胜过版本范围
版本范围是一句关于未来的承诺，而插件风险恰好住在未来里。当你的清单写着「2.x 都行」，你其实已经提前同意了维护者接下来发布的任何东西，包括那个改了安装脚本、或者悄悄加了一个依赖的版本。你上个月评过分的那个插件，不是你今天装到的那个。
精确版本把这个关系反过来。索引里的评分绑定在某个版本上，公告也绑定在某个版本上，你的安装就该绑在同一个版本上。这条链上每一环的强度，取决于最松的那一环，而一个没锁定的清单永远是最松的那一环。
团队能坚持的 lockfile 最佳实践
- 把 lockfile 提交进仓库。只存在于某台笔记本上的 lockfile 是一张便条，不是构建输入。
- lockfile 的 diff 单独看。一次改动四十个版本的 diff 是一场讨论，不是一个顺手通过的勾选。
- 记下插件名、精确版本号，以及你批准时看到的评分。三个字段，就能回答半年后你真正会被问到的那个问题。
- 有意识地重新锁定。一次只升一个插件，对新版本跑一遍扫描，再提交。批量刷新会把唯一重要的那次改动藏起来。
- 保留上一版 lockfile。最快的回滚是你手上已经有的那个文件，[如何在不弄坏环境的前提下更新 dsh 插件](/blog/how-to-update-dsh-plugins-without-breaking-your-setup) 讲了完整的顺序。
如何锁定插件版本范围
锁定不等于永远不动。真正有用的中间地带是有边界的范围：宽到能收补丁，窄到次版本发布不可能没人看一眼就落地。
| 清单写法 | 会装到什么 | 什么时候用 |
|---|---|---|
| 1.4.2 | 永远只有 1.4.2 | 生产环境、CI，以及任何能碰到凭据的地方 |
| ~1.4.2 | 1.4.x 的补丁 | 补丁节奏稳定、评分不错的插件 |
| ^1.4.2 | 任意 1.x 版本 | 本地工具，绝不能用于共享构建 |
| latest | 今天存在的任何版本 | 任何你还愿意称之为构建的场景都别用 |
caret 与 tilde 版本符号
这两个符号经常被搞混，差别其实只在版本号里的哪一位。tilde 守住你写到的最后一位，只让末位动；caret 守住第一个非零位，后面全部可以动。
| 写法 | 接受 | 拒绝 |
|---|---|---|
| ~1.4.2 | 1.4.9 | 1.5.0 |
| ^1.4.2 | 1.9.0 | 2.0.0 |
| ^0.4.2 | 0.4.7 | 0.5.0 |
| 1.4.2 | 其它都不接受 | 其余全部 |
坑在 0.x 这一行。caret 作用在 0.4.2 上时表现得和 tilde 一样，因为开头的零意味着接口还没稳定。以为「caret 总是允许次版本升级」的团队，通常就是在这里第一次翻车。
怎样做到可复现的插件安装
- 从 lockfile 开始，别从 README 开始。文档里写的安装命令是建议，lockfile 才是事实。
- 每季度在一台干净的机器或容器上完整装一次。从没验证过的可复现性，只是一个假设。
- 装完之后再验证，而不是装之前。对你真正装到的那个版本跑一遍评分，因为[依赖混淆](/blog/dependency-confusion)和镜像漂移都会产出一个「名字对得上、其它都对不上」的包。
- 把配置和 lockfile 一起做快照。只锁版本、不做[配置备份](/blog/backup-dsh-plugin-configuration)，结果是装对了插件、配错了设置。
- 每一次版本变动都要过闸门，降级也算。只在首次安装时生效的[白名单](/blog/setting-up-a-plugin-allowlist-for-your-dev-team)，等于把更新这条路敞着。
锁定的版本，是关于某一个制品在某一时刻的一项声明。让它可重复的，是 lockfile。
常见问题
- 锁定会不会让我收不到安全修复？会让你不再「悄悄」收到。修复照样会来，只是以一份可以评审的 diff 的形式来，而不是一夜之间变了。
- 是不是每个插件都要锁到精确版本？凡是在共享路径或自动化路径上的，是的。用完就扔的本地工具留个 tilde 范围，省得折腾。
- 维护者不再发布我锁定的那个版本怎么办？这是个决策点，不是 bug。要么让新版本走一遍正常闸门，要么规划退出方案。
- 怎么确认我装上的就是我评过分的那个版本？对已安装版本重跑一遍检查。扫描怎么做的写在 /blog/how-install-script-scanning-works。
- 有了 lockfile 还需要评分吗？需要。评分告诉你某个版本值不值得装，lockfile 告诉你你装的还是不是那个版本。
dshquality.com 上每个插件页都会写明评分适用于哪些版本，所以照着 / 的索引把版本锁在评过分的那一版，就是复制一下的事。版本随时间的变化在 /blog/dsh-plugin-score-trends-what-a-dropping-score-means，团队级闸门在 /blog/plugin-supply-chain-security-team-enforcement，其余文章都在 /blog。