使用GitHub Actions部署Next.js应用时上传产物报错如何解决？

问题 #

尝试用GitHub Actions部署Next.js应用，按GitHub文档操作：进入仓库>设置>Pages，将源设置为GitHub Actions，并添加官方提供的deploy.yml配置文件，但执行到Upload Artifact步骤时出现报错。本地执行npm run build能正常生成out目录。

部署配置文件（deploy.yml） #

name: Deploy Next.js site to Pages

on:
  push:
    branches: ["main"]

  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Detect package manager
        id: detect-package-manager
        run: |
          if [ -f "${{ github.workspace }}/yarn.lock" ]; then
            echo "manager=yarn" >> $GITHUB_OUTPUT
            echo "command=install" >> $GITHUB_OUTPUT
            echo "runner=yarn" >> $GITHUB_OUTPUT
            exit 0
          elif [ -f "${{ github.workspace }}/package.json" ]; then
            echo "manager=npm" >> $GITHUB_OUTPUT
            echo "command=ci" >> $GITHUB_OUTPUT
            echo "runner=npx --no-install" >> $GITHUB_OUTPUT
            exit 0
          else
            echo "Unable to determine package manager"
            exit 1
          fi
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: ${{ steps.detect-package-manager.outputs.manager }}
      - name: Setup Pages
        uses: actions/configure-pages@v4
        with:
          static_site_generator: next
      - name: Restore cache
        uses: actions/cache@v4
        with:
          path: |
            .next/cache
          key: ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json', '**/yarn.lock') }}-${{ hashFiles('**.[jt]s', '**.[jt]sx') }}
          restore-keys: |
            ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json', '**/yarn.lock') }}-
      - name: Install dependencies
        run: ${{ steps.detect-package-manager.outputs.manager }} ${{ steps.detect-package-manager.outputs.command }}
      - name: Build with Next.js
        run: ${{ steps.detect-package-manager.outputs.runner }} next build
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./out

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

报错信息 #

Run actions/upload-pages-artifact@v3
  with:
    path: ./out
    name: github-pages
    retention-days: 1
  env:
    GITHUB_PAGES: true
Run tar \
  tar \
    --dereference --hard-dereference \
    --directory "$INPUT_PATH" \
    -cvf "$RUNNER_TEMP/artifact.tar" \
    --exclude=.git \
    --exclude=.github \
    .
  shell: /usr/bin/sh -e {0}
  env:
    GITHUB_PAGES: true
    INPUT_PATH: ./out
tar: dist: Cannot open: No such file or directory
tar: Error is not recoverable: exiting now
Error: Process completed with exit code 2.

解决方案 #

报错核心是CI环境下构建生成的目录和配置中指定的上传路径不匹配，按以下步骤解决：

• 统一构建输出目录
  直接在CI构建命令中强制指定输出目录为out，修改deploy.yml里的Build with Next.js步骤：

  - name: Build with Next.js
    run: ${{ steps.detect-package-manager.outputs.runner }} next build --out-dir out
  

  该命令会强制Next.js将构建产物输出到out目录，和配置中的上传路径保持一致。

• 检查Next.js配置一致性
  打开项目根目录的next.config.js，确认output配置：

  • 如果设置了output: 'standalone'，默认会生成dist目录，需改为output: 'export'来生成out目录；
  • 确保本地和CI环境的next.config.js完全一致，避免配置差异导致的输出目录不同。

• 验证CI构建产物目录
  在Upload artifact步骤前添加目录检查步骤，确认实际生成的目录名称：

  - name: Check build output directory
    run: |
      ls -la ./out || ls -la ./dist
  

  如果输出显示实际生成的是dist，则直接修改Upload artifact的path为./dist即可。

内容的提问来源于stack exchange，提问作者Enes