feat: 更新 npm-install GitHub Action，移除 lockfile-name 输入参数，添加 cache-hash 参数以支持自定义缓存 hash，优化锁文件处理逻辑，确保在未提供 hash 时使用 package.json 作为 fallback，提升缓存管理的灵活性和可靠性，同时更新文档以反映新功能和使用示例。

npm-install/README.md

@@ -5,8 +5,9 @@
 ## ✨ 特性
 
 - 🚀 **智能缓存**: 自动缓存 node_modules，避免重复安装
-- 📦 **多包管理器支持**: 支持 npm、pnpm、yarn
+- 📦 **多包管理器支持**: 支持 npm、pnpm、yarn，自动检测标准锁文件
 - 🎯 **灵活配置**: 可自定义缓存前缀、安装命令等
+- 🔑 **精确 hash 控制**: 支持自定义缓存 hash，确保依赖变化时缓存失效
 - 🔄 **Git 集成**: 可选的 git stash 功能
 - 📊 **详细输出**: 提供缓存命中状态和使用的缓存 key
 
@@ -15,12 +16,12 @@
 | 参数名              | 描述                         | 是否必需 | 默认值         |
 | ------------------- | ---------------------------- | -------- | -------------- |
 | `package-manager`   | 包管理器类型 (npm/pnpm/yarn) | 否       | `npm`          |
-| `lockfile-name`     | lock 文件名称                | 否       | 自动检测       |
 | `cache-prefix`      | 缓存前缀名称                 | 否       | `modules`      |
 | `node-modules-path` | node_modules 目录路径        | 否       | `node_modules` |
 | `force-install`     | 是否强制安装                 | 否       | `false`        |
 | `enable-git-stash`  | 安装后是否执行 git stash     | 否       | `false`        |
 | `install-command`   | 自定义安装命令（覆盖默认）   | 否       | `''`           |
+| `cache-hash`        | 缓存 hash 值（**推荐使用**） | 否       | 自动计算       |
 
 ## 📤 输出参数
 
@@ -29,6 +30,25 @@
 | `cache-hit` | 是否命中缓存 (true/false) |
 | `cache-key` | 使用的缓存 key            |
 
+## 💡 重要提示
+
+**强烈推荐使用 `cache-hash` 参数！**
+
+使用 `cache-hash` 参数有以下优势：
+
+- ✅ **精确控制**: 让你完全控制缓存失效的条件
+- ✅ **环境兼容**: 避免在不同容器环境中 hash 计算不一致的问题
+- ✅ **灵活组合**: 可以组合多个文件的 hash（如 `package.json` + `package-lock.json` + `.nvmrc`）
+- ✅ **调试友好**: 在 workflow 中可以清楚看到使用的 hash 值
+
+```yaml
+# 推荐用法
+with:
+  cache-hash: ${{ hashFiles('package-lock.json') }}
+```
+
+如果不提供 `cache-hash`，action 会自动使用 `package.json` 作为 fallback，但不如手动指定精确。
+
 ## 🚀 使用方法
 
 ### 基础用法 (npm)
@@ -78,6 +98,31 @@
     install-command: "npm ci --only=production"
 ```
 
+### 使用自定义缓存 hash（推荐用法）
+
+```yaml
+# 推荐：手动指定缓存hash，确保精确的缓存管理
+- name: 安装npm依赖
+  uses: actions/xgj/npm-install@v1
+  with:
+    package-manager: "npm"
+    cache-hash: ${{ hashFiles('package-lock.json') }}
+
+# pnpm项目
+- name: 安装pnpm依赖
+  uses: actions/xgj/npm-install@v1
+  with:
+    package-manager: "pnpm"
+    cache-hash: ${{ hashFiles('pnpm-lock.yaml') }}
+
+# 多文件hash组合
+- name: 安装依赖（多文件hash）
+  uses: actions/xgj/npm-install@v1
+  with:
+    package-manager: "npm"
+    cache-hash: ${{ hashFiles('package.json', 'package-lock.json', '.nvmrc') }}
+```
+
 ### 检查缓存状态
 
 ```yaml

npm-install/action.yml

@@ -10,11 +10,7 @@ inputs:
     required: false
     default: 'npm'
   
-  lockfile-name:
-    description: 'lock文件名称'
-    required: false
-    default: 'package-lock.json'
-  
+
   cache-prefix:
     description: '缓存前缀名称'
     required: false
@@ -39,6 +35,11 @@ inputs:
     description: '自定义安装命令（可选，会覆盖默认命令）'
     required: false
     default: ''
+  
+  cache-hash:
+    description: '缓存hash值（推荐使用hashFiles计算）'
+    required: false
+    default: "hashFiles('pnpm-lock.yaml')"
 
 outputs:
   cache-hit:
@@ -56,49 +57,32 @@ runs:
       id: cache-key
       shell: bash
       env:
-        NPM_HASH: ${{ hashFiles('package-lock.json') }}
-        PNPM_HASH: ${{ hashFiles('pnpm-lock.yaml') }}
-        YARN_HASH: ${{ hashFiles('yarn.lock') }}
+        FALLBACK_HASH: ${{ hashFiles('package.json') }}
       run: |
-        # 根据包管理器确定锁文件和对应的hash
-        case "${{ inputs.package-manager }}" in
-          "npm")
-            if [[ "${{ inputs.lockfile-name }}" != "package-lock.json" ]]; then
-              LOCKFILE="${{ inputs.lockfile-name }}"
-              LOCKFILE_HASH="${NPM_HASH}"
-            else
-              LOCKFILE="package-lock.json"
-              LOCKFILE_HASH="${NPM_HASH}"
-            fi
-            ;;
-          "pnpm")
-            LOCKFILE="pnpm-lock.yaml"
-            LOCKFILE_HASH="${PNPM_HASH}"
-            ;;
-          "yarn")
-            LOCKFILE="yarn.lock"
-            LOCKFILE_HASH="${YARN_HASH}"
-            ;;
-          *)
-            LOCKFILE="${{ inputs.lockfile-name }}"
-            # 对于自定义情况，使用npm hash作为默认
-            LOCKFILE_HASH="${NPM_HASH}"
-            ;;
-        esac
-        
-        # 截取hash的前12位
-        if [[ -n "${LOCKFILE_HASH}" && "${LOCKFILE_HASH}" != "" ]]; then
-          LOCKFILE_HASH_SHORT=$(echo "${LOCKFILE_HASH}" | head -c 12)
+        # 确定使用的hash值
+        if [[ -n "${{ inputs.cache-hash }}" && "${{ inputs.cache-hash }}" != "" ]]; then
+          CACHE_HASH="${{ inputs.cache-hash }}"
+          echo "✅ 使用用户传入的hash值"
+        elif [[ -n "${FALLBACK_HASH}" && "${FALLBACK_HASH}" != "" ]]; then
+          CACHE_HASH="${FALLBACK_HASH}"
+          echo "📝 未提供hash，使用package.json作为fallback"
         else
-          echo "⚠️ 警告: 无法计算锁文件hash，使用默认值"
-          LOCKFILE_HASH_SHORT="no-lockfile"
+          CACHE_HASH=""
+          echo "⚠️ 警告: 无法获取hash值，使用默认值"
         fi
         
-        CACHE_KEY="${{ runner.os }}-${{ inputs.cache-prefix }}-${LOCKFILE_HASH_SHORT}"
+        # 截取hash的前12位
+        if [[ -n "${CACHE_HASH}" && "${CACHE_HASH}" != "" ]]; then
+          CACHE_HASH_SHORT=$(echo "${CACHE_HASH}" | head -c 12)
+          echo "✅ 成功计算缓存hash: ${CACHE_HASH_SHORT}"
+        else
+          CACHE_HASH_SHORT="no-hash"
+          echo "⚠️ 使用默认hash值: ${CACHE_HASH_SHORT}"
+        fi
+        
+        CACHE_KEY="${{ runner.os }}-${{ inputs.cache-prefix }}-${CACHE_HASH_SHORT}"
         echo "key=${CACHE_KEY}" >> $GITHUB_OUTPUT
-        echo "lockfile=${LOCKFILE}" >> $GITHUB_OUTPUT
-        echo "使用锁文件: ${LOCKFILE}"
-        echo "文件hash: ${LOCKFILE_HASH}"
+        echo "使用hash: ${CACHE_HASH}"
         echo "缓存key: ${CACHE_KEY}"
 
     - name: 拉取缓存依赖

npm-install/examples/custom-cache-hash.yml

@@ -0,0 +1,107 @@
+# 自定义缓存hash示例（推荐用法）
+name: 自定义缓存hash示例
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    
+    steps:
+      - name: 检出代码
+        uses: actions/checkout@v4
+
+      - name: 设置Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+
+      # 推荐用法：手动计算hash并传入
+      - name: 安装npm依赖（使用package-lock.json hash）
+        uses: actions/xgj/npm-install@v1
+        with:
+          package-manager: 'npm'
+          cache-hash: ${{ hashFiles('package-lock.json') }}
+
+      - name: 运行linting
+        run: npm run lint
+
+      - name: 运行测试
+        run: npm test
+
+  test-pnpm:
+    runs-on: ubuntu-latest
+    
+    steps:
+      - name: 检出代码
+        uses: actions/checkout@v4
+
+      - name: 设置Node.js和pnpm
+        uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+
+      - name: 安装pnpm
+        run: npm install -g pnpm
+
+      # pnpm项目示例
+      - name: 安装pnpm依赖
+        uses: actions/xgj/npm-install@v1
+        with:
+          package-manager: 'pnpm'
+          cache-hash: ${{ hashFiles('pnpm-lock.yaml') }}
+
+      - name: 运行测试
+        run: pnpm test
+
+  test-yarn:
+    runs-on: ubuntu-latest
+    
+    steps:
+      - name: 检出代码
+        uses: actions/checkout@v4
+
+      - name: 设置Node.js和Yarn
+        uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+
+      - name: 启用Yarn
+        run: corepack enable yarn
+
+      # Yarn项目示例
+      - name: 安装yarn依赖
+        uses: actions/xgj/npm-install@v1
+        with:
+          package-manager: 'yarn'
+          cache-hash: ${{ hashFiles('yarn.lock') }}
+
+      - name: 运行测试
+        run: yarn test
+
+  # 多个锁文件的复杂项目示例
+  test-multi-lockfiles:
+    runs-on: ubuntu-latest
+    
+    steps:
+      - name: 检出代码
+        uses: actions/checkout@v4
+
+      - name: 设置Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+
+      # 组合多个文件的hash，确保任何文件变化都会使缓存失效
+      - name: 安装依赖（多文件hash）
+        uses: actions/xgj/npm-install@v1
+        with:
+          package-manager: 'npm'
+          cache-hash: ${{ hashFiles('package.json', 'package-lock.json', '.nvmrc') }}
+
+      - name: 运行测试
+        run: npm test