本文介绍一种通过 MITM 代理拦截并过滤 npm 注册表响应的方式，使 Yarn 在执行 yarn install 时仅感知指定日期前发布的包版本，从而精准复现历史 yarn.lock 文件，适用于调试已消失的依赖相关 Bug。
本文介绍一种通过 mitm 代理拦截并过滤 npm 注册表响应的方式，使 yarn 在执行 `yarn install` 时仅感知指定日期前发布的包版本，从而精准复现历史 yarn.lock 文件，适用于调试已消失的依赖相关 bug。
在现代前端工程实践中，yarn.lock 是保障依赖可重现性的核心文件。但当该文件未被提交（如误删、CI 环境未保留或团队规范缺失），而你又需复现一个仅存在于旧依赖组合下的 Bug（例如 fig-components@1.0.6 引发的渲染异常），直接运行 yarn install 将始终拉取最新兼容版本（如 1.0.8），导致问题无法复现。
Yarn 本身不提供原生命令（如 yarn install --as-of 2023-12-31）来按时间戳解析语义化版本范围（如 ^1.0.0）。根本原因在于：NPM/Yarn 注册表返回的包元数据（/fig-components）默认包含所有历史版本及对应发布时间（time 字段），客户端仅根据 dist-tags.latest 和 versions 对象做本地解析——它不会主动“回溯”版本发布时间。
因此，可行解法是在请求链路中注入时间过滤逻辑：通过中间人（MITM）代理劫持对 registry 的 HTTP(S) 请求，动态裁剪响应体中的 versions 和 time 字段，仅保留截止某时间点前发布的版本。以下为完整实践方案：
✅ 步骤一：编写 mitmproxy 插件（Python）
创建 plugin.py，强制注册表返回完整元数据格式，并移除超期版本：
from mitmproxy import http
import json
def request(flow: http.HTTPFlow):
# 确保获取含 'time' 字段的完整元数据（避免 install-v1+json 精简格式）
flow.request.headers["Accept"] = "application/json"
def response(flow: http.HTTPFlow):
if not flow.response or "application/json" not in flow.response.headers.get("Content-Type", ""):
return
try:
pkg = json.loads(flow.response.content)
# ⚠️ 设置目标截止时间（ISO 8601 格式，注意时区一致性）
maxdate = "2023-12-31T23:59:59.999Z"
# 过滤掉发布时间晚于 maxdate 的所有版本
versions_to_remove = {
v for v, t in pkg.get("time", {}).items()
if t and isinstance(t, str) and t >= maxdate
}
for v in versions_to_remove:
pkg["versions"].pop(v, None)
# 更新 latest tag 指向剩余最新版（按字典序，适用于纯数字版本）
if pkg["versions"]:
pkg["dist-tags"]["latest"] = max(pkg["versions"].keys())
# 移除 time 字段避免 Yarn 内部逻辑干扰（非必需但更干净）
pkg.pop("time", None)
flow.response.text = json.dumps(pkg)
except Exception as e:
print(f"[mitm] Error processing {flow.request.url}: {e}")
? 关键说明：
max(pkg["versions"].keys())依赖版本号为纯数字格式（如1.0.6 ）；若含预发布标签（1.0.0-beta.1），建议改用semver.sort()（需额外引入库）。
✅ 步骤二：启动 mitmproxy 容器
docker run --rm -it -p 1234:8080 \ -v "$(pwd)/plugin.py:/tmp/plugin.py" \ mitmproxy/mitmproxy mitmdump -s /tmp/plugin.py
? 使用
mitmdump（无 UI）更轻量；确保宿主机1234端口未被占用。
✅ 步骤三：配置 Yarn 使用代理
在项目根目录创建 .yarnrc（或修改现有文件）：
# 强制走本地代理 https-proxy "http://localhost:1234" # 绕过自签名证书警告（mitmproxy 默认使用自签证书） strict-ssl false # 可选：加速首次安装（跳过完整性校验，调试阶段可接受） ignore-scripts false
⚠️ 安全提示：生产环境切勿设置 strict-ssl false；如需长期使用，应为 mitmproxy 配置可信 CA 证书 并将根证书导入系统信任库。
✅ 步骤四：生成历史 lockfile
# 清理现有 node_modules 和 lockfile（如有） rm -rf node_modules yarn.lock # 执行安装 —— 此时所有 registry 请求均经代理过滤 yarn install
终端将显示代理捕获的请求日志，yarn.lock 中 fig-components 的解析结果将严格限定在 2023-12-31 前发布的版本（即 1.0.6），完美匹配历史环境。
? 注意事项与优化建议
-
版本排序可靠性：本方案假设
max(versions.keys())能正确选出最新可用版。对于复杂版本（含-alpha,-rc），建议升级插件逻辑，集成semver库进行语义化比较。 - 性能影响：代理增加单次请求延迟，大型项目首次安装可能明显变慢；建议仅在调试时启用。
-
Yarn 版本兼容性：已验证 Yarn v1.22.19；Yarn Berry（v3+）因使用 PnP 和不同网络栈，需另行适配（推荐改用
yarn set version锁定 Yarn 自身版本 +yarn install --immutable配合历史镜像）。 -
替代方案权衡：
- ✅ npm +
--registry镜像：若存在历史 registry 快照（如 Verdaccio 归档），可直接切换 registry； - ❌ 手动编辑
package.json：对多层嵌套依赖不现实，且易遗漏间接依赖； - ⚠️
resolutions强制指定：需遍历整个依赖树，维护成本高，且无法覆盖peerDependencies解析逻辑。
- ✅ npm +
此方法本质是“时间旅行式依赖解析”，虽需额外工具链，却是目前最通用、最可控的解决方案。掌握它，你便拥有了在任意时间点重建确定性构建环境的能力——这是可重现性工程的真正基石。
