diff --git a/npm-install/README.md b/npm-install/README.md index 30e4dfc..e046ec2 100644 --- a/npm-install/README.md +++ b/npm-install/README.md @@ -11,6 +11,7 @@ - 🔄 **Git 集成**: 可选的 git stash 功能 - 📊 **详细输出**: 提供缓存命中状态和使用的缓存 key - 🧰 **自动安装 pnpm**: 当选择 `package-manager: pnpm` 时,自动通过 `pnpm/action-setup@v4` 确保 pnpm 可用(可指定版本) +- 🗜️ **缓存 pnpm 二进制**: 在安装前缓存 Corepack 的 pnpm 二进制目录,避免重复下载 pnpm 本体(对封闭/慢网环境更友好) ## 📋 输入参数 @@ -215,6 +216,7 @@ jobs: 1. **缓存 Key 生成**: 根据包管理器类型和 lock 文件生成唯一的缓存 key 2. **缓存检查**: 使用`actions/cache@v4`检查是否存在匹配的缓存 3. **自动安装 pnpm(如需)**: 当 `package-manager=pnpm` 时,使用 `pnpm/action-setup@v4` 确保 pnpm 已安装 + - 在此之前,本 Action 会使用 `actions/cache@v4` 缓存 Corepack 的 pnpm 二进制目录,命中后无需再次从外网拉取 pnpm 本体 4. **缓存路径确定**: - 当 `cache-mode=node_modules` 时,缓存 `node_modules`(可用 `node-modules-path` 定义目录)。 - 当 `cache-mode=store` 时,缓存包管理器的全局存储:`npm` → `~/.npm`,`pnpm` → 通过 `pnpm store path` 动态获取,`yarn` → `~/.cache/yarn`。 @@ -292,6 +294,20 @@ jobs: 4. **权限**: 某些自定义安装命令可能需要额外的权限 5. **跨包管理器缓存隔离**: 缓存 key 与 restore-keys 均包含包管理器、版本(pnpm)与模式,切换包管理器/模式时会触发一次干净安装,避免污染 +## 🛡️ 封闭网络/慢网优化 + +在网络较差或对外网络受限的环境中,建议: + +- 本 Action 已默认缓存 pnpm 二进制(Corepack 缓存目录),首次成功后后续运行将跳过 pnpm 下载。 + - 缓存路径(按 OS 区分,Action 会全部尝试): + - Linux: `~/.cache/corepack` + - macOS: `~/Library/Caches/CorePack` 与 `~/Library/Caches/Corepack` + - Windows: `C:\Users\runneradmin\AppData\Local\Corepack\cache` + - 缓存 key:`${{ runner.os }}-corepack-pnpm-${{ inputs.pnpm-version }}` +- 将 registry 指向内网镜像或近源镜像,并(如需)配置 `NODE_AUTH_TOKEN`。 +- 适当降低并发、调大超时与重试,例如设置:`pnpm config set network-concurrency 1` 与对应的 `npm config set network-timeout ...` 等。 +- 使用 `cache-mode: store` 并确保 `pnpm store path` 被缓存(Action 默认已处理)。首次成功安装后,后续基本本地链接即可。 + ## 🔍 故障排除 ### 缓存未命中 diff --git a/npm-install/action.yml b/npm-install/action.yml index 63f3881..2a21b36 100644 --- a/npm-install/action.yml +++ b/npm-install/action.yml @@ -119,6 +119,19 @@ runs: echo "使用hash: ${CACHE_HASH}" echo "缓存key: ${CACHE_KEY}" + - name: 缓存 pnpm 二进制 (Corepack) + if: inputs.package-manager == 'pnpm' + uses: actions/cache@v4 + with: + path: | + ~/.cache/corepack + ~/Library/Caches/CorePack + ~/Library/Caches/Corepack + C:\Users\runneradmin\AppData\Local\Corepack\cache + key: ${{ runner.os }}-corepack-pnpm-${{ inputs.pnpm-version }} + restore-keys: | + ${{ runner.os }}-corepack-pnpm- + - name: 确保 pnpm 可用(用于计算 store 路径) if: inputs.package-manager == 'pnpm' && inputs.cache-mode == 'store' uses: pnpm/action-setup@v4