mirror of
https://git.bjxgj.com/xgj/xgj-actions.git
synced 2025-10-14 17:13:38 +08:00
89 lines
3.1 KiB
Markdown
89 lines
3.1 KiB
Markdown
# 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` 以避免冲突。
|