Enforce pnpm version consistency to prevent lockfile format churn

.github/workflows/content-check.yml

@@ -31,14 +31,42 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      # Enable corepack to ensure the exact pnpm version from package.json is used
+      - name: Enable Corepack
+        run: corepack enable
+
       - uses: pnpm/action-setup@v4
 
       - uses: actions/setup-node@v4
         with:
           node-version: 20
           cache: "pnpm"
 
+      # Verify pnpm version matches package.json packageManager field
+      - name: Check pnpm version
+        run: node scripts/check-pnpm-version.mjs
+
       - run: pnpm install --frozen-lockfile
+
+      # Verify lockfile wasn't modified by install
+      - name: Check lockfile consistency
+        run: |
+          if ! git diff --exit-code pnpm-lock.yaml; then
+            echo "❌ Error: pnpm-lock.yaml was modified after install"
+            echo "This indicates a pnpm version mismatch or corrupted lockfile"
+            echo ""
+            echo "Expected pnpm version from package.json:"
+            # Use multiple fallback methods to extract version
+            grep '"packageManager"' package.json | grep -o 'pnpm@[^"]*' || \
+              node -e "try { console.log(require('./package.json').packageManager || 'not specified') } catch(e) { console.log('Could not read') }" || \
+              echo "Could not extract version"
+            echo ""
+            echo "Actual pnpm version:"
+            pnpm --version || echo "pnpm not found"
+            exit 1
+          fi
+          echo "✅ Lockfile is consistent"
+
       - name: Run tests
         run: pnpm test
       # Non-blocking image migration + lint (visibility only)

.github/workflows/deploy.yml

@@ -20,14 +20,41 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      # Enable corepack to ensure the exact pnpm version from package.json is used
+      - name: Enable Corepack
+        run: corepack enable
+
       - uses: pnpm/action-setup@v4
 
       - uses: actions/setup-node@v4
         with:
           node-version: 20
           cache: pnpm
 
+      # Verify pnpm version matches package.json packageManager field
+      - name: Check pnpm version
+        run: node scripts/check-pnpm-version.mjs
+
       - run: pnpm install --frozen-lockfile
+
+      # Verify lockfile wasn't modified by install
+      - name: Check lockfile consistency
+        run: |
+          if ! git diff --exit-code pnpm-lock.yaml; then
+            echo "❌ Error: pnpm-lock.yaml was modified after install"
+            echo "This indicates a pnpm version mismatch or corrupted lockfile"
+            echo ""
+            echo "Expected pnpm version from package.json:"
+            # Use multiple fallback methods to extract version
+            grep '"packageManager"' package.json | grep -o 'pnpm@[^"]*' || \
+              node -e "try { console.log(require('./package.json').packageManager || 'not specified') } catch(e) { console.log('Could not read') }" || \
+              echo "Could not extract version"
+            echo ""
+            echo "Actual pnpm version:"
+            pnpm --version || echo "pnpm not found"
+            exit 1
+          fi
+          echo "✅ Lockfile is consistent"
       - run: pnpm run lint
       - run: pnpm run lint:images
       - run: pnpm run typecheck

.github/workflows/sync-uuid.yml

@@ -36,13 +36,21 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      # Enable corepack to ensure the exact pnpm version from package.json is used
+      - name: Enable Corepack
+        run: corepack enable
+
       - uses: pnpm/action-setup@v4
 
       - uses: actions/setup-node@v4
         with:
           node-version: 20
           cache: "pnpm" # 顺便启用 pnpm 缓存，加速
 
+      # Verify pnpm version matches package.json packageManager field
+      - name: Check pnpm version
+        run: node scripts/check-pnpm-version.mjs
+
       - name: Install deps
         run: pnpm install --frozen-lockfile
 

.husky/pre-commit

@@ -10,5 +10,9 @@ pnpm lint:images || exit 1
 # 3) 运行 Vitest，确保配置校验通过
 pnpm test || exit 1
 
-# 4) 其余按 lint-staged 处理（如 Prettier）
+# 4) 检查 pnpm 版本和 lockfile 一致性（警告但不阻止提交）
+pnpm check:pnpm-version || true
+pnpm check:lockfile || true
+
+# 5) 其余按 lint-staged 处理（如 Prettier）
 pnpm exec lint-staged

CONTRIBUTING.md

@@ -173,6 +173,83 @@ git push origin doc_raven
 | `disable`                | 在任何模式下都跳过远程图片尺寸请求，仅使用文档内手动声明的宽高                   |
 | `force`                  | 强制启用远程图片尺寸请求，并在出现错误时抛出异常以暴露问题                       |
 
+### pnpm 版本和 lockfile 相关问题
+
+#### 问题：pnpm-lock.yaml 频繁出现格式变化（单双引号切换）
+
+**原因**：不同版本的 pnpm 使用不同的 YAML 序列化格式，即使依赖关系相同，锁文件的格式也可能不同。
+
+**解决方案**：
+
+1. **确保使用正确的 pnpm 版本**：
+   ```bash
+   # 检查当前版本
+   pnpm --version
+
+   # 应该显示: 10.20.0
+   # 如果不是，请使用以下命令之一：
+
+   # 方法 1: 使用 corepack（推荐）
+   corepack enable
+   corepack prepare pnpm@10.20.0 --activate
+
+   # 方法 2: 全局安装
+   npm install -g pnpm@10.20.0
+   ```
+
+2. **验证版本一致性**：
+   ```bash
+   pnpm check:pnpm-version
+   ```
+
+3. **如果 lockfile 已经被错误修改**：
+   ```bash
+   # 丢弃 lockfile 的修改
+   git checkout pnpm-lock.yaml
+
+   # 确认使用正确的 pnpm 版本后重新安装
+   pnpm install
+   ```
+
+4. **在提交前检查**：
+   项目的 pre-commit hook 会自动检查 pnpm 版本和 lockfile 变更，如果发现版本不匹配会给出警告。
+
+#### 问题：CI 检查失败，提示 lockfile 不一致
+
+这通常意味着：
+1. 你本地使用的 pnpm 版本与项目要求的不一致
+2. lockfile 被错误修改或损坏
+
+**解决方案**：
+```bash
+# 1. 确认并切换到正确的 pnpm 版本
+corepack enable
+pnpm --version  # 确认是 10.20.0
+
+# 2. 删除 node_modules 和重新安装
+rm -rf node_modules
+pnpm install
+
+# 3. 检查 lockfile 是否有变更
+git status
+
+# 4. 如果没有变更，说明已修复；如果有变更，说明之前的 lockfile 确实有问题
+```
+
+#### 问题：为什么要使用 corepack 而不是全局安装？
+
+**Corepack 的优势**：
+- 自动读取 `package.json` 的 `packageManager` 字段
+- 每个项目可以使用不同的 pnpm 版本而不冲突
+- 新贡献者克隆项目后自动使用正确的版本
+- 减少版本不匹配导致的问题
+
+**如何为团队启用 corepack**：
+```bash
+# 一次性设置，之后所有项目都会受益
+corepack enable
+```
+
 ## 🚀 开发环境
 
 ### 1. 克隆仓库
@@ -184,10 +261,57 @@ cd involutionhell
 
 ### 2. 安装依赖
 
+**重要：为了避免 pnpm-lock.yaml 格式不一致的问题，请务必使用项目指定的 pnpm 版本！**
+
+本项目已在 `package.json` 中锁定了 pnpm 版本（`"packageManager": "pnpm@10.20.0"`），推荐使用 **corepack** 来自动管理正确的版本：
+
+#### 方式一：使用 Corepack（推荐）
+
+Corepack 是 Node.js 16.9+ 自带的工具，能自动使用 `package.json` 中指定的包管理器版本。
+
+```bash
+# 启用 corepack
+corepack enable
+
+# 安装依赖（corepack 会自动使用 pnpm@10.20.0）
+pnpm install
+```
+
+#### 方式二：全局安装指定版本
+
+如果不想使用 corepack，可以手动安装项目指定的 pnpm 版本：
+
+```bash
+# 安装 pnpm 10.20.0
+npm install -g pnpm@10.20.0
+
+# 安装依赖
+pnpm install
+```
+
+#### 验证 pnpm 版本
+
+安装完成后，请务必验证你使用的是正确的版本：
+
 ```bash
-pnpm install    # 推荐；如需可改用 npm install
+# 检查 pnpm 版本
+pnpm --version
+# 应该输出: 10.20.0
+
+# 或使用项目提供的检查脚本
+pnpm check:pnpm-version
 ```
 
+#### ⚠️ 为什么版本一致性很重要？
+
+不同版本的 pnpm 在序列化 `pnpm-lock.yaml` 时可能使用不同的格式（如单引号 vs 双引号），导致：
+- PR 中产生大量无意义的 diff
+- 增加代码审查负担
+- 可能导致 CI 检查失败
+
+我们的 CI 工作流会自动检查版本一致性，如果检测到版本不匹配会导致构建失败。
+
+
 ### 3. 本地开发
 
 运行开发服务器：
@@ -207,12 +331,14 @@ pnpm dev
 常用脚本集中在 `package.json` 中，以下是最常用的命令：
 
 ```bash
-pnpm dev             # 启动开发服务器
-pnpm build           # 构建生产版本
-pnpm start           # 启动生产服务器
-pnpm lint:images     # 检查图片是否符合规范
-pnpm migrate:images  # 自动迁移图片到对应 assets 目录
-pnpm postinstall     # 同步必要的 Husky/Fumadocs 配置
+pnpm dev                  # 启动开发服务器
+pnpm build                # 构建生产版本
+pnpm start                # 启动生产服务器
+pnpm lint:images          # 检查图片是否符合规范
+pnpm migrate:images       # 自动迁移图片到对应 assets 目录
+pnpm check:pnpm-version   # 检查 pnpm 版本是否与 package.json 一致
+pnpm check:lockfile       # 检查 lockfile 是否有未预期的修改
+pnpm postinstall          # 同步必要的 Husky/Fumadocs 配置
 ```
 
 ---