📄 本页由源文件 rules/依赖管理与Lock文件规范.mdc 自动投影生成（单一权威源）。请勿直接编辑本页。

依赖管理与Lock文件规范

与红线的关系：「开发规范-红线」（alwaysApply）已包含依赖管理的 3 条核心禁令（禁止盲目升级、禁止修改 lockfileVersion、新增须说明用途）。本文件在此基础上展开详细操作规范（版本映射表、检查清单、恢复方法、环境差异处理等），安装依赖/处理 lock 文件时按需加载。

---

一、Lock 文件保护原则（最高优先级）

1. 禁止修改 Lock 文件格式

• ❌ 绝对禁止：使用高版本包管理工具导致 lock 文件格式升级
• ✅ 必须：安装依赖前先检查 lock 文件版本，使用匹配的工具版本操作

2. 安装依赖前必须检查

执行 npm install、pnpm add、yarn add 等命令前，必须：

# 1. 检查 lock 文件版本
head -5 pnpm-lock.yaml  # 查看 lockfileVersion
head -5 package-lock.json  # 查看 lockfileVersion
head -5 yarn.lock  # 查看格式

# 2. 检查当前工具版本
pnpm --version / npm --version / yarn --version

# 3. 确认 CI 环境使用的版本（如有）

3. 版本映射关系

Lock 文件版本	对应工具版本	操作命令
pnpm lockfileVersion: 5.4	pnpm 7.x	npx pnpm@7 add ...
pnpm lockfileVersion: 6.0	pnpm 8.x	npx pnpm@8 add ...
pnpm lockfileVersion: 9.0	pnpm 9.x/10.x	npx pnpm@9 add ...
npm lockfileVersion: 2	npm 7-9	使用对应版本
npm lockfileVersion: 3	npm 10+	使用对应版本

4. 发现版本不匹配时的处理

• ✅ 正确做法：使用 npx 临时调用匹配版本

  npx pnpm@7 --filter @scope/package add dependency@version

• ❌ 禁止：直接使用本地高版本工具操作

---

二、依赖安装规范

1. 安装前确认清单

在执行任何依赖安装命令前，必须向用户确认：

• [ ] lock 文件当前版本是什么？
• [ ] CI 环境使用的包管理工具版本是什么？
• [ ] 本地工具版本是否匹配？

2. 安装后验证清单

安装完成后，必须验证：

• [ ] lock 文件的 lockfileVersion 是否保持不变
• [ ] 目标依赖版本是否正确更新
• [ ] 其他依赖版本是否保持不变

# 验证 lock 文件格式未变
head -5 pnpm-lock.yaml

# 验证依赖版本
grep "dependency-name" pnpm-lock.yaml

3. Lock 文件被意外修改的恢复方法

# 1. 从主分支恢复 lock 文件
git checkout origin/master -- pnpm-lock.yaml

# 2. 用匹配版本重新安装依赖
npx pnpm@7 --filter @scope/package add dependency@version

---

三、配置文件修改规范

1. 最小改动原则

修改配置文件（如 whistle、nginx、webpack 等）时：

• ✅ 正确做法：在用户原有配置基础上追加/修改
• ❌ 禁止：重写整个配置文件

2. 修改前必须确认

• 用户原有配置是什么？
• 原有配置的格式/语法是什么？（如 whistle 的正则 vs 简单匹配）
• 修改后是否会影响原有功能？

3. 修改后必须验证

• 原有功能是否正常？
• 新增功能是否生效？

---

四、环境差异处理规范

1. 必须确认的环境信息

在进行任何可能受环境影响的操作前，必须确认：

• 本地开发环境版本（Node.js、npm/pnpm/yarn、操作系统）
• CI/CD 环境版本
• 生产环境版本

2. 常见环境差异问题

问题	原因	解决方案
CI 构建依赖解析错误	lock 文件格式不兼容	使用匹配版本的包管理工具
本地正常 CI 报错	环境版本不一致	统一环境版本或使用兼容写法
代理配置不生效	配置格式/语法差异	确认目标工具的配置语法

---

五、错误处理与回滚

1. 发现问题后的处理流程

1. 立即停止：不要继续操作，避免问题扩大
2. 分析原因：查看错误信息，定位根本原因
3. 回滚操作：恢复到操作前的状态
4. 重新执行：使用正确的方法重新操作

2. 常用回滚命令

# 恢复单个文件
git checkout origin/master -- path/to/file

# 恢复所有未提交的修改
git checkout -- .

# 恢复已提交但未推送的修改
git reset --soft HEAD~1

---

六、总结：绝对禁止的行为

• ❌ 不检查 lock 文件版本就安装依赖
• ❌ 使用高版本工具导致 lock 文件格式升级
• ❌ 重写用户的配置文件而不是追加修改
• ❌ 假设本地环境和 CI 环境一致
• ❌ 出现问题后继续操作而不先回滚
• ❌ 不验证操作结果就告知用户完成