yarn install --frozen-lockfile 报错如何解决？

Question

使用 `yarn install --frozen-lockfile` 时，常见报错为“Your lockfile needs to be updated, but yarn.lock is readonly”。该问题通常发生在 CI/CD 环境中，当 `node_modules` 与 `yarn.lock` 文件依赖版本不一致，或本地未生成 `yarn.lock` 文件时触发。`--frozen-lockfile` 选项要求 Yarn 不允许自动生成或更新锁文件，任何潜在的锁文件变更都会导致安装失败。解决方法包括：确保提交最新的 `yarn.lock` 文件到版本控制；在运行命令前避免执行 `yarn add` 或 `yarn upgrade`；检查 `package.json` 是否有未同步的依赖变更。本地可先运行 `yarn install` 生成一致的锁文件，确认无误后再提交，以避免冻结安装时报错。

Answer 1

深入解析 Yarn 冻结锁文件机制与 CI/CD 中的常见问题

1. 问题背景：什么是 --frozen-lockfile？

yarn install --frozen-lockfile 是 Yarn 提供的一个严格安装模式，用于确保依赖安装过程完全基于现有的 yarn.lock 文件，不允许任何对锁文件的修改或自动生成。

该选项常用于 CI/CD 流水线中，以防止因依赖版本漂移导致构建不一致。一旦检测到 package.json 与 yarn.lock 不匹配，Yarn 将抛出错误：

Your lockfile needs to be updated, but yarn.lock is readonly

此错误的本质是 Yarn 检测到潜在的锁文件变更需求，但由于 --frozen-lockfile 的限制而拒绝执行。

2. 常见触发场景分析

• 本地未提交最新的 yarn.lock：开发者修改了 package.json 后仅运行 yarn add，但未提交生成的 yarn.lock。
• node_modules 与 yarn.lock 版本不一致：例如本地使用不同 Yarn 版本安装，导致解析策略差异。
• CI 环境中缺少 yarn.lock：仓库克隆后未包含锁文件（如被 .gitignore 错误排除）。
• 并行分支合并冲突：多个分支更新依赖后合并，yarn.lock 内容未正确合并。

3. 技术原理深度剖析

Yarn 的依赖解析流程如下：

1. 读取 package.json 中声明的依赖版本范围。
2. 比对 yarn.lock 中锁定的具体版本和哈希值。
3. 若存在差异且启用 --frozen-lockfile，则立即中断安装。
4. 否则，Yarn 会尝试重新解析并写入新的 yarn.lock。

在冻结模式下，第 3 步将直接失败，确保构建环境的确定性（Determinism）。

4. 解决方案全景图

问题类型	诊断方法	修复措施
锁文件缺失	检查仓库根目录是否存在 yarn.lock	本地运行 yarn install 生成并提交
版本不一致	执行 yarn check --integrity	同步 package.json 与锁文件
CI 权限问题	查看构建日志中文件系统权限	确保工作目录可写但锁文件受控
缓存污染	清除 CI 缓存后重试	配置缓存键包含 yarn.lock 哈希

5. CI/CD 最佳实践建议

为避免此类问题反复出现，推荐以下工程化策略：

# GitHub Actions 示例
- name: Install dependencies
  run: yarn install --frozen-lockfile
  env:
    CI: true

同时，在项目中引入校验脚本：

// scripts/validate-deps.js
const fs = require('fs');
if (!fs.existsSync('yarn.lock')) {
  console.error('Error: yarn.lock is missing!');
  process.exit(1);
}

6. 自动化检测流程图

graph TD
            A[开始 CI 构建] --> B{yarn.lock 存在?}
            B -- 否 --> C[报错退出]
            B -- 是 --> D[比较 package.json 与 yarn.lock]
            D --> E{版本一致?}
            E -- 否 --> F[提示需运行 yarn install]
            E -- 是 --> G[执行 yarn install --frozen-lockfile]
            G --> H[继续后续构建步骤]

7. 高级调试技巧

当问题难以复现时，可使用以下命令辅助诊断：

• yarn why <package-name>：查看某个包为何被安装及版本来源。
• yarn install --dry-run --json：模拟安装过程并输出变更预测。
• git diff HEAD~1 -- yarn.lock：审查最近一次提交中的锁文件变更。

此外，可通过设置环境变量增强行为控制：

YARN_ENABLE_IMMUTABLE_INSTALLS=true

该变量等效于全局启用 --frozen-lockfile，提升安全性。