Next.js 프로젝트를 GitHub Pages 에 배포할 때 생기는 오류 해결하기
Next.js 로 블로그를 만들던 중 배포에 문제가 생겼다.
GitHub Actions 를 이용해 배포를 하려고 했는데, 빌드 과정에 문제가 발생했다.
목차
첫 문제: next export
먼저 저장소의 Actions 탭으로 들어가서 빌드 과정을 확인했더니 다음과 같은 오류 메세지를 확인할 수 있었다.
Next.js 가 에러의 원인과 해결 방법, 그리고 참고할 수 있는 링크까지 제공해주고 있었다.
App Router 를 사용할 때에는 next export
대신 config 파일에서 output
설정을 export
로 변경하라고 한다.
그래서 next.config.mjs
파일을 열어서 output
값을 export
로 변경했다.
또한 workflows 파일에서 next export
명령어를 지워줘야 했다.
GitHub에서 기본으로 지원하는 Next.js 빌드 액션을 사용하고 있었는데, 이 액션은 next export
명령어를 사용하고 있었기 때문이다.
그래서 .github/workflows/nextjs.yml
파일을 열어서 next export
를 실행하는 단계를 지워주었다.
이 부분은 비교적 간단하게 해결할 수 있었다.
이 다음에 발생한 문제에 비해서는 말이다.
두번째 문제: next.config.mjs
와 next.config.js
next export
문제를 해결했지만, 이번에는 또다른 문제가 발생했다.
빌드된 파일이 저장되는 out
디렉토리가 없다는 에러 메세지였다.
처음에는 내 설정이 문제인가 싶어서 VM 으로 들어가서 빌드를 직접 해보기도 했지만 out
디렉토리가 정상적으로 생성되었었다.
하도 답답해서 그냥 workflows 에 ls
명령어를 추가해서 빌드 과정을 확인해보았다.
그랬더니 진짜로 out
디렉토리가 없었다.
그런데 더 이상한 점은 next.config.js
파일이 생성되어 있었다는 점이었다.
최근 create-next-app
으로 생성된 프로젝트는 next.config.js
를 대체하기 위한 next.config.mjs
파일이 생성되기 때문에 나도 해당 파일을 사용했다.
그런데 빌드 과정에서 next.config.js
파일을 생성해 사용하고 있었던 것이다.
아무래도 내가 직접 짠 액션이 아니라 GitHub에서 제공하는 액션 템플릿을 사용했는데, 해당 템플릿이 최신 업데이트를 반영하지 못한 것 같다.
그래서 빌드하기 전에 next.config.js
파일을 삭제하는 명령어를 추가했다.
이렇게 하니 빌드 과정이 정상적으로 진행되었다!
찾아보니 문제가 되는 리포지토리에도 관련 이슈가 등록되어 있어서 내 의견과 위에 쓴 임시 해결방법을 추가했다.
만약 문제가 생긴 템플릿의 원본 저장소를 찾게된다면 이슈 등록과 수정 요청 PR 을 보내는 등의 방법으로 기여할 수 있는 방도를 찾아보려고 한다.
이렇게 두 번의 문제를 해결하면서 GitHub Actions 에 대해 더 잘 이해할 수 있었다.
2024년 3월 28일 추가: config 파일 명시
next.config.js
외의 config 파일을 사용할 때 이를 명시하는 방법을 알게 되어 추가한다.
generator_config_file
을 본인이 사용하는 config 파일의 경로로 지정해주면 된다.
예를 들어 내 경우에는 next.config.mjs
를 사용하고 있으므로 다음과 같이 작성했다.
해당 인자를 지정하면 위에서 적어둔 rm -f next.config.js
가 필요가 없으므로 지워주자.
해당 액션의 주 개발진 분이 위에 남겨둔 이슈에 직접 코멘트를 남겨주셨다. config 파일 자동 감지 기능을 우선 순위는 높지 않지만 추가할 예정이라고 한다. 추가될 때까진 해당 이슈를 구독하고 있어야겠다.