xgj/pnpm-install/README.md

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
store-path	自定义 pnpm store 路径（默认使用 runner 临时目录）	否	''
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	缓存目录路径（调试/复用用途）

🚀 快速上手

- 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，完成后写入缓存。

🔁 缓存路径

默认缓存路径为 ${{ runner.temp }}/.pnpm-store。如需与团队现有目录保持一致，可通过 store-path 自定义：

with:
  store-path: ~/.cache/pnpm-store
  cache-hash: ${{ hashFiles('pnpm-lock.yaml') }}

提示：如自定义路径，需确保同一 Runner 不会被多个并发作业共享该目录，以免产生竞争条件。

⚙️ 进阶配置

• 强制安装

with:
  force-install: "true"

当缓存未命中且怀疑存在依赖冲突时，可追加 --force。

• 自定义命令

with:
  install-command: "pnpm install --prod"

完全覆盖默认安装逻辑，适合部署类任务。

• 清理项目根 .pnpm-store

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