feat: 新增pnpm依赖安装与缓存的GitHub Action实现

pnpm-install/README.md

@@ -0,0 +1,102 @@
+# pnpm 依赖安装与缓存 Action
+
+专为 pnpm 项目设计的 GitHub Action，通过缓存 `node_modules` 或 pnpm store，在 CI/CD 中实现快速复用，二次执行可在 10 秒内完成安装。
+
+## ✨ 特性
+
+- **专注 pnpm**：默认缓存 `node_modules`，命中后直接复用，无需重新链接
+- **双缓存模式**：可在 `node_modules` / `store` 之间切换，满足不同目录约束
+- **锁文件准确性**：推荐传入 `cache-hash`（如 `hashFiles('pnpm-lock.yaml')`）确保缓存精准失效
+- **自定义安装**：支持附加参数或完全覆盖安装命令，保留 `force-install` 选项
+- **环境整洁**：自动设置 `PNPM_STORE_DIR`，可选清理项目根 `.pnpm-store`
+
+## 📥 输入参数
+
+| 参数名 | 描述 | 必需 | 默认值 |
+| --- | --- | --- | --- |
+| `cache-mode` | 缓存模式：`node_modules` / `store` | 否 | `node_modules` |
+| `cache-prefix` | 缓存 key 前缀 | 否 | `modules` |
+| `node-modules-path` | `node_modules` 目录路径（仅 `cache-mode=node_modules` 时生效） | 否 | `node_modules` |
+| `force-install` | 是否强制安装（追加 `--force`） | 否 | `false` |
+| `install-command` | 自定义安装命令，覆盖默认的 `pnpm install` | 否 | `''` |
+| `install-args` | 附加参数（仅默认命令时生效） | 否 | `''` |
+| `cache-hash` | 缓存 hash 值（建议：`hashFiles('pnpm-lock.yaml')`） | 否 | `''` |
+| `clean-project-store` | 安装后是否清理项目根的 `.pnpm-store` | 否 | `false` |
+
+## 📤 输出参数
+
+| 参数名 | 描述 |
+| --- | --- |
+| `cache-hit` | 缓存是否命中 (`true` / `false`) |
+| `cache-key` | 实际使用的缓存 key |
+| `cache-path` | 缓存目录路径（调试/复用用途） |
+
+## 🚀 快速上手
+
+```yaml
+- name: 安装依赖
+  uses: actions/xgj/pnpm-install@v1
+  with:
+    cache-hash: ${{ hashFiles('pnpm-lock.yaml') }}
+```
+
+- 默认缓存 `node_modules`，命中后直接跳过安装步骤，满足 10 秒内完成的目标。
+- 首次执行或 lock 文件变更时执行 `pnpm install --prefer-offline --frozen-lockfile`，完成后写入缓存。
+
+## 🔁 缓存模式
+
+### `cache-mode: node_modules`（默认）
+
+- **适用场景**：希望二次执行直接复用产物、编译型依赖较多。
+- **行为**：缓存 `node_modules` 指定目录。命中缓存后跳过安装步骤。
+- **额外设定**：Action 会自动将 `pnpm node-linker` 设置为 `hoisted`，避免使用 symlink，生成更接近 npm 的目录结构。
+
+### `cache-mode: store`
+
+```yaml
+with:
+  cache-mode: store
+  cache-hash: ${{ hashFiles('pnpm-lock.yaml') }}
+```
+
+- **适用场景**：项目对 `node_modules` 目录结构有额外处理，或需要保持 `node_modules` 在工作目录内新生成。
+- **行为**：缓存 `${{ runner.temp }}/.pnpm-store`。命中缓存后执行 `pnpm install --offline --frozen-lockfile`，仅进行符号链接操作。
+
+## ⚙️ 进阶配置
+
+- **强制安装**
+
+```yaml
+with:
+  force-install: "true"
+```
+
+当缓存未命中且怀疑存在依赖冲突时，可追加 `--force`。
+
+- **自定义命令**
+
+```yaml
+with:
+  install-command: "pnpm install --prod"
+```
+
+完全覆盖默认安装逻辑，适合部署类任务。
+
+- **清理项目根 `.pnpm-store`**
+
+```yaml
+with:
+  clean-project-store: "true"
+```
+
+在部分仓库中 `.npmrc` 会指定相对 store 路径，该选项可避免 CI 工作目录残留。
+
+## 🧰 示例工作流
+
+参见 `examples/basic-usage.yml`，展示在 CI 中的集成方式。
+
+## 🛡️ 注意事项
+
+- 该 Action 假设 Runner 环境已安装 pnpm。若未预装，请在前一步引入 `pnpm/action-setup@v4`。
+- 强烈建议传入 `cache-hash`，并确保 `pnpm-lock.yaml` 已提交。
+- GitHub Actions 缓存配额有限，定期清理或调整 `cache-prefix` 以避免冲突。