Next.js 배포할 때 연결 문자열 에러 처음 볼 로그

로컬에서는 완벽하게 작동하던 Next.js 앱도 배포 후 데이터베이스 연결이 실패할 때가 있다. 이런 상황에서 제일 먼저 봐야 할 것은 HTML 메타 데이터가 아니라 연결 문자열(connection string)이다.

HTML head에서 메타 태그 먼저 확인

배포 후 페이지를 열었을 때, 먼저 HTML head에 어떤 메타 데이터가 있는지 확인해보자.

curl -s https://example.com | grep -Ei 'title|description|canonical|og:|twitter:'

메타 태그가 제대로 생성되었다면, 적어도 빌드는 성공했다는 뜻이다. 만약 메타 태그가 비어있거나 기본값만 있다면, 빌드 단계에서 환경 변수가 정상적으로 로드되지 않았을 가능성이 있다.

빌드 로그와 배포 설정 확인

npm run build

빌드 중에 데이터베이스 관련 에러나 경고가 있었는지 확인한다. 특히 Prisma를 사용한다면, prisma generate 단계에서 DATABASE_URL이 필요할 수 있다.

배포 환경의 환경 변수가 정말로 설정되었는지 확인하자. 보통 실수하는 부분:

• DATABASE_URL 변수명이 정확한가
• URL 형식이 정확한가 (postgresql://, mysql:// 등)
• 비밀번호에 특수문자가 있으면 URL 인코딩되어 있는가

canonical과 SEO 메타 태그 검증

canonical URL이 올바르게 설정되어 있으면, 적어도 페이지 메타 데이터는 생성된 것이다.

curl -s https://example.com | grep canonical

canonical이 배포된 도메인을 가리키고 있는지 확인하고, og:image가 제대로 생성되었는지도 봐야 한다.

배포 전 체크리스트

1. 환경 변수 확인 — NEXT_PUBLIC_로 시작하는 변수들이 노출되어야 하는가, DATABASE_URL은 서버에만 있어야 하는가
2. 로컬 빌드 테스트 — npm run build 후 .next 디렉토리가 정상적으로 생성되는가
3. 배포 환경의 빌드 로그 확인 — 배포 플랫폼의 빌드 로그에서 에러가 있는가
4. HTML 메타 데이터 검증 — curl로 생성된 페이지의 메타 태그 확인
5. 배포 후 데이터베이스 연결 테스트 — 실제로 쿼리가 작동하는가

결과가 바뀌었으면 어떤 값이 달라졌는지를 기록하면, 다음 배포 때 훨씬 빠르게 대응할 수 있다.