[github workflow + Next.js] 빌드 실패 File is not defined 오류 해결하기

문제

Next.js 14를 사용한 프로젝트에서 Github Actions로 빌드, 스토리북 테스트를 진행하고 있는데 Github Actions 빌드 환경에서 File을 찾을 수 없다는 에러가 발생했습니다.

 

ReferenceError: File is not defined
Error: Failed to collect page data for /lectures/[lectureId]/question

 

 

로컬 개발 환경이나 빌드 상황에서는 정상적으로 동작하고, CI 환경에서만 발생하는 상황이었습니다.

 

시도 1 (해결 X)

유일하게 prefetch를 하는 페이지였고, File을 서버컴포넌트에서 사용하려는게 문제가 됐나보다 추측하고 서버 환경에서 File을 정의하거나 CI 환경에서 prefetchQuery를 진행하지 않도록 조건을 추가했습니다.

- 서버 환경에서 File 대신 undici.File을 사용하도록 설정

- workflow에 CI라는 환경변수를 추가해 prefetch를 실행하는 조건에 추가

 

시도2 (해결)

여러 시도를 했지만 동일한 에러가 계속 발생했고 prefetch에 사용하는 스키마와 함수들을 살펴보다가 prefetch하려는 값에는 File 타입을 사용하지 않고 있다는 점을 발견했습니다.

스키마를 정의해둔 같은 파일에 폼에서 사용할 스키마가 같이 정의되어 있었고, 여기에 file을 사용하는 코드가 있어 에러가 발생하는 건가 추측했습니다.

export const AnswerFormSchema = z.object({
  content: z.string(),
  files: z.array(z.object({
    id: z.string(),
    file: z.instanceof(File),  // 의심..
  })),
});

 

이 스키마는 prefetch를 하는 서버 환경에서는 필요없으므로 분리해봤습니다.

 

해결

File 클래스를 사용하는 스키마를 별도의 파일로 분리했고, 결과는 성공!!

서버 환경에서 실행되는 파일에는 File을 참조하는 코드가 없도록 분리했습니다.

 

결론

github workflow는 node.js 환경에서 실행되고 있었고, 번들링 시점에 브라우저 API인 File은 없음!

z.instanceof(File)이 런타임에 사용돼지 않았더라도 정적 번들 과정에 포함되므로 에러 발생!

서버에서 사용될 zod 스키마 + 그 외 파일등에 DOM이나 브라우저 전용 api, 객체를 불필요하게 사용하지 않도록 유의하자!