mirror of
https://git.bjxgj.com/xgj/xgj-actions.git
synced 2025-10-15 18:33:37 +08:00
103 lines
3.7 KiB
Markdown
103 lines
3.7 KiB
Markdown
# 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` 以避免冲突。
|