如何在GitHub Actions中安装uv后供后续作业复用，无需重复安装？

问题原因 #

GitHub Actions的每个作业（job）运行在独立的虚拟机/容器实例中，作业之间的文件系统完全隔离。setup作业中安装的uv二进制文件仅存在于该作业的运行环境中，无法直接被后续的build、test作业访问，这就是你遇到uv: command not found的核心原因。

解决方案 #

方案1：利用actions/cache手动缓存uv二进制文件 #

通过缓存uv的安装目录，在setup作业中保存文件，后续作业恢复缓存并配置PATH即可复用uv。

完整工作流示例

jobs:
  setup:
    runs-on: ubuntu-latest
    steps:
      - name: Check out code
        uses: actions/checkout@v4

      - name: Install uv with cache enabled
        uses: astral-sh/setup-uv@v5
        with:
          enable-cache: true
          cache-dependency-glob: "uv.lock"
      
      - name: Verify uv Installation
        run: |
          echo "Checking uv version:"
          uv --version

      - name: Cache uv binary
        uses: actions/cache@v4
        with:
          path: ~/.local/bin/uv
          key: ${{ runner.os }}-uv-${{ hashFiles('**/uv.lock') }}
          restore-keys: |
            ${{ runner.os }}-uv-

  build:
    runs-on: ubuntu-latest
    needs: setup  # 确保setup作业先执行
    steps:
      - name: Check out code
        uses: actions/checkout@v4

      - name: Restore uv binary from cache
        uses: actions/cache@v4
        with:
          path: ~/.local/bin/uv
          key: ${{ runner.os }}-uv-${{ hashFiles('**/uv.lock') }}
          restore-keys: |
            ${{ runner.os }}-uv-

      - name: Add uv directory to PATH
        run: echo "$HOME/.local/bin" >> $GITHUB_PATH

      - name: Verify uv Availability
        run: uv --version

方案2：在后续作业中复用astral-sh/setup-uv自带缓存 #

astral-sh/setup-uv本身集成了缓存功能，后续作业中直接调用该action时，会自动从缓存恢复uv，无需重新下载安装，这是更简洁的方案。

完整工作流示例

jobs:
  setup:
    runs-on: ubuntu-latest
    steps:
      - name: Check out code
        uses: actions/checkout@v4

      - name: Install uv with cache enabled
        uses: astral-sh/setup-uv@v5
        with:
          enable-cache: true
          cache-dependency-glob: "uv.lock"
      
      - name: Verify uv Installation
        run: |
          echo "Checking uv version:"
          uv --version

  build:
    runs-on: ubuntu-latest
    steps:
      - name: Check out code
        uses: actions/checkout@v4

      - name: Restore uv from cache
        uses: astral-sh/setup-uv@v5
        with:
          enable-cache: true
          cache-dependency-glob: "uv.lock"

      - name: Verify uv Availability
        run: uv --version

关键注意事项 #

• 无需在setup作业中重复调用astral-sh/setup-uv，一次配置enable-cache即可。
• 确保后续作业中使用的缓存key与setup作业一致，这样才能正确匹配缓存文件。

内容的提问来源于stack exchange，提问作者blue-sam