Next.js 프로젝트를 GitHub Pages 에 배포할 때 생기는 오류 해결하기
on Git, Github, Github actions, Next.js, Github pages
GitHub Actions 로 Next.js 프로젝트를 빌드할 때 생기는 오류를 해결하는 방법
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: $ next build
# 주석 처리된 부분을 지워주면 된다.
# - name: Static HTML export with Next.js
# run: $ next export
- name: Upload artifact
...
이 부분은 비교적 간단하게 해결할 수 있었다.
이 다음에 발생한 문제에 비해서는 말이다.
두번째 문제: next.config.mjs 와 next.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: $ 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
$ next build
- name: Show files
...
이렇게 하니 빌드 과정이 정상적으로 진행되었다!
찾아보니 문제가 되는 리포지토리에도 관련 이슈가 등록되어 있어서 내 의견과 위에 쓴 임시 해결방법을 추가했다. 만약 문제가 생긴 템플릿의 원본 저장소를 찾게된다면 이슈 등록과 수정 요청 PR 을 보내는 등의 방법으로 기여할 수 있는 방도를 찾아보려고 한다.
이렇게 두 번의 문제를 해결하면서 GitHub Actions 에 대해 더 잘 이해할 수 있었다.