mirror of
https://git.bjxgj.com/xgj/xgj-actions.git
synced 2025-10-14 17:33:37 +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` 以避免冲突。
|