# pnpm 依赖安装与缓存 Action

专为 pnpm 项目设计的 GitHub Action，通过缓存 pnpm store，在 CI/CD 中实现快速复用，二次执行可在 10 秒内完成安装。

## ✨ 特性

- **专注 pnpm**：缓存 pnpm store，命中后仅执行快速链接
- **离线友好**：自动根据缓存命中追加 `--offline`/`--prefer-offline`
- **锁文件准确性**：推荐传入 `cache-hash`（如 `hashFiles('pnpm-lock.yaml')`）确保缓存精准失效
- **自定义安装**：支持附加参数或完全覆盖安装命令，保留 `force-install` 选项
- **环境整洁**：自动设置 `PNPM_STORE_DIR`，可选清理项目根 `.pnpm-store`

## 📥 输入参数

| 参数名 | 描述 | 必需 | 默认值 |
| --- | --- | --- | --- |
| `cache-prefix` | 缓存 key 前缀 | 否 | `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') }}
```

- 默认缓存 pnpm store，命中后执行 `pnpm install --offline --frozen-lockfile`，通常在 10 秒内完成链接。
- 首次执行或 lock 文件变更时执行 `pnpm install --prefer-offline --frozen-lockfile`，完成后写入缓存。
- 当未显式提供 `cache-hash` 时，会依次使用 `pnpm-lock.yaml`、`package.json` 计算 hash 作为兜底，确保缓存具备基本失效条件。

## 🔁 缓存路径

Action 会通过执行 `pnpm store path --silent` 获取当前 pnpm store 目录，并将结果写入日志与 `PNPM_STORE_DIR` 环境变量。

若命令未返回有效路径，可在调用前手动设置 `PNPM_STORE_DIR=/path/to/store` 以确保后续步骤正常运行。

## ⚙️ 进阶配置

- **强制安装**

```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` 以避免冲突。