Chomu's Blog.

>

Posts

GitHub

Next.js 프로젝트를 GitHub Pages 에 배포할 때 생기는 오류 해결하기

Next.js 로 블로그를 만들던 중 배포에 문제가 생겼다.
GitHub Actions 를 이용해 배포를 하려고 했는데, 빌드 과정에 문제가 발생했다.

목차

첫 문제: next export

먼저 저장소의 Actions 탭으로 들어가서 빌드 과정을 확인했더니 다음과 같은 오류 메세지를 확인할 수 있었다.

 The "next export" command has been removed in favor of "output: export" in next.config.js. Learn more: https://nextjs.org/docs/advanced-features/static-html-export

Next.js 가 에러의 원인과 해결 방법, 그리고 참고할 수 있는 링크까지 제공해주고 있었다.
App Router 를 사용할 때에는 next export 대신 config 파일에서 output 설정을 export 로 변경하라고 한다.
그래서 next.config.mjs 파일을 열어서 output 값을 export 로 변경했다.

// next.config.mjs
/** @type {import('next').NextConfig} */
const nextConfig = {
  output: "export",
};
 
export default nextConfig;

또한 workflows 파일에서 next export 명령어를 지워줘야 했다.
GitHub에서 기본으로 지원하는 Next.js 빌드 액션을 사용하고 있었는데, 이 액션은 next export 명령어를 사용하고 있었기 때문이다.
그래서 .github/workflows/nextjs.yml 파일을 열어서 next export 를 실행하는 단계를 지워주었다.

      ...
        run: ${{ steps.detect-package-manager.outputs.runner }} next build
      # 주석 처리된 부분을 지워주면 된다.
      # - name: Static HTML export with Next.js
      #   run: ${{ steps.detect-package-manager.outputs.runner }} next export
      - name: Upload artifact
      ...

이 부분은 비교적 간단하게 해결할 수 있었다.
이 다음에 발생한 문제에 비해서는 말이다.

두번째 문제: next.config.mjsnext.config.js

next export 문제를 해결했지만, 이번에는 또다른 문제가 발생했다.

Archive artifact
  tar: out: Cannot open: No such file or directory
  tar: Error is not recoverable: exiting now
  Error: Process completed with exit code 2.

빌드된 파일이 저장되는 out 디렉토리가 없다는 에러 메세지였다.
처음에는 내 설정이 문제인가 싶어서 VM 으로 들어가서 빌드를 직접 해보기도 했지만 out 디렉토리가 정상적으로 생성되었었다.
하도 답답해서 그냥 workflows 에 ls 명령어를 추가해서 빌드 과정을 확인해보았다.

      ...
        run: ${{ steps.detect-package-manager.outputs.runner }} next build
      - name: Show files
        run: |
          ls -l
      - name: Upload artifact
      ...

그랬더니 진짜로 out 디렉토리가 없었다.

-rw-r--r--   1 runner docker      9 Mar  5 06:22 CNAME
-rw-r--r--   1 runner docker   1383 Mar  5 06:22 README.md
drwxr-xr-x   2 runner docker   4096 Mar  5 06:22 app
-rw-r--r--   1 runner docker    201 Mar  5 06:23 next-env.d.ts
-rw-r--r--   1 runner docker    174 Mar  5 06:22 next.config.js
-rw-r--r--   1 runner docker    161 Mar  5 06:22 next.config.mjs
drwxr-xr-x 294 runner docker  12288 Mar  5 06:23 node_modules
-rw-r--r--   1 runner docker 149671 Mar  5 06:22 package-lock.json
-rw-r--r--   1 runner docker    622 Mar  5 06:22 package.json
drwxr-xr-x   2 runner docker   4096 Mar  5 06:22 public
-rw-r--r--   1 runner docker    574 Mar  5 06:22 tsconfig.json
-rw-r--r--   1 runner docker 114293 Mar  5 06:22 yarn.lock

그런데 더 이상한 점은 next.config.js 파일이 생성되어 있었다는 점이었다.
최근 create-next-app 으로 생성된 프로젝트는 next.config.js 를 대체하기 위한 next.config.mjs 파일이 생성되기 때문에 나도 해당 파일을 사용했다.
그런데 빌드 과정에서 next.config.js 파일을 생성해 사용하고 있었던 것이다.
아무래도 내가 직접 짠 액션이 아니라 GitHub에서 제공하는 액션 템플릿을 사용했는데, 해당 템플릿이 최신 업데이트를 반영하지 못한 것 같다. 그래서 빌드하기 전에 next.config.js 파일을 삭제하는 명령어를 추가했다.

      ...
      - name: Build with Next.js
        run: |
          rm -f next.config.js
          ${{ steps.detect-package-manager.outputs.runner }} next build
      - name: Show files
      ...

이렇게 하니 빌드 과정이 정상적으로 진행되었다!
찾아보니 문제가 되는 리포지토리에도 관련 이슈가 등록되어 있어서 내 의견과 위에 쓴 임시 해결방법을 추가했다. 만약 문제가 생긴 템플릿의 원본 저장소를 찾게된다면 이슈 등록과 수정 요청 PR 을 보내는 등의 방법으로 기여할 수 있는 방도를 찾아보려고 한다.
이렇게 두 번의 문제를 해결하면서 GitHub Actions 에 대해 더 잘 이해할 수 있었다.

2024년 3월 28일 추가: config 파일 명시

next.config.js 외의 config 파일을 사용할 때 이를 명시하는 방법을 알게 되어 추가한다. generator_config_file 을 본인이 사용하는 config 파일의 경로로 지정해주면 된다. 예를 들어 내 경우에는 next.config.mjs 를 사용하고 있으므로 다음과 같이 작성했다.

      - name: Setup Pages
        uses: actions/configure-pages@v4
        with:
          static_site_generator: next
          generator_config_file: ./next.config.mjs

해당 인자를 지정하면 위에서 적어둔 rm -f next.config.js 가 필요가 없으므로 지워주자.

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

해당 액션의 주 개발진 분이 위에 남겨둔 이슈에 직접 코멘트를 남겨주셨다. config 파일 자동 감지 기능을 우선 순위는 높지 않지만 추가할 예정이라고 한다. 추가될 때까진 해당 이슈를 구독하고 있어야겠다.