1. 핵심요약
Supabase, Vercel, Next.js를 연결하면 배포, 인증, 데이터 저장, 도메인 운영까지 한 흐름으로 완성할 수 있습니다.
2. 목차
3. Supabase Vercel 연동이 필요한 이유
Supabase Vercel 연동은 단순 배포가 아니라 로그인, 데이터 저장, 서버 로직, 운영 도메인까지 함께 묶는 실서비스 구조를 만드는 방법입니다. Vercel은 빠른 배포와 도메인 연결에 강하고, Supabase는 데이터베이스와 인증, 스토리지에 강하며, Next.js는 화면과 서버 로직을 함께 다루기 좋습니다. 공식 자료도 이 조합이 풀스택 앱 구성에 적합하다고 안내합니다.[3][8]
이 조합의 핵심은 “배포만 되는 앱”이 아니라 “사용자가 실제로 쓰는 앱”을 만드는 데 있습니다. 즉, 개발 편의성보다 운영 완성도를 우선하는 구조입니다. 이 흐름을 이해하면 이후의 도메인 연결과 인증 설정도 훨씬 단순해집니다.
역할은 보통 아래처럼 나눌 수 있습니다.
- Vercel: 배포, 자동 배포, 커스텀 도메인
- Supabase: DB, 인증, 스토리지
- Next.js: 화면, 서버 로직, Server Actions
4. 시작 전 준비물과 전제 조건
작업을 시작하려면 먼저 기본 재료가 있어야 합니다. Next.js 프로젝트, GitHub 저장소, Vercel 계정, Supabase 계정, 그리고 필요하면 도메인이 필요합니다. Vercel은 GitHub 저장소를 연결해 프로젝트를 Import하고 배포하는 흐름을 기본으로 사용합니다.[1][3]
준비물은 아래처럼 보면 됩니다. 이 순서대로 갖춰지면 이후 배포와 연동 단계가 훨씬 자연스럽게 이어집니다. 특히 코드가 먼저 GitHub에 올라가 있어야 자동 배포 흐름을 안정적으로 만들 수 있습니다.
| 준비물 | 이유 | 확인할 것 |
|---|---|---|
| Next.js 프로젝트 | 앱의 기본 구조 | 로컬 실행 가능 여부 |
| GitHub 저장소 | Vercel 연결용 | 코드 푸시 가능 여부 |
| Vercel 계정 | 배포와 도메인 연결 | 로그인 가능 여부 |
| Supabase 계정 | DB와 인증용 | 프로젝트 생성 가능 여부 |
| 도메인 | 커스텀 주소 연결용 | DNS 관리 가능 여부 |
로컬 개발 환경에서는 Node.js가 필요하고, Vercel CLI를 쓰면 환경변수 동기화가 편해집니다. 이 단계에서 중요한 것은 배포와 로컬 개발이 같은 기준으로 움직이도록 준비하는 것입니다.
5. Supabase 프로젝트 생성과 핵심 설정
Supabase는 먼저 프로젝트를 만들어야 합니다. 프로젝트를 생성하면 프로젝트 URL과 키를 확인할 수 있고, 이 값들은 Next.js에서 환경변수로 분리해 사용합니다.[3][4]
보통 공개 클라이언트에서 필요한 값은 다음처럼 둡니다. 이 값들은 코드에 직접 넣지 말고 환경변수로 관리해야 합니다. 그래야 배포 환경과 로컬 환경을 같은 방식으로 유지할 수 있고, 보안도 더 좋습니다.[3]
| 환경변수 | 용도 |
|---|---|
NEXT_PUBLIC_SUPABASE_URL |
Supabase 프로젝트 주소 |
NEXT_PUBLIC_SUPABASE_ANON_KEY |
브라우저용 공개 키 |
이 단계에서 확인할 것은 두 가지입니다. 첫째, 프로젝트 URL과 anon key가 맞는지 보는 것. 둘째, 이후 Vercel에서도 같은 이름의 환경변수를 등록할 준비를 하는 것입니다.
6. Vercel 프로젝트 생성과 GitHub 연결
이제 Vercel에서 새 프로젝트를 만들고 GitHub 저장소를 연결합니다. Vercel의 기본 흐름은 New Project를 만들고, GitHub repo를 선택한 뒤 Import해서 배포하는 방식입니다.[1][3]
이 단계의 목적은 코드 저장소와 배포 플랫폼을 붙여서, 앞으로는 GitHub에 푸시만 해도 자동으로 배포되게 만드는 것입니다. 기존 프로젝트가 있으면 Import로 가져오면 되고, 없다면 Next.js 템플릿부터 시작해도 됩니다.
- 새 프로젝트 생성
- GitHub 저장소 연결
- 환경변수 입력
- 첫 배포 실행
배포가 끝나면 Vercel이 기본 도메인을 만들어 줍니다. 여기까지가 첫 번째 완성 지점이며, 이후 Supabase연결과 인증 설정을 붙이면 실서비스 구조가 됩니다.
7. Vercel과 Supabase를 실제로 연결하는 방법
Supabase Vercel 연동의 핵심은 Vercel Integration을 통해 Supabase프로젝트를 연결하는 것입니다. 공식 자료는 Vercel과 Supabase를 연결해 앱의 배포 흐름과 데이터 흐름을 함께 관리하는 방식을 안내합니다.[3][8]
실무에서는 다음 순서가 가장 깔끔합니다. 이 흐름을 쓰면 배포 환경의 환경변수를 로컬로 내려받아 개발 환경과 배포 환경을 맞출 수 있습니다.[1]
- Vercel 프로젝트에서 Supabase Integration 연결
- 연결할 Supabase 프로젝트 선택
- Vercel 환경변수 등록
- 로컬 환경으로 환경변수 내려받기
- 앱 실행 확인
여기서 중요한 점은 로컬에서 되던 코드가 배포에서 안 되는 문제를 줄이는 것입니다. 환경변수 이름이 다르거나 값이 빠지면 배포 후 오류가 생기기 쉽습니다.
8. Next.js에서 Supabase 클라이언트 구성하기
Next.js에서는 Supabase 클라이언트를 따로 만들어 재사용하는 방식이 가장 편합니다. @supabase/supabase-js를 설치한 뒤 `supabase.ts` 같은 파일을 만들고, 앱 전반에서 같은 클라이언트를 쓰게 하면 됩니다.[3]
원칙은 간단합니다. 브라우저에서 필요한 값은 NEXT_PUBLIC_ 접두사를 붙이고, 서버에서만 쓸 값은 따로 분리하며, 클라이언트 생성 코드는 한 곳에 모읍니다. 이렇게 하면 코드가 짧아지고 실수도 줄어듭니다.[3][4]
- 브라우저 값과 서버 값을 분리한다
- 클라이언트 생성 코드는 한 곳에 모은다
- 재사용 가능한 설정 파일을 만든다
여기서 확인할 것은 클라이언트 코드가 브라우저에서 안전하게 동작하는지, 그리고 서버 전용 값이 노출되지 않는지입니다.
9. Next.js Server Actions와 Vercel에서의 사용 방식
Next.js Server Actions Vercel 구조는 폼 제출이나 데이터 쓰기 작업을 API Route 없이 서버에서 바로 처리하는 방식입니다. 쉽게 말해, 사용자가 버튼을 누르면 서버에서 Supabase에 직접 저장하고, 그 결과를 다시 화면에 반영하는 구조입니다.
Server Actions가 좋은 이유는 명확합니다. API 파일을 따로 만들 필요가 적고, 서버 전용 로직을 더 단순하게 쓸 수 있으며, 폼 처리와 데이터 저장 흐름이 짧아집니다. Vercel 배포 환경에서는 서버 전용 코드와 클라이언트 코드를 분리해 환경변수를 안전하게 관리해야 합니다.[3][8]
- API 파일을 줄일 수 있다
- 서버 전용 로직이 단순해진다
- 폼 처리와 저장 흐름이 짧아진다
이 구조를 잘 쓰면 문의 폼, 댓글, 주문 생성, 프로필 수정 같은 기능을 빠르게 만들 수 있습니다.
10. Server Actions로 Supabase 데이터 쓰기 흐름 설계
Server Actions와 Supabase를 함께 쓰면 보통 폼 제출이 들어올 때 Server Action이 실행되고, 그 안에서 Supabaseinsert나 update를 수행한 뒤 UI를 갱신합니다. 이 흐름은 API 레이어를 얇게 유지하면서도 서버 중심 로직을 안정적으로 운영할 수 있게 해 줍니다.
가장 흔한 사용 예시는 아래와 같습니다. 무엇을 저장할지, 어디에 저장할지, 성공하면 무엇을 보여줄지를 먼저 정하면 서버 액션 코드가 깔끔해집니다.[2][3]
| 기능 | 동작 | 저장 위치 |
|---|---|---|
| 문의 폼 | 입력값 저장 | contacts 테이블 |
| 댓글 작성 | 새 댓글 추가 | comments 테이블 |
| 주문 생성 | 주문 데이터 저장 | orders 테이블 |
| 프로필 수정 | 사용자 정보 업데이트 | profiles 테이블 |
이 방식의 핵심은 성공 후 사용자에게 무엇을 보여줄지까지 함께 설계하는 것입니다. 데이터 저장만 성공하고 화면 반영이 어색하면 실제 사용성은 떨어집니다.
11. Supabase Auth 또는 NextAuth 중 무엇을 쓸지 정리
인증은 크게 두 선택지가 있습니다. Supabase Auth를 쓰거나, NextAuth Vercel 설정으로 NextAuth를 붙이는 방식입니다. Supabase Auth는 Supabase 생태계와의 연결이 쉽고, NextAuth는 Next.js 중심의 인증 흐름을 더 세밀하게 다루기 좋습니다.[3][8]
둘 중 하나가 무조건 정답은 아닙니다. Supabase DB와 인증을 한 세트로 쓰려면 Supabase Auth가 편하고, 외부 OAuth와 세밀한 세션 제어가 중요하면 NextAuth가 좋습니다.
| 항목 | Supabase Auth | NextAuth |
|---|---|---|
| 연동 난이도 | 비교적 간단 | 설정이 더 많음 |
| Supabase DB 연동 | 매우 자연스러움 | 직접 연결 필요 |
| 커스터마이징 | 기본형에 강함 | 확장에 강함 |
| 추천 상황 | 빠른 MVP | 복잡한 로그인 정책 |
12. NextAuth를 Vercel에 설정할 때 꼭 챙길 것
NextAuth Vercel 설정에서 가장 중요한 것은 환경변수와 callback URL입니다. 배포 환경에서는 로컬 주소가 아니라 실제 Vercel 배포 도메인과 커스텀 도메인을 기준으로 설정해야 합니다.
꼭 챙길 항목은 다음과 같습니다. 로컬에서는 .env.local로 맞추고, 배포에서는 Vercel 대시보드에 같은 값을 넣어야 합니다. Vercel의 환경변수 pull 흐름을 쓰면 로컬과 배포를 쉽게 맞출 수 있습니다.[1]
NEXTAUTH_URLNEXTAUTH_SECRET- OAuth 제공자 설정
- callback URL
- Vercel 환경변수 등록
도메인이 바뀌면 callback URL도 바꿔야 하므로, Vercel 도메인 연결과 인증 설정은 같이 봐야 합니다.
13. Vercel 도메인 연결 실전 가이드
Vercel 도메인 연결은 단순히 주소를 예쁘게 만드는 작업이 아닙니다. 브랜딩을 맞추고, 인증 callback URL을 안정적으로 유지하고, 서비스 운영 기준 주소를 만드는 작업입니다.[1][3]
도메인을 붙일 때는 아래를 확인합니다. 이 순서를 놓치면 로그인은 로컬에서는 되는데 배포에서는 실패하는 일이 생길 수 있습니다.
- Vercel 프로젝트에 커스텀 도메인 추가
- DNS 레코드 설정
- SSL 활성화 확인
- 전파 상태 확인
- 인증 URL과 도메인 일치 여부 확인
도메인 연결은 배포의 마지막 단계가 아니라 인증 설정과 함께 움직여야 합니다.
14. Supabase 보안 설정과 RLS 정책
Supabase를 실서비스에 쓰려면 RLS, 즉 Row Level Security를 반드시 이해해야 합니다. RLS는 누가 어떤 데이터를 읽고 쓸 수 있는지 제한하는 Supabase의 핵심 보안 장치입니다.[5][8]
기본 원칙은 간단합니다. 공개 데이터는 읽기 허용 범위를 넓게 두고, 사용자 데이터는 본인만 접근하게 하며, 인증된 사용자와 비인증 사용자를 분리해야 합니다.
- 공개 데이터는 읽기 허용 범위를 넓게 둔다
- 사용자 데이터는 본인만 접근하게 한다
- 인증된 사용자와 비인증 사용자를 분리한다
예를 들어, 공지사항은 누구나 읽을 수 있어도 되지만, 프로필 정보는 로그인한 사용자만 자기 정보만 봐야 합니다. 이런 구분이 없으면 DB는 열려 보이지만 실제 서비스로는 불안정합니다.
15. 운영 체크리스트와 자주 나는 문제
배포 후에는 아래 문제를 가장 먼저 확인해야 합니다. 증상부터 확인하고, 그다음 원인과 위치를 좁혀 가는 순서가 가장 빠릅니다.[1][3][4]
| 증상 | 흔한 원인 | 확인할 곳 |
|---|---|---|
| 로컬에서는 되는데 배포에서 안 됨 | 환경변수 누락 | Vercel 환경변수 |
| 로그인 실패 | callback URL 불일치 | NextAuth 설정 |
| Supabase 연결 오류 | 키 값 오류 | 프로젝트 URL, anon key |
| 도메인 접속 지연 | DNS 전파 중 | 도메인 설정 |
| 데이터 저장 실패 | RLS 정책 문제 | Supabase 정책 |
특히 NEXT_PUBLIC_ 접두사를 잘못 붙이거나 빼는 실수가 많습니다. 또 Vercel CLI의 환경변수 pull 기능을 쓰지 않으면, 같은 코드인데도 결과가 달라질 수 있습니다.
16. 실무에서 가장 추천하는 최종 구성안
초보자에게 가장 무난한 조합은 Next.js + Vercel + Supabase + Server Actions + 필요 시 NextAuth입니다. 이 조합은 구현 순서가 분명하고, 개인 프로젝트부터 SaaS MVP, 관리자 대시보드까지 확장하기 쉽습니다.[3][8]
추천 순서는 아래와 같습니다. 이 순서대로 따라가면 문서형으로 외우지 않아도 실제 서비스 수준의 구조를 만들 수 있습니다.
- Next.js 프로젝트 준비
- GitHub에 푸시
- Vercel에 Import 배포
- Supabase 프로젝트 생성
- Supabase Integration 연결
- 환경변수 정리
- Server Actions로 쓰기 작업 연결
- 인증 방식 선택
- 도메인 연결
- RLS와 운영 점검
Supabase Vercel 연동을 중심에 두고, Next.js Server Actions Vercel과 NextAuth Vercel 설정, Vercel 도메인 연결을 같은 흐름 안에 넣으면 실제 서비스 수준의 앱을 만들 수 있습니다.
17. 자주 묻는 질문 (FAQ)
Supabase Vercel 연동은 꼭 Integration으로 해야 하나요?
꼭 그런 것은 아니지만, Integration을 쓰면 환경변수와 프로젝트 연결을 한 번에 관리하기 쉬워집니다. 수동 설정도 가능하지만 운영 편의성은 통합 방식이 더 좋습니다.[3][8]
Next.js Server Actions는 Vercel에서만 사용할 수 있나요?
Server Actions 자체는 Next.js 기능이지만, Vercel은 이를 배포하고 운영하기 좋은 환경을 제공합니다. 서버 코드와 클라이언트 코드를 분리해 쓰는 방식이 특히 잘 맞습니다.[3]
Supabase Auth와 NextAuth 중 무엇이 더 좋은가요?
정답은 프로젝트 목적에 따라 다릅니다. Supabase DB와 인증을 한 흐름으로 묶고 싶으면 Supabase Auth가 편하고, 외부 OAuth나 세션 제어를 더 세밀하게 다루려면 NextAuth가 유리합니다.[3][8]
Vercel 도메인 연결 후 로그인 오류가 나면 무엇부터 봐야 하나요?
가장 먼저 callback URL과 환경변수를 확인해야 합니다. 로컬 주소가 남아 있거나 도메인이 바뀌었는데 설정이 그대로면 인증이 실패할 수 있습니다.[1]
Supabase에서 데이터가 저장되지 않을 때 가장 흔한 원인은 무엇인가요?
가장 흔한 원인은 RLS 정책과 키 설정 문제입니다. 먼저 anon key와 프로젝트 URL을 확인하고, 그다음 테이블 정책을 점검하는 순서가 효율적입니다.[5][8]