문제 배경

회사의 기존 홈페이지(회사 서비스와 구성원을 소개하는)를 새롭게 만드는 작업을 진행하게 되었다. 당시 Next.js의 파일 기반의 라우팅에 대해 궁금했으며, 기존에 Next.js 프로젝트를 써본 적이 없지만 규모가 작은 프로젝트라 시범 도입하기 좋을 것 같다는 점, 그리고 회사를 소개하는 홈페이지이기 때문에 SEO를 신경쓰면 좋을 것 같다는 점에 기반해 Next.js로 프로젝트를 구성하게 되었다.

프로젝트를 마무리하고 기존의 레포지토리에 push를 진행했는데, CI/CD build 단계에서 에러가 발생했다.

에러 내용

1. .build 폴더를 찾을 수 없다는 내용이었으며, 검색을 통해서 손쉽게 해결할 수 있었다.
   Next 공식문서 바로가기

2. 다룰 주 내용으로, nginx에서 index.html을 찾을 수 없다는 내용을 담고 있었다.
   에러 메시지를 기록해 두지 않아 아쉬울 따름이다.

해결 과정

일단 index.html을 내보낼 수 있는 방법에 대해 알아보았다. 해결 방법은 어렵지 않게 찾을 수 있었다.
next.config.js에서 output: export설정을 통해 index.html 파일을 내보낼 수 있다고 한다.

const nextConfig = {
	output: 'export',
}

실제로 해당 설정을 통한 빌드 결과물을 비교해보았다.

예제 파일 구조

해당 프로젝트는 개념 정리를 위해 예시로 만들었으며 next 14.0.0으로 구성했다.

매우 간단한 구조이다.

src/app/
├── page.tsx
├── login/
│   ├── page.tsx
├── main/
│   ├── page.tsx

next run build

해당 명령어를 통해 build 했을 때의 파일 구조이다.

.next/server/
├── app/
│   ├── index.html
│   ├── login.html
│   ├── main.html
│   ├── page.js
│   ├── login/
│   ├── ├── page.js
│   ├── main/
│   ├── ├── page.js

위와 같은 형식으로 되어있다.

{ output: export }

next.config.js에 해당 속성을 추가했다.

/** @type {import('next').NextConfig} */
const nextConfig = {
  distDir: 'build',
  output: 'export',
};

module.exports = nextConfig;

아래는 빌드 결과물이다.

build/
├── _next/
├── index.html
├── login.html
├── main.html

위의 빌드 결과물과 달리 빌드 폴더 밑에 바로 index.html 파일이 생성된 것을 볼 수 있다.
그렇기 때문에 문제였던 Nginx에서 index.html을 찾을 수 없다는 오류가 나오지 않고, CI/CD가 정상적으로 작동했다.

그렇다면 해당 속성은 무슨 역할을 하는 걸까?

Next 공식문서 바로 가기

When running next build, Next.js generates an HTML file per route.
Since Next.js supports this static export, it can be deployed and hosted on any web server that can serve HTML/CSS/JS static assets.

next build를 실행할 때, Next는 각 라우트마다 HTML을 생성한다.
Next는 이러한 정적 내보내기를 통해 HTML/CSS/JS 정적 자원을 제공할 수 있는 어떤 웹서버에서도 배포하고 호스팅할 수 있다.

즉, output: export 설정은 정적 내보내기를 가능하게 하는 것이다.

정적 내보내기 - Static Site Generation (SSG)

SSG는 웹 페이지를 빌드 시점에 미리 생성하여 정적 파일로 제공하는 방법이다. 이 방법은 전통적인 서버 사이드 렌더링(SSR)이나 클라이언트 사이드 렌더링(CSR)과는 달리 서버의 런타임 작업이 필요하지 않다.

SSG를 이용하면 사용자는 미리 생성된 정적 파일을 받기 때문에 응답 속도가 빠르다. 서버에서 실시간으로 페이지를 렌더링할 필요가 없다. SSG는 변경 빈도가 낮은 페이지에 사용한다면 빠른 로딩 속도를 제공할 수 있다.

왜 Nginx는 index.html이 필요할까?

Nginx는 웹 서버이다. 웹 서버는 주로 정적 컨텐츠를 클라이언트에게 전달하는 역할을 한다.
웹 서버는 index.html 파일을 반드시 필요로 하는 것은 아니지만, 많은 웹 서버의 기본 설정이 대체로 index.html을 기본 문서로 제공하도록 설정되어 있다.

---

마무리

본인이 구현한 사이트는 변경 빈도가 거의 없었고, API 호출이 이루어지지 않는 특성을 가지고 있어서 SSG로 웹 페이지를 제공하는 것에 무리가 없었다.
지금 생각해보니 nginx 서버 설정을 바꾸는 방식도 가능했겠지만, 여러 개의 프로젝트가 nginx를 통했고 위험 요소가 있었을 것이라고 생각한다.