feat: 添加pnpm自动安装和store缓存模式支持

npm-install/README.md

@@ -10,17 +10,21 @@
 - 🔑 **精确 hash 控制**: 支持自定义缓存 hash，确保依赖变化时缓存失效
 - 🔄 **Git 集成**: 可选的 git stash 功能
 - 📊 **详细输出**: 提供缓存命中状态和使用的缓存 key
+- 🧰 **自动安装 pnpm**: 当选择 `package-manager: pnpm` 时，自动通过 `pnpm/action-setup@v4` 确保 pnpm 可用（可指定版本）
 
 ## 📋 输入参数
 
 | 参数名              | 描述                         | 是否必需 | 默认值         |
 | ------------------- | ---------------------------- | -------- | -------------- |
 | `package-manager`   | 包管理器类型 (npm/pnpm/yarn) | 否       | `npm`          |
+| `pnpm-version`      | pnpm 版本（`package-manager: pnpm` 时生效） | 否 | `9` |
+| `cache-mode`        | 缓存模式（`node_modules` 或 `store`） | 否 | `node_modules` |
 | `cache-prefix`      | 缓存前缀名称                 | 否       | `modules`      |
 | `node-modules-path` | node_modules 目录路径        | 否       | `node_modules` |
 | `force-install`     | 是否强制安装                 | 否       | `false`        |
 | `enable-git-stash`  | 安装后是否执行 git stash     | 否       | `false`        |
 | `install-command`   | 自定义安装命令（覆盖默认）   | 否       | `''`           |
+| `install-args`      | 附加到默认安装命令的参数（当未提供 `install-command` 时生效） | 否 | `''` |
 | `cache-hash`        | 缓存 hash 值（**推荐使用**） | 否       | 自动计算       |
 
 ## 📤 输出参数
@@ -29,6 +33,7 @@
 | ----------- | ------------------------- |
 | `cache-hit` | 是否命中缓存 (true/false) |
 | `cache-key` | 使用的缓存 key            |
+| `cache-path` | 缓存路径（用于调试与复用） |
 
 ## 💡 重要提示
 
@@ -65,6 +70,13 @@ with:
   uses: actions/xgj/npm-install@v1
   with:
     package-manager: "pnpm"
+    # 可选：指定 pnpm 版本（默认 9）
+    pnpm-version: "9"
+    # 可选：切换为包管理器 store 缓存，提升复用率（首次仍需安装链接）
+    # cache-mode: "store"
+    # 可选：附加安装参数（当未设置 install-command 时生效）
+    # 例如：保持锁文件严格、忽略可选依赖
+    install-args: "--frozen-lockfile --no-optional"
 ```
 
 ### 强制安装 + Git Stash
@@ -98,6 +110,31 @@ with:
     install-command: "npm ci --only=production"
 ```
 
+### 仅附加参数（不覆盖命令）
+
+```yaml
+# npm 示例：追加只生产依赖
+- name: 安装（npm，仅生产依赖）
+  uses: actions/xgj/npm-install@v1
+  with:
+    package-manager: npm
+    install-args: "--only=production"
+
+# pnpm 示例：严格锁文件 + 忽略可选依赖
+- name: 安装（pnpm，严格锁文件）
+  uses: actions/xgj/npm-install@v1
+  with:
+    package-manager: pnpm
+    install-args: "--frozen-lockfile --no-optional"
+
+# yarn 示例：纯安装（禁用脚本）
+- name: 安装（yarn，禁用脚本）
+  uses: actions/xgj/npm-install@v1
+  with:
+    package-manager: yarn
+    install-args: "--ignore-scripts"
+```
+
 ### 使用自定义缓存 hash（推荐用法）
 
 ```yaml
@@ -177,8 +214,14 @@ jobs:
 
 1. **缓存 Key 生成**: 根据包管理器类型和 lock 文件生成唯一的缓存 key
 2. **缓存检查**: 使用`actions/cache@v4`检查是否存在匹配的缓存
-3. **条件安装**: 仅在缓存未命中时执行依赖安装
-4. **可选操作**: 根据配置执行 git stash 等额外操作
+3. **自动安装 pnpm（如需）**: 当 `package-manager=pnpm` 时，使用 `pnpm/action-setup@v4` 确保 pnpm 已安装
+4. **缓存路径确定**:
+   - 当 `cache-mode=node_modules` 时，缓存 `node_modules`（可用 `node-modules-path` 定义目录）。
+   - 当 `cache-mode=store` 时，缓存包管理器的全局存储：`npm` → `~/.npm`，`pnpm` → 通过 `pnpm store path` 动态获取，`yarn` → `~/.cache/yarn`。
+5. **条件安装**: 仅在缓存未命中时执行依赖安装
+6. **可选操作**: 根据配置执行 git stash 等额外操作
+
+> 说明：缓存 key 中包含 OS、包管理器（以及 pnpm 的版本）、缓存模式与自定义前缀，避免跨包管理器/模式的缓存误用。
 
 ## 🎯 最佳实践
 
@@ -189,6 +232,21 @@ jobs:
 - uses: actions/xgj/npm-install@v1
   with:
     package-manager: "pnpm" # 如果项目使用pnpm
+
+### 1.1 选择合适的缓存模式
+
+```yaml
+# 追求最快的安装且目录较稳定：缓存 node_modules（默认）
+- uses: actions/xgj/npm-install@v1
+  with:
+    package-manager: pnpm
+    cache-mode: node_modules
+
+# 追求更高的通用性和复用率：缓存包管理器 store（首次仍需 install 链接）
+- uses: actions/xgj/npm-install@v1
+  with:
+    package-manager: pnpm
+    cache-mode: store
 ```
 
 ### 2. 合理使用强制安装
@@ -220,6 +278,10 @@ jobs:
 - name: 重建缓存
   if: steps.install.outputs.cache-hit != 'true'
   run: npm run build:cache
+
+# 调试：打印缓存路径（可用于后续步骤复用路径）
+- name: 打印缓存路径
+  run: echo "Cache path is: ${{ steps.install.outputs.cache-path }}"
 ```
 
 ## 🚨 注意事项
@@ -228,6 +290,7 @@ jobs:
 2. **缓存大小**: node_modules 可能很大，请关注 GitHub Actions 的缓存限制
 3. **Lock 文件**: 确保 lock 文件已提交到仓库，这是缓存 key 生成的基础
 4. **权限**: 某些自定义安装命令可能需要额外的权限
+5. **跨包管理器缓存隔离**: 缓存 key 与 restore-keys 均包含包管理器、版本（pnpm）与模式，切换包管理器/模式时会触发一次干净安装，避免污染
 
 ## 🔍 故障排除
 
@@ -238,6 +301,11 @@ jobs:
 - lock 文件是否存在且已提交
 - package.json 或 lock 文件是否有变更
 - 缓存前缀是否与之前一致
+- 是否切换了包管理器或 `cache-mode`（切换会生成不同的 key 与前缀）
+
+### pnpm store 路径
+
+当 `cache-mode=store` 且 `package-manager=pnpm` 时，本 Action 会通过 `pnpm store path` 动态解析缓存目录；若命令不可用，则回退到 `~/.pnpm-store`。
 
 ### 安装失败