next js 빌드 에러

배경

혼자 토이프로젝트 만든거를 이제 빌드해서 vercel 에 올려보려고 했는데
npm run build 할때 빌드가 안되는거다
음?ㅋㅋ 이러고 걍 다시 빌드하고 그랬는데
별 거 아닐 줄 알았는데

이게 날 ...이렇게 고톹ㅇ받게 할줄은...
진짜 영원히 괴롭힘ㅁㅊ 밤새 거의 이것만 매달려 있었다

next 15.2 버전

처음에는 next 15.2 버전이랑 react 19 버전을 쓰고 있었음

Creating an optimized production build ...
✓ Compiled successfully
Linting and checking validity of types ...Failed to compile.

.next/types/app/api/process-text/route.ts:2:24
Type error: File 'C:/Users/sister/Desktop/translation-app/translation-app/app/api/process-text/route.ts' is not a module.

1 | // File: C:\Users\sister\Desktop\translation-app\translation-app\app\api\process-text\route.ts
2 | import * as entry from '../../../../../app/api/process-text/route.js'
| ^
3 | import type { NextRequest } from 'next/server.js'
4 |
5 | type TEntry = typeof import('../../../../../app/api/process-text/route.js')
Next.js build worker exited with code: 1 and signal: null

C:\Users\sister\Desktop\translation-app\translation-app>

GitHub Copilot

이 에러는 route.ts 파일이 모듈로 인식되지 않아서 발생하는 문제입니다. 이를 해결하기 위해 route.ts 파일에 default export를 추가해야 합니다.

route.ts
default export를 추가합니다.

이렇게 수정하면 route.ts 파일에 default export가 추가되어 Next.js가 API 라우트를 올바르게 인식할 수 있습니다. npm run build 명령어를 실행할 때 발생하는 에러도 해결될 것입니다.

~ 이와 비슷한 에러 2398471238471623489612335786개 수정 ~

근데도 안돼서 개열받는 중에 챗지피티한테 물어봄

bash
C:\Users\sister\Desktop\translation-app\translation-app>npm run build

> translation-app@0.1.0 build
> next build

   ▲ Next.js 15.2.0
   - Environments: .env.local

   Creating an optimized production build ...
 ✓ Linting and checking validity of types
 ✓ Collecting page data
Error occurred prerendering page "/". Read more: https://nextjs.org/docs/messages/prerender-error
TypeError: Cannot read properties of undefined (reading 'entryCSSFiles')
    at rP (C:\Users\sister\Desktop\translation-app\translation-app\node_modules\next\dist\compiled\next-server\app-page.runtime.prod.js:128:2639)
    at Z.preloadCallbacks (C:\Users\sister\Desktop\translation-app\translation-app\node_modules\next\dist\compiled\next-server\app-page.runtime.prod.js:128:5692)
    at rF (C:\Users\sister\Desktop\translation-app\translation-app\node_modules\next\dist\compiled\next-server\app-page.runtime.prod.js:128:6430)
    at C:\Users\sister\Desktop\translation-app\translation-app\node_modules\next\dist\compiled\next-server\app-page.runtime.prod.js:128:4617
    at C:\Users\sister\Desktop\translation-app\translation-app\node_modules\next\dist\server\lib\trace\tracer.js:169:36
    at NoopContextManager.with (C:\Users\sister\Desktop\translation-app\translation-app\node_modules\next\dist\compiled\@opentelemetry\api\index.js:1:7062)
    at ContextAPI.with (C:\Users\sister\Desktop\translation-app\translation-app\node_modules\next\dist\compiled\@opentelemetry\api\index.js:1:518)
    at NoopTracer.startActiveSpan (C:\Users\sister\Desktop\translation-app\translation-app\node_modules\next\dist\compiled\@opentelemetry\api\index.js:1:18093)
    at ProxyTracer.startActiveSpan (C:\Users\sister\Desktop\translation-app\translation-app\node_modules\next\dist\compiled\@opentelemetry\api\index.js:1:18854)
    at C:\Users\sister\Desktop\translation-app\translation-app\node_modules\next\dist\server\lib\trace\tracer.js:151:103
Export encountered an error on /(routes)/page: /, exiting the build.
 ⨯ Next.js build worker exited with code: 1 and signal: null

C:\Users\sister\Desktop\translation-app\translation-app>

next 14.1 버전으로 다운그레이드

GPT

이 TypeError: Cannot read properties of undefined (reading 'entryCSSFiles') 오류는 Next.js 15.2.0 버전에서 발생하는 빌드 타임 렌더링 문제와 관련이 있습니다.
보통 스타일 관련 문제, 잘못된 서버 측 코드, 환경 변수 설정 문제 등으로 인해 발생할 수 있습니다.

✅ 1. Next.js 버전 다운그레이드 (추천)

Next.js 15.x에서 종종 이런 오류가 발생합니다. 안정적인 14.x 버전으로 다운그레이드하면 해결될 가능성이 큽니다.

npm install next@14.1.0

그 후 다시 빌드 시도:

npm run build

해보래서 해봤는데 그다음에는 react 19 버전이랑 충돌이 나서 react 를 18버전으로 낮췄고

그다음에는

C:\Users\sister\Desktop\translation-app\translation-app>npm run build

> translation-app@0.1.0 build
> next build

   ▲ Next.js 14.1.0
   - Environments: .env.local

   Creating an optimized production build ...
Failed to compile.

./node_modules/canvas/build/Release/canvas.node
Module parse failed: Unexpected character '�' (1:2)
You may need an appropriate loader to handle this file type, currently no loaders are configured to process this file. See https://webpack.js.org/concepts#loaders
(Source code omitted for this binary file)

Import trace for requested module:
./node_modules/canvas/build/Release/canvas.node
./node_modules/canvas/lib/bindings.js
./node_modules/canvas/index.js
./node_modules/pdfjs-dist/build/pdf.js
./lib/pdfProcessor.ts
./components/PdfUploader.tsx
./app/page.tsx

app\layout.tsx
next/font error:
Unknown font Geist

app\layout.tsx
next/font error:
Unknown font Geist Mono


> Build failed because of webpack errors

C:\Users\sister\Desktop\translation-app\translation-app>

GPT

1️⃣ canvas 모듈 관련 에러

./node_modules/canvas/build/Release/canvas.node
Module parse failed: Unexpected character '�' (1:2)

🔹 원인:

• canvas 패키지는 Node.js 환경에서만 동작하는 네이티브 모듈입니다.
• Next.js의 웹팩(Webpack)은 canvas.node 파일을 처리할 수 없습니다.
• pdfjs-dist가 canvas를 내부적으로 사용하고 있기 때문에 문제가 발생합니다.

🔹 해결 방법:
1️⃣ canvas를 동적 import로 변경 (서버에서만 실행되도록 설정)
👉 lib/pdfProcessor.ts 수정

const canvas = typeof window === "undefined" ? require("canvas") : null;

---

2️⃣ canvas를 Next.js 빌드에서 제외
👉 next.config.js에 다음 코드 추가

/** @type {import('next').NextConfig} */
const nextConfig = {
  webpack: (config, { isServer }) => {
    if (!isServer) {
      config.externals = [...(config.externals || []), "canvas"];
    }
    return config;
  },
};

module.exports = nextConfig;

---

2️⃣ Geist 폰트 관련 에러

Unknown font `Geist`
Unknown font `Geist Mono`

🔹 원인:

• Geist와 Geist Mono는 Vercel에서 기본 제공하는 폰트가 아님
• next/font/google로 제공되지 않으며, 수동으로 추가해야 함

🔹 해결 방법:
1️⃣ 사용 중인 코드에서 Geist를 Inter 등으로 변경
👉 app/layout.tsx 수정

import { Inter } from "next/font/google";

const inter = Inter({ subsets: ["latin"] });

export default function Layout({ children }) {
  return <div className={inter.className}>{children}</div>;
}

---

그래서 canvas 를 npm uninstall canvas 하고 next.config에도 external로 등록함
그리고 폰트는 사용되어 있는 부분을 아예 다 삭제해버렸다.

그래도 에러가 나길래
node_modules랑 package-lock.json 삭제 후 다시 설치함

next.config.js

const nextConfig = {
  webpack: (config) => {
    config.externals = [...(config.externals || []), "canvas"];
    return config;
  },
};

그리고 또 다른 산이 기다리고 있었다 :

Error occurred prerendering page "/".

> Build failed because of webpack errors

   ▲ Next.js 14.1.0
   - Environments: .env.local
> translation-app@0.1.0 build
   Creating an optimized production build ...
 ✓ Compiled successfully
 ✓ Linting and checking validity of types
 ✓ Collecting page data
   Generating static pages (1/10)  [=   ]
TypeError: Cannot read properties of undefined (reading 'clientModules')
    at C:\Users\sister\Desktop\translation-app\translation-app\node_modules\next\dist\compiled\next-server\app-page.runtime.prod.js:12:199008
    at rW (C:\Users\sister\Desktop\translation-app\translation-app\node_modules\next\dist\compiled\next-server\app-page.runtime.prod.js:16:14861)
    at nM (C:\Users\sister\Desktop\translation-app\translation-app\node_modules\next\dist\compiled\next-server\app-page.runtime.prod.js:12:47419)
    at nN (C:\Users\sister\Desktop\translation-app\translation-app\node_modules\next\dist\compiled\next-server\app-page.runtime.prod.js:12:64674)
    at nM (C:\Users\sister\Desktop\translation-app\translation-app\node_modules\next\dist\compiled\next-server\app-page.runtime.prod.js:12:61233)
    at nN (C:\Users\sister\Desktop\translation-app\translation-app\node_modules\next\dist\compiled\next-server\app-page.runtime.prod.js:12:64674)
    at nI (C:\Users\sister\Desktop\translation-app\translation-app\node_modules\next\dist\compiled\next-server\app-page.runtime.prod.js:12:46806)
    at nM (C:\Users\sister\Desktop\translation-app\translation-app\node_modules\next\dist\compiled\next-server\app-page.runtime.prod.js:12:47570)
    at nN (C:\Users\sister\Desktop\translation-app\translation-app\node_modules\next\dist\compiled\next-server\app-page.runtime.prod.js:12:64674)
    at nM (C:\Users\sister\Desktop\translation-app\translation-app\node_modules\next\dist\compiled\next-server\app-page.runtime.prod.js:12:61233)
TypeError: Cannot read properties of undefined (reading 'clientModules')
    at C:\Users\sister\Desktop\translation-app\translation-app\node_modules\next\dist\compiled\next-server\app-page.runtime.prod.js:12:199008
    at rW (C:\Users\sister\Desktop\translation-app\translation-app\node_modules\next\dist\compiled\next-server\app-page.runtime.prod.js:16:14861)
    at nM (C:\Users\sister\Desktop\translation-app\translation-app\node_modules\next\dist\compiled\next-server\app-page.runtime.prod.js:12:47419)
    at nN (C:\Users\sister\Desktop\translation-app\translation-app\node_modules\next\dist\compiled\next-server\app-page.runtime.prod.js:12:64674)
    at nG (C:\Users\sister\Desktop\translation-app\translation-app\node_modules\next\dist\compiled\next-server\app-page.runtime.prod.js:12:72265)
    at AsyncLocalStorage.run (node:async_hooks:338:14)
    at Timeout._onTimeout (C:\Users\sister\Desktop\translation-app\translation-app\node_modules\next\dist\compiled\next-server\app-page.runtime.prod.js:12:88128)
    at listOnTimeout (node:internal/timers:569:17)
    at process.processTimers (node:internal/timers:512:7)

Error occurred prerendering page "/". Read more: https://nextjs.org/docs/messages/prerender-error

TypeError: Cannot read properties of undefined (reading 'clientModules')
    at C:\Users\sister\Desktop\translation-app\translation-app\node_modules\next\dist\compiled\next-server\app-page.runtime.prod.js:12:199008
    at rW (C:\Users\sister\Desktop\translation-app\translation-app\node_modules\next\dist\compiled\next-server\app-page.runtime.prod.js:16:14861)
    at nM (C:\Users\sister\Desktop\translation-app\translation-app\node_modules\next\dist\compiled\next-server\app-page.runtime.prod.js:12:47419)
    at nN (C:\Users\sister\Desktop\translation-app\translation-app\node_modules\next\dist\compiled\next-server\app-page.runtime.prod.js:12:64674)
    at nG (C:\Users\sister\Desktop\translation-app\translation-app\node_modules\next\dist\compiled\next-server\app-page.runtime.prod.js:12:72265)
    at AsyncLocalStorage.run (node:async_hooks:338:14)
    at Timeout._onTimeout (C:\Users\sister\Desktop\translation-app\translation-app\node_modules\next\dist\compiled\next-server\app-page.runtime.prod.js:12:88128)
    at listOnTimeout (node:internal/timers:569:17)
 ✓ Generating static pages (10/10)

> Export encountered errors on following paths:
        /(routes)/page: /

GPT

이번에도 clientModules를 읽을 수 없음 (Cannot read properties of undefined) 오류가 발생했습니다.

🔴 이 오류는 주로 아래 두 가지 원인으로 발생합니다.
1. 클라이언트 전용 코드(useState, useEffect, window, document, localStorage 등)가 서버 환경에서 실행됨
2. Next.js의 app 디렉토리(app/page.tsx, app/layout.tsx 등)에서 use client 선언이 빠짐

---

🛠 1. 해결 방법

✅ (1) use client가 빠진 컴포넌트 확인

Next.js의 app 디렉토리에서는 기본적으로 서버 컴포넌트(서버에서 렌더링되는 컴포넌트) 가 됩니다.
그런데 여기에 useState, useEffect, window, localStorage 같은 클라이언트 전용 코드를 사용하면 서버에서 실행되면서 오류가 발생합니다.

📌 app/page.tsx, app/layout.tsx 파일을 열고 맨 위에 use client 추가

// app/page.tsx
"use client"; // ✅ 클라이언트 컴포넌트 선언

import { useState, useEffect } from "react";

export default function Home() {
  const [count, setCount] = useState(0);

  return <div>Counter: {count}</div>;
}

➡️ 클라이언트에서만 실행되도록 보장

---

✅ (2) layout.tsx는 use client를 사용하면 안 됨!

app/layout.tsx는 서버 컴포넌트로 유지해야 합니다.
즉, use client를 사용하면 안 됩니다.

📌 app/layout.tsx 예시 (올바른 방식)

export const metadata = {
  title: "My Next.js App",
};

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}

➡️ 여기에는 useState, useEffect, localStorage 같은 클라이언트 훅을 쓰면 안 됩니다.

---

✅ (3) Next.js 캐시 삭제 및 node_modules 정리

설정을 수정한 후 Next.js의 캐시를 완전히 삭제한 다음 다시 빌드하세요.

📌 Windows (PowerShell)

rd /s /q .next node_modules
del package-lock.json
npm install
npm run build

이렇게 해봤는데도 안된다.
app/page.tsx와 /components/SavedTranslations.tsx
/components/TranslationCard.tsx
/components/PdfUploader.tsx
/hooks/useTranslation.ts
/hooks/useTextProcessing.tsx 등등 모두 use client 가 있는 걸 확인했고,

rd /s /q .next node_modules
del package-lock.json
npm install
npm run build 를 하고도 동일한 에러를 만남

미치고 팔짝 뛰겠고 지피티가 해결 방법을 모르니 결국 스택 오버플로우를 뒤지기 시작했다.

내가 찾은 키워드는 next.js 14 build error prerendering page
다행히도 나랑 똑같은 에러를 겪은 사람들이 더 있었다...

참조 링크들
https://github.com/vercel/next.js/discussions/57535#discussioncomment-7410129
https://github.com/vercel/next.js/discussions/57535#discussioncomment-7767719
https://github.com/vercel/next.js/discussions/57535#discussioncomment-7613434
https://medium.com/phantom3/next-js-14-build-prerender-error-fix-f3c51de2fe1d

그래서 나와있는걸 다 시도해봄
무슨 모듈을 지워라, next.config에서 뭐를 비활성화해라, 누구는 loading.tsx만 추가하면 된다, 'force-dynamic'을 붙여라, 등등등...

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    appDir: true,
    serverActions: false, // 서버 액션 기능 비활성화
    serverComponentsExternalPackages: ['canvas'], // canvas 모듈 제외
  },
};

module.exports = nextConfig;

그리고도 안 돼서 그냥 빡쳐서 자꾸 오류가 나는 폴더(안ㄴ 쓰는 폴더고 테스트용으로 만들어 뒀었음)를 지웠더니, (/translationtest) 그 뒤에는 /_not-found/와 같은 식으로 뜨며 이 폴더가 문제가 되어 에러가 난다고 로그에 뜬다.

Error occurred prerendering page "/_not-found". Read more: https://nextjs.org/docs/messages/prerender-error

Error: Unsupported Server Component type: {...}
    at e (C:\Users\sister\Desktop\translation-app\translation-app\node_modules\next\dist\compiled\next-server\app-page.runtime.prod.js:12:137969)
    at ek (C:\Users\sister\Desktop\translation-app\translation-app\node_modules\next\dist\compiled\next-server\app-page.runtime.prod.js:12:138019)
    at Array.toJSON (C:\Users\sister\Desktop\translation-app\translation-app\node_modules\next\dist\compiled\next-server\app-page.runtime.prod.js:12:135629)
    at stringify (<anonymous>)
    at eP (C:\Users\sister\Desktop\translation-app\translation-app\node_modules\next\dist\compiled\next-server\app-page.runtime.prod.js:12:142093)
    at eE (C:\Users\sister\Desktop\translation-app\translation-app\node_modules\next\dist\compiled\next-server\app-page.runtime.prod.js:12:142572)
    at AsyncLocalStorage.run (node:async_hooks:338:14)
    at Timeout._onTimeout (C:\Users\sister\Desktop\translation-app\translation-app\node_modules\next\dist\compiled\next-server\app-page.runtime.prod.js:12:150373)
    at listOnTimeout (node:internal/timers:569:17)
    at process.processTimers (node:internal/timers:512:7)
 ✓ Generating static pages (6/6)

> Export encountered errors on following paths:
        /_not-found/page: /_not-found
        /page: /

ㄹㅇ 미치고 팔짝 뜀
그 폴더를 지우고(휴지통 비우기) 캐시도 삭제하고 next와 node modules, package-lock.json도 삭제 후에 다시 npm install을 했는데도 같은 오류가 나서
아 이젠진짜 뭐 어떻게 해야 되냐,,,
수십번 node modules 지웠다 깔고 캐시 지우고 했던 것 같다

뭐 config에 넣어보라는거 다 넣어보고 했다

그리고 이 글 을 발견

그리고 내 config 파일이랑 비교했다.

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: "standalone", // ✅ 독립형 빌드로 설정
  experimental: {
    appDir: true, 
  },
};

module.exports = nextConfig;

챗지피티가 package.json에서 dev build 뭐 이런것들 이렇게 환경변수 명확화 해주라고 했는데 : 이건 개소리였다 (해주니까 안됨)
"scripts": { "dev": "NODE_ENV=development next dev", "build": "NODE_ENV=production next build", "start": "NODE_ENV=production next start", "lint": "next lint" }

C:\Users\sister\Desktop\translation-app\translation-app>npm run build --force
npm warn using --force Recommended protections disabled.

> translation-app@0.1.0 build
> next build

 ⚠ Invalid next.config.js options detected:
 ⚠     Expected object, received boolean at "experimental.serverActions"
 ⚠     Unrecognized key(s) in object: 'appDir' at "experimental"
 ⚠ See more info here: https://nextjs.org/docs/messages/invalid-next-config
 ⚠ Server Actions are available by default now, experimental.serverActions option can be safely removed.
  ▲ Next.js 14.2.24
  - Environments: .env.local
  - Experiments (use with caution):
    · esmExternals

   Creating an optimized production build ...

> Build error occurred
ReferenceError: path is not defined
    at Object.webpack (C:\Users\sister\Desktop\translation-app\translation-app\next.config.js:6:33)
    at getBaseWebpackConfig (C:\Users\sister\Desktop\translation-app\translation-app\node_modules\next\dist\build\webpack-config.js:1838:32)
    at async Promise.all (index 1)
    at async Span.traceAsyncFn (C:\Users\sister\Desktop\translation-app\translation-app\node_modules\next\dist\trace\trace.js:154:20)
    at async webpackBuildImpl (C:\Users\sister\Desktop\translation-app\translation-app\node_modules\next\dist\build\webpack-build\impl.js:136:21)
    at async C:\Users\sister\Desktop\translation-app\translation-app\node_modules\next\dist\build\index.js:1006:111
    at async Span.traceAsyncFn (C:\Users\sister\Desktop\translation-app\translation-app\node_modules\next\dist\trace\trace.js:154:20)
    at async build (C:\Users\sister\Desktop\translation-app\translation-app\node_modules\next\dist\build\index.js:368:9)

C:\Users\sister\Desktop\translation-app\translation-app>

🔍 에러 분석 및 해결 방법

당신의 Next.js 빌드 오류는 주로 next.config.js 설정 오류와 path is not defined 문제에서 발생하고 있습니다.
이를 하나씩 분석하고 해결 방법을 제시하겠습니다.

---

✅ 1. next.config.js 설정 오류

에러 메시지:

⚠ Invalid next.config.js options detected:
 ⚠     Expected object, received boolean at "experimental.serverActions"
 ⚠     Unrecognized key(s) in object: 'appDir' at "experimental"
 ⚠ Server Actions are available by default now, `experimental.serverActions` option can be safely removed.

📌 오류 원인

• experimental.serverActions는 더 이상 필요하지 않습니다. → 삭제해야 함
• experimental.appDir → 지원되지 않는 설정 값이므로 제거해야 함

📌 해결 방법
👉 next.config.js 수정

🔹 변경 전 (오류가 있는 코드)

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: "standalone",
  experimental: {
    appDir: true, // ❌ 지원되지 않는 옵션 (삭제 필요)
    serverActions: false, // ❌ 이제 기본값이므로 삭제 필요
  },
};

module.exports = nextConfig;

🔹 변경 후 (수정된 코드)

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: "standalone", // ✅ 독립 실행형 빌드 사용 (필요하면 유지)
};

module.exports = nextConfig;

✅ 불필요한 experimental 옵션을 제거하면 오류가 사라질 것입니다.

---

✅ 2. path is not defined 오류 해결

에러 메시지:

ReferenceError: path is not defined
    at Object.webpack (C:\Users\sister\Desktop\translation-app\translation-app\next.config.js:6:33)

📌 오류 원인

• next.config.js에서 path 모듈을 import하지 않고 사용하려 했기 때문입니다.
• Next.js에서 Webpack을 설정하는 과정에서 path 모듈이 필요할 경우, 명시적으로 import해야 합니다.

📌 해결 방법
👉 next.config.js에서 path를 명확하게 import

🔹 변경 전 (오류가 있는 코드)

module.exports = {
  webpack: (config) => {
    config.resolve.alias["@components"] = path.resolve(__dirname, "components"); // ❌ path가 정의되지 않음
    return config;
  },
};

🔹 변경 후 (수정된 코드)

const path = require("path"); // ✅ path 모듈 추가

module.exports = {
  webpack: (config) => {
    config.resolve.alias["@components"] = path.resolve(__dirname, "components"); // ✅ 이제 정상 작동
    return config;
  },
};

✅ 이렇게 수정하면 path is not defined 오류가 해결될 것입니다.

---

내가 path 를 import 안하고 사용하려고 했다고,,

이걸 수정하고 나서 드디어... 장장 24시간만에(정말로) 빌드에 성공했다.

내 생각에, 처음에 이 분의 글이 맞았던 것 같다. ㅠㅠ

결론 : 해결 방법

다른 사람이 또 이런 일을 겪는다면...
반드시

next.config.js에서

const path = require("path");
와

webpack 안에
config.resolve.alias["@components"] = path.resolve(__dirname, "components");
를 쓸 것

---

진짜 진이 다 빠진다... 겨우빌드함 ㅠㅠ