GitLab CI Runner执行yarn install报错：锁文件将被修改，如何解决？

问题背景 #

开发环境：

react-native 0.75.2
yarn 3.6.4
node 20

项目依赖配置（package.json）：

"dependencies": { 
  ....,
  "react-native-my-native-mod": "file:native_modules/react-native-my-native-mod", 
}

在GitLab CI Runner执行yarn install --immutable时触发报错：

"The lockfile would have been modified by this install, which is explicitly forbidden."

同时提示该本地原生模块存在校验和差异。原因是本地安装时Yarn基于当前项目路径计算模块校验和，而CI环境中项目被克隆到builds/0/project-0/路径下，模块的绝对路径发生变化，导致校验和计算结果不一致，触发了Yarn不可变安装的限制。

解决方案 #

方案1：改用Yarn工作区管理本地模块（推荐） #

将本地原生模块配置为Yarn工作区，Yarn会基于项目根目录的相对路径计算校验和，不受CI环境绝对路径变化影响：

1. 在项目根目录的package.json中添加工作区配置：

"workspaces": [
  "native_modules/react-native-my-native-mod"
]

2. 修改依赖声明，直接使用包名：

"dependencies": { 
  ....,
  "react-native-my-native-mod": "*", 
}

3. 重新生成lockfile：

yarn install

提交更新后的package.json和yarn.lock到仓库，CI环境执行yarn install --immutable即可正常完成安装。

方案2：跳过本地模块的校验和检查 #

如果不想调整工作区结构，可以在.yarnrc.yml中为目标模块禁用校验和验证：

nodeLinker: node-modules
yarnPath: .yarn/releases/yarn-3.6.4.cjs
packageExtensions:
  "react-native-my-native-mod@*":
    dependenciesMeta:
      react-native-my-native-mod:
        checksum: false

也可以全局禁用所有本地文件依赖的校验和（不推荐，会降低依赖完整性校验能力）：

nodeLinker: node-modules
yarnPath: .yarn/releases/yarn-3.6.4.cjs
checksumBehavior: ignore

修改后提交配置文件，CI执行安装时就不会再因校验和差异报错。

方案3：强制CI环境路径与本地一致（不推荐） #

通过GitLab CI配置，将项目克隆到与本地完全相同的绝对路径下，示例：

build_job:
  script:
    - mkdir -p /your/local/project/path
    - cd /your/local/project/path
    - git clone $CI_REPOSITORY_URL .
    - yarn install --immutable

该方案局限性大，不同CI Runner环境可能无法适配，仅作为临时应急方案。

内容的提问来源于stack exchange，提问作者Shaon Debnath