Vercel 도메인 연결 방법 완벽 가이드

VIBE CODING · WEBSITE GUIDE

Vercel 도메인 연결 방법

무료 주소 변경부터 개인 도메인 연결, DNS 설정까지 초보자도 쉽게 따라 할 수 있는 실전 가이드입니다.

AI로 웹사이트를 만들고 Vercel에 배포했다면 이제 나만의 주소를 연결할 차례입니다.

처음 배포하면 vercel.app이라는 주소가 제공됩니다. 이 주소를 그대로 사용해도 되지만, 개인 도메인을 연결하면 더욱 전문적인 웹사이트를 운영할 수 있습니다.

이번 글에서는 무료 주소 변경 방법과 개인 도메인 연결 방법을 단계별로 알아보겠습니다.

이 글의 목차

1. 도메인과 DNS 이해하기
2. Vercel 도메인 연결 방식
3. 무료 주소 변경하기
4. 개인 도메인 구매하기
5. Vercel에 도메인 등록하기
6. A 레코드와 CNAME 설정하기
7. 연결 오류 해결하기

01. 도메인과 DNS 이해하기

도메인은 인터넷에서 내 웹사이트를 찾아올 수 있도록 만들어 주는 주소입니다.

예를 들어 다음과 같은 주소가 있습니다.

google.com

naver.com

mywebsite.com

웹사이트는 실제로 서버의 IP 주소를 통해 접속합니다. 하지만 숫자로 된 주소는 기억하기 어렵기 때문에 사람이 쉽게 기억할 수 있는 도메인을 사용합니다.

DNS란 무엇일까?

DNS는 도메인 이름을 실제 서버 주소와 연결해 주는 시스템입니다.

도메인 : 웹사이트 주소

DNS : 도메인과 서버를 연결하는 시스템

DNS 레코드 : 연결에 필요한 설정 정보

02. Vercel 도메인 연결 방식

Vercel에서는 기본 제공 주소를 사용하거나 별도로 구매한 개인 도메인을 연결할 수 있습니다.

방법 A. 무료 Vercel 주소

예시: myblog.vercel.app

별도의 도메인 구매 비용 없이 사용할 수 있습니다. 개인 프로젝트나 테스트용 웹사이트에 적합합니다.

방법 B. 개인 도메인

예시: mywebsite.com

직접 구매한 도메인을 연결하는 방법입니다. 브랜드나 사업용 웹사이트에 적합합니다.

추천

처음에는 무료 Vercel 주소를 사용하세요. 웹사이트가 완성된 뒤 개인 도메인을 연결해도 늦지 않습니다.

03. 무료 Vercel 주소 변경하기

무료 주소는 별도의 도메인을 구매하지 않고 사용할 수 있습니다.

변경 전

my-first-site.vercel.app

변경 후 예시

myblog.vercel.app

STEP 1. Vercel 로그인

Vercel 대시보드 바로가기

로그인한 뒤 주소를 변경할 프로젝트를 선택합니다.

STEP 2. 프로젝트 설정

프로젝트의 Settings 메뉴에서 Domains 항목으로 이동합니다.

STEP 3. 주소 변경

현재 등록된 기본 주소를 확인합니다. 변경 가능한 주소 설정에서 원하는 이름을 지정합니다.

STEP 4. 저장 및 확인

변경 사항을 저장한 다음 새 주소로 접속합니다.

주의: 이미 다른 사용자가 등록한 주소는 사용할 수 없습니다. 또한 Vercel의 프로젝트 이름과 배포 도메인은 서로 다른 설정일 수 있으므로 Domains 메뉴에서 실제 연결 상태를 확인하세요.

04. 개인 도메인 구매하기

나만의 도메인을 사용하려면 먼저 도메인 등록 업체에서 원하는 주소를 구매해야 합니다.

국내에서는 가비아 등의 서비스를 이용할 수 있습니다.

가비아 공식 홈페이지 바로가기

구매 전 확인할 사항

• 도메인 이름이 짧고 기억하기 쉬운가?
• 첫해 등록 비용은 얼마인가?
• 다음 해 갱신 비용은 얼마인가?
• 자동 연장 설정은 어떻게 되어 있는가?
• 원하는 도메인을 사용할 수 있는가?

특히 첫해 할인 가격만 확인하지 마세요. 다음 해 갱신 비용까지 비교하는 것이 좋습니다.

05. 구매한 도메인을 Vercel에 등록하기

STEP 1. Domains 메뉴 열기

Vercel 대시보드에서 연결할 프로젝트를 선택합니다.

Settings → Domains 메뉴로 이동합니다.

STEP 2. 도메인 추가

Add Domain 또는 Add Existing 버튼을 클릭합니다.

구매한 도메인 주소를 입력합니다.

mywebsite.com

입력할 때 https://는 제외합니다.

STEP 3. DNS 설정값 확인

도메인을 추가하면 Vercel에서 DNS 설정에 필요한 정보를 안내합니다.

이 정보를 확인한 다음 도메인 등록 업체의 DNS 관리 페이지로 이동합니다.

06. A 레코드와 CNAME 설정하기

DNS 설정에서 가장 많이 사용하는 레코드는 A 레코드와 CNAME입니다.

① A 레코드

A 레코드는 도메인을 IPv4 주소와 연결합니다.

항목	설정 예시
타입	A
호스트	@
값	Vercel 안내 IP 주소

② CNAME 레코드

CNAME은 www와 같은 하위 도메인을 다른 도메인 이름으로 연결합니다.

항목	설정 예시
타입	CNAME
호스트	www
값	Vercel 안내 주소

중요한 설정 주의사항

위 표는 이해를 돕기 위한 일반적인 예시입니다. 실제 IP 주소와 CNAME 값은 프로젝트별 안내에 따라 입력해야 합니다.

기존 DNS 레코드와 충돌하지 않는지도 확인하세요.

DNS 설정을 저장한 다음 Vercel로 돌아옵니다.

정상적으로 연결되면 Valid Configuration 상태를 확인할 수 있습니다.

07. 도메인 연결 확인하기

DNS 설정을 마쳤다면 다음 항목을 확인합니다.

연결 확인 체크리스트

□ Vercel Domains 메뉴에서 상태 확인

□ Valid Configuration 표시 확인

□ 기본 도메인 접속 테스트

□ www 주소 접속 테스트

□ HTTPS 보안 연결 확인

DNS 정보는 변경 후 전파되는 시간이 필요합니다. 따라서 설정 직후 접속되지 않더라도 잠시 기다린 후 다시 확인하세요.

08. 도메인 연결 오류 해결하기

Invalid Configuration 오류

DNS 레코드가 잘못되었거나 아직 전파되지 않았을 수 있습니다.

• A 레코드 값 확인
• CNAME 값 확인
• 중복되거나 충돌하는 레코드 확인

기존 웹사이트가 계속 나타나는 경우

브라우저 캐시 또는 DNS 캐시 문제일 수 있습니다.

• Ctrl + F5로 새로고침
• 시크릿 창에서 접속
• DNS 전파 시간 기다리기

SSL 인증서 오류

DNS 검증이 완료되지 않았거나 인증서 발급이 진행 중일 수 있습니다. Vercel의 도메인 상태를 먼저 확인하세요.

09. 도메인 연결 후 해야 할 일

도메인 연결이 완료되었다면 웹사이트 운영을 위한 마무리 작업을 진행하세요.

• GitHub README에 새 주소 기록하기
• 이메일 서명에 웹사이트 주소 추가하기
• Google Search Console에 사이트 등록하기
• www 주소와 기본 도메인 연결 확인하기
• 도메인 갱신일 기록하기

마무리: 나만의 웹사이트 주소 만들기

Vercel 도메인 연결은 처음에는 복잡하게 느껴질 수 있습니다.

하지만 기본 원리를 이해하면 어렵지 않습니다.

무료 주소를 사용한다면 Vercel에서 기본 주소를 설정하면 됩니다. 개인 도메인을 사용한다면 도메인을 등록하고 DNS 레코드를 연결하면 됩니다.

처음에는 무료 주소로 시작하고, 웹사이트가 완성되면 나만의 도메인을 연결해 보세요.

공식 참고 자료

Vercel 도메인 공식 문서

Vercel 대시보드

가비아 도메인 서비스

AI 웹사이트 제작 · Vercel 활용 가이드

Gemini API 연결 방법: Google AI Studio와 Vercel로 나만의 AI 웹사이트 만들기

Gemini API 연결 방법 

웹사이트에 인공지능 기능을 추가하고 싶으신가요? Gemini API 연결 방법을 알면 단순한 웹페이지를 사용자의 질문에 답하는 AI 웹사이트로 바꿀 수 있습니다.

이번 글에서는 Google AI Studio에서 API 키를 발급받고, Next.js로 만든 웹사이트에 Gemini를 연결하는 방법을 알아보겠습니다.

코딩을 처음 접하는 분도 따라 할 수 있도록 API 키 발급부터 Vercel 배포까지 단계별로 정리했습니다.

이번 글에서 완성할 기능

• 웹사이트에서 사용자가 질문을 입력합니다.
• 서버가 Gemini API에 질문을 전달합니다.
• Gemini가 생성한 답변을 웹페이지에 표시합니다.
• 로컬 컴퓨터와 인터넷에 공개된 사이트에서 모두 작동하는지 확인합니다.

1. Gemini API란 무엇인가?

Gemini API는 Google의 인공지능 모델을 외부 프로그램에서 사용할 수 있도록 제공하는 연결 통로입니다.

쉽게 말하면 웹사이트와 Gemini가 대화할 수 있도록 연결해 주는 창구입니다.

예를 들어 사용자가 웹사이트에 다음과 같이 입력했다고 가정해 보겠습니다.

사용자 질문

오늘 하루를 긍정적으로 시작할 수 있는 문장을 만들어 줘.

웹사이트는 이 질문을 서버로 전달합니다.

서버는 Gemini API를 통해 질문을 보내고, Gemini가 생성한 답변을 다시 웹사이트로 전달합니다.

이 과정은 다음과 같습니다.

사용자

질문 입력

↓

내 웹사이트

서버에 질문 전달

↓

Gemini API

인공지능 답변 생성

↓

내 웹사이트

답변을 화면에 표시

이처럼 API를 연결하면 별도의 인공지능 모델을 직접 개발하지 않아도 AI 기능을 웹사이트에 추가할 수 있습니다.

2. 실습용 스타터 프로젝트 준비하기

이번 실습에서는 화면이 미리 만들어진 프로젝트를 사용합니다.

화면을 처음부터 제작하는 대신, Gemini를 연결하는 부분에 집중할 수 있습니다.

① GitHub 스타터 저장소 열기

아래 주소를 열어 실습용 프로젝트를 확인합니다.

AI Mini App Starter GitHub 저장소

② 내 저장소 만들기

1. GitHub에 로그인합니다.
2. 저장소 오른쪽 위의 Use this template을 누릅니다.
3. Create a new repository를 선택합니다.
4. Repository name에 my-first-ai-app을 입력합니다.
5. 공개 범위는 Public을 선택합니다.
6. Create repository를 눌러 저장소를 만듭니다.

이제 내 계정에 실습용 프로젝트가 복사됩니다.

③ 내 컴퓨터로 프로젝트 가져오기

안티그래비티에서 File → Open Folder를 선택합니다.

바탕화면에 my-first-ai-app이라는 새 폴더를 만들고 엽니다.

그다음 AI 도구에 다음 내용을 요청합니다.

복사용 프롬프트

이 폴더는 비어 있습니다. GitHub에 만든 내 저장소를 현재 폴더 안으로 받아 주세요. git clone 주소 . 명령을 사용해 주세요. 그다음 npm install을 실행해 필요한 패키지를 설치해 주세요. 작업이 끝나면 결과를 한국어로 설명해 주세요.

여기서 내 저장소 주소는 방금 만든 GitHub 저장소 주소로 바꿔야 합니다.

설치가 끝나면 왼쪽 파일 목록에서 app, lib, .env.example, .gitignore 파일을 확인합니다.

3. Google AI Studio에서 Gemini API 키 발급받기

Gemini API를 사용하려면 먼저 API 키가 필요합니다.

API 키는 내 웹사이트가 Google AI 서비스에 접근할 수 있도록 인증하는 비밀 열쇠입니다.

① Google AI Studio 접속

아래 공식 주소를 엽니다.

Google AI Studio API 키 발급 페이지

개인 Google 계정으로 로그인합니다.

② API 키 만들기

1. Create API key 또는 API 키 만들기를 누릅니다.
2. 프로젝트 선택 화면이 나오면 안내에 따라 프로젝트를 선택합니다.
3. API 키가 생성되면 복사 아이콘을 누릅니다.
4. 복사한 키를 다음 단계에서 사용할 수 있도록 준비합니다.

API 키 보안 주의사항

API 키는 비밀번호처럼 관리해야 합니다. 코드 파일이나 GitHub에 올리면 안 됩니다.

AI 채팅창, 카카오톡, 이메일, 캡처 화면에도 붙여 넣지 마세요.

③ 무료 사용 시 주의할 점

Gemini API에는 무료 사용 등급이 있습니다.

다만 모든 모델과 기능을 무제한으로 사용할 수 있는 것은 아닙니다. 모델별 요청 횟수와 사용량 제한이 적용됩니다.

무료 등급으로 전송한 콘텐츠는 Google 제품 개선에 사용될 수 있다고 안내되어 있습니다.

따라서 실습용 웹사이트에는 이름, 전화번호, 주소, 건강 정보 등 민감한 개인정보를 입력하지 않는 것이 좋습니다.

사용량과 요금은 변경될 수 있으므로 실제 사용 전 공식 요금표를 확인하세요.

Gemini API 공식 요금 안내

4. .env 파일에 API 키 안전하게 보관하기

API 키를 발급받았다면 이제 내 컴퓨터에 안전하게 보관해야 합니다.

이때 사용하는 파일이 .env입니다.

.env는 API 키와 같은 민감한 정보를 소스 코드와 분리해서 보관하는 환경 변수 파일입니다.

① 먼저 .gitignore 확인하기

API 키를 입력하기 전에 반드시 .gitignore 파일부터 확인합니다.

파일 안에 다음 내용이 있는지 확인하세요.

.env*

!.env.example

첫 번째 줄은 .env로 시작하는 파일을 Git이 추적하지 않도록 합니다.

두 번째 줄은 예시 파일인 .env.example은 저장소에 포함할 수 있도록 예외 처리합니다.

② .env 파일 만들기

.env.example 파일을 복사해 같은 폴더에 .env라는 이름으로 저장합니다.

파일을 열어 다음 항목을 확인합니다.

GEMINI_API_KEY=여기에_본인_API_키

안내 문구를 지우고 복사한 실제 API 키를 붙여 넣습니다.

등호 앞뒤에 공백이나 불필요한 따옴표를 넣지 않습니다.

입력한 뒤 Ctrl + S를 눌러 저장합니다.

③ Git에서 .env가 제외되었는지 확인

터미널에서 다음 명령어를 실행합니다.

git status

변경 파일 목록에 .env가 나타나지 않아야 합니다.

.env.example은 보여도 괜찮습니다. 실제 API 키가 들어 있는 .env가 보이지 않는지 확인하는 것이 중요합니다.

중요한 보안 확인

이미 Git이 .env 파일을 추적하고 있었다면 .gitignore에 추가하는 것만으로는 충분하지 않습니다.

이 경우 커밋이나 푸시를 멈추고 추적 상태를 먼저 바로잡아야 합니다.

5. Gemini API를 웹사이트에 연결하기

이제 웹사이트와 Gemini를 실제로 연결할 차례입니다.

스타터 프로젝트에는 Gemini API를 호출할 파일이 준비되어 있습니다.

안티그래비티 왼쪽 파일 목록에서 다음 경로를 엽니다.

app/api/gemini/route.ts

파일 안에 있는 TODO 부분을 채우도록 AI에게 요청합니다.

Gemini 연결 복사용 프롬프트

이 route.ts 파일의 TODO 부분을 완성해 주세요.

• Google 공식 패키지 @google/genai를 사용해 주세요.
• 모델은 gemini-3.5-flash-lite를 사용해 주세요.
• 사용자가 입력한 prompt를 Gemini API에 전달해 주세요.
• 생성된 답변은 { text: '답변 내용' } 형식으로 NextResponse.json에 담아 반환해 주세요.
• API 키는 process.env.GEMINI_API_KEY에서 읽어 주세요.
• API 키를 코드에 직접 작성하지 마세요.
• API 키가 없거나 요청에 실패하면 적절한 HTTP 오류 상태와 메시지를 반환해 주세요.
• 서버에서만 API를 호출하고 브라우저에 API 키가 노출되지 않도록 해 주세요.

AI가 패키지를 설치하거나 파일을 수정하겠다고 요청하면 내용을 확인하고 진행합니다.

수정된 코드에서 확인할 부분

AI가 작업을 마쳤다면 다음 두 가지를 확인합니다.

• @google/genai 패키지를 사용하는지 확인합니다.
• process.env.GEMINI_API_KEY에서 API 키를 읽는지 확인합니다.

실제 API 키 문자열이 코드 안에 들어 있다면 해당 코드를 그대로 사용하지 마세요.

Gemini 모델은 변경될 수 있습니다. 모델을 찾을 수 없다는 오류가 나오면 Google 공식 모델 목록에서 현재 사용 가능한 모델명을 확인해야 합니다.

Gemini API 공식 모델 목록

6. 내 컴퓨터에서 Gemini 연결 테스트하기

코드 수정이 끝났다면 먼저 인터넷에 공개하기 전에 내 컴퓨터에서 테스트합니다.

안티그래비티에 다음과 같이 요청합니다.

사이트를 실행해 주세요. npm run dev 명령을 사용하고, 브라우저에서 접속할 주소를 알려 주세요.

서버가 실행되면 보통 다음 주소가 표시됩니다.

http://localhost:3000

브라우저에서 안내된 주소를 엽니다.

스타터 화면에는 다음과 같은 AI 기능 카드가 준비되어 있습니다.

• AI 자기소개 도우미
• 내 마음 위로 받기
• 한 줄 일기 펼치기
• AI 명언 생성기
• 메일 문구 다듬기

카드 하나를 선택하고 간단한 질문을 입력합니다.

버튼을 눌렀을 때 Gemini가 생성한 답변이 화면에 나타나면 연결에 성공한 것입니다.

.env 파일을 수정했다면 서버 재시작

개발 서버는 실행할 때 환경 변수를 읽습니다.

따라서 API 키를 새로 입력하거나 변경했다면 기존 서버를 종료해야 합니다.

1. 터미널에서 Ctrl + C를 누릅니다.
2. 개발 서버를 다시 실행합니다.
3. 브라우저를 새로 고침합니다.
4. 질문을 입력해 다시 테스트합니다.

7. GitHub에 올리고 Vercel에 배포하기

내 컴퓨터에서 Gemini가 정상적으로 작동한다면 이제 인터넷에 공개할 차례입니다.

여기서 꼭 알아야 할 점이 있습니다.

Vercel은 GitHub에 올라간 코드만으로 내 컴퓨터의 .env 파일을 자동으로 가져오지 못합니다.

따라서 Vercel에도 API 키를 별도로 등록해야 합니다.

① GitHub에 코드 업로드

안티그래비티에 변경 내용을 커밋하고 GitHub로 푸시해 달라고 요청합니다.

지금까지 수정한 내용을 GitHub에 커밋하고 푸시해 주세요. 커밋 메시지는 '제미나이연결'로 해 주세요. 먼저 git status로 변경 파일을 보여 주고 .env가 포함되지 않았는지 확인해 주세요.

푸시하기 전에 변경 파일 목록에 .env가 없는지 다시 확인합니다.

GitHub 저장소를 열어 .env.example은 있지만 .env는 없는지 확인합니다.

② Vercel에서 프로젝트 가져오기

1. Vercel 공식 사이트에 접속합니다.
2. 대시보드에서 Add New를 선택합니다.
3. Project를 선택합니다.
4. GitHub에 올린 my-first-ai-app 저장소를 찾습니다.
5. Import를 누릅니다.

③ 환경 변수 등록하기

프로젝트 설정 화면에서 Environment Variables 항목을 찾습니다.

다음과 같이 입력합니다.

Name

GEMINI_API_KEY

Value

Google AI Studio에서 발급받은 실제 API 키

이름은 반드시 GEMINI_API_KEY로 입력해야 합니다.

대소문자와 밑줄까지 정확하게 입력하세요.

Value에는 실제 API 키를 붙여 넣습니다.

등록이 끝나면 Deploy를 눌러 배포를 시작합니다.

④ 배포 완료 확인하기

배포 상태가 Ready로 바뀌면 Vercel이 제공하는 공개 주소를 엽니다.

로컬 테스트 때와 마찬가지로 질문을 입력하고 답변이 나오는지 확인합니다.

인터넷에 공개된 주소에서도 정상적으로 답변이 나오면 Gemini API 연결이 완료된 것입니다.

⑤ 환경 변수를 나중에 등록했다면 Redeploy

처음 배포할 때 API 키를 등록하지 않았다면 나중에 환경 변수를 추가할 수 있습니다.

다만 환경 변수 변경은 이미 완료된 기존 배포에 자동으로 적용되지 않습니다.

1. Vercel 프로젝트에서 Settings를 엽니다.
2. Environment Variables를 선택합니다.
3. GEMINI_API_KEY 항목을 추가하거나 수정합니다.
4. Save를 누릅니다.
5. Deployments 메뉴로 이동합니다.
6. 최신 배포의 메뉴에서 Redeploy를 선택합니다.
7. 새 배포가 Ready 상태가 되면 사이트를 다시 확인합니다.

기억해야 할 핵심

Vercel에 환경 변수를 새로 등록하거나 변경했다면 새 배포가 필요합니다. Redeploy를 완료해야 변경된 값이 적용됩니다.

8. Gemini API 연결 오류와 해결 방법

처음 API를 연결할 때는 오류가 발생할 수 있습니다.

오류 메시지를 확인하고 아래 순서대로 점검하면 대부분의 문제를 찾을 수 있습니다.

① 내 컴퓨터에서는 되지만 공개 사이트에서 오류가 발생하는 경우

Vercel에 API 키가 등록되지 않았거나 새 배포가 적용되지 않았을 가능성이 있습니다.

• Vercel Settings에서 환경 변수를 확인합니다.
• GEMINI_API_KEY 이름이 정확한지 확인합니다.
• 값이 정상적으로 저장되었는지 확인합니다.
• Redeploy를 실행합니다.

② 404 또는 모델을 찾을 수 없다는 오류

코드에 입력한 모델명이 잘못되었거나 더 이상 제공되지 않는 모델일 수 있습니다.

Google 공식 모델 목록에서 현재 사용할 수 있는 모델명을 확인한 뒤 코드의 모델명을 수정합니다.

③ 429 또는 quota 오류

무료 등급의 요청 횟수나 사용량 한도에 도달했을 수 있습니다.

잠시 기다린 후 다시 요청하거나 Google AI Studio의 사용량 제한을 확인합니다.

④ API 키 인증 오류

API 키가 잘못 입력되었거나 삭제·폐기된 경우 발생할 수 있습니다.

• Google AI Studio에서 키가 유효한지 확인합니다.
• .env의 키 값에 공백이 들어갔는지 확인합니다.
• Vercel의 환경 변수 값도 확인합니다.
• 키를 새로 발급했다면 로컬 서버를 재시작하고 Vercel도 Redeploy합니다.

⑤ 아직 Gemini API가 연결되지 않았다는 메시지

스타터 프로젝트의 TODO 부분이 아직 수정되지 않았을 수 있습니다.

app/api/gemini/route.ts 파일을 다시 확인하고 Gemini 연결 작업이 완료되었는지 확인합니다.

9. API 키가 노출되었다면 어떻게 해야 할까?

API 키가 GitHub나 채팅창에 공개되었다면 단순히 파일에서 지우는 것으로 끝내면 안 됩니다.

다른 사람이 이미 키를 복사했을 가능성이 있기 때문입니다.

다음 순서로 조치하는 것이 안전합니다.

1. Google AI Studio에서 노출된 API 키를 삭제하거나 폐기합니다.
2. 새 API 키를 발급받습니다.
3. 내 컴퓨터의 .env에 새 키를 입력합니다.
4. Vercel의 GEMINI_API_KEY 값도 교체합니다.
5. Vercel에서 Redeploy를 실행합니다.
6. GitHub 커밋 기록에 키가 남아 있다면 저장소 기록에서도 제거 조치를 합니다.

API 키는 코드에 직접 넣지 마세요.

브라우저에서 실행되는 코드에 API 키를 넣으면 방문자가 개발자 도구 등을 통해 키를 확인할 수 있습니다.

서버에서 API를 호출하고 비밀 키는 환경 변수로 관리해야 합니다.

10. Gemini API 연결 과정 정리

이번 실습에서 진행한 내용을 간단히 정리해 보겠습니다.

1. GitHub 스타터 프로젝트를 내 저장소로 복사합니다.
2. 내 컴퓨터에 프로젝트를 내려받습니다.
3. Google AI Studio에서 Gemini API 키를 발급받습니다.
4. .gitignore를 확인한 뒤 .env 파일을 만듭니다.
5. GEMINI_API_KEY에 실제 키를 입력합니다.
6. route.ts 파일의 TODO 부분을 완성합니다.
7. 로컬 웹사이트에서 Gemini 답변을 테스트합니다.
8. API 키가 제외된 코드만 GitHub에 업로드합니다.
9. Vercel에 환경 변수를 등록합니다.
10. 배포 후 공개 사이트에서 다시 테스트합니다.

이제 단순히 정해진 글자만 보여 주는 웹페이지가 아니라, 사용자의 질문에 따라 답변을 생성하는 AI 웹사이트를 만들 수 있습니다.

마무리: 내 웹사이트에 AI 기능 추가하기

Gemini API를 연결하는 과정에서 가장 중요한 것은 API 키를 안전하게 관리하는 것입니다.

내 컴퓨터에서는 .env 파일에 보관하고, Vercel에서는 환경 변수로 등록합니다.

그리고 GitHub에는 실제 API 키가 포함된 파일을 올리지 않아야 합니다.

이번 과정을 완료했다면 AI 자기소개 도우미, 일기 작성 도우미, 문장 다듬기 등 다양한 기능을 직접 확장할 수 있습니다.

먼저 간단한 질문과 답변 기능부터 완성해 보세요. 작은 기능 하나를 직접 연결해 보는 것이 AI 웹서비스 개발의 좋은 출발점입니다.

공식 참고 자료

• Google AI Studio API 키 발급
• Gemini API 빠른 시작 가이드
• Gemini API 모델 목록
• Gemini API 요금 안내
• Vercel 환경 변수 설정
• 실습용 GitHub 스타터 프로젝트

Vercel과 Resend API 연결하기: 웹사이트에 이메일 문의 기능 만들기

Vercel과 Resend API 연결하기: 

웹사이트에 이메일 문의 기능 만들기

AI로 웹사이트를 만들었다면 다음 단계는 방문자가 직접 나에게 연락할 수 있도록 기능을 추가하는 것입니다.

예를 들어 웹사이트에 이름과 문의 내용을 입력하고 보내기 버튼을 누르면 내 이메일로 편지가 도착하는 기능입니다.

이 기능을 만들 때 사용할 수 있는 서비스가 바로 Resend API입니다.

Resend는 웹사이트나 프로그램에서 이메일을 보낼 수 있도록 도와주는 서비스입니다.

이번 글에서는 안티그래비티로 만든 웹사이트에 Resend를 연결하고, Vercel에 배포한 사이트에서도 이메일을 받을 수 있도록 설정하는 방법을 알아보겠습니다.

이번 글에서 배울 내용

• API와 API 키의 개념
• Resend 회원가입 및 API 키 발급
• .env 파일에 비밀 정보 저장하기
• .gitignore로 API 키 보호하기
• 안티그래비티로 연락하기 기능 만들기
• 내 컴퓨터에서 이메일 전송 테스트
• Vercel 환경 변수 등록하기
• Redeploy로 공개 웹사이트에 적용하기

1. API란 무엇일까?

API라는 말을 처음 들으면 어렵게 느껴질 수 있습니다.

하지만 식당에서 주문하는 과정을 생각하면 쉽게 이해할 수 있습니다.

식당에 가서 음식을 주문하면 직원이 주방에 주문 내용을 전달합니다.

주방에서는 주문에 맞춰 음식을 만들고 다시 손님에게 전달합니다.

API도 비슷합니다.

내 웹사이트가 외부 서비스에 필요한 작업을 요청하면 해당 서비스가 결과를 돌려줍니다.

이메일 서비스로 이해하기

식당 주문과 API 비교

메뉴판 : Resend의 사용 설명서

주문서 : 내 웹사이트가 보내는 이메일 요청

주방 : Resend 이메일 서비스

음식 : 내 메일함에 도착한 이메일

멤버십 카드 : API 키

내 웹사이트에서 방문자가 문의 내용을 작성하면 Resend에 이메일 발송을 요청합니다.

Resend는 요청을 확인한 후 이메일을 전송합니다.

이처럼 서로 다른 프로그램이 정해진 방식으로 정보를 주고받는 통로가 API입니다.

2. API 키란 무엇일까?

Resend API를 사용하려면 API 키가 필요합니다.

API 키는 외부 서비스에 접근할 수 있도록 해주는 인증 정보입니다.

쉽게 말하면 내 웹사이트가 Resend 서비스를 사용할 수 있도록 허락하는 열쇠입니다.

이 열쇠를 다른 사람에게 알려 주면 다른 사람이 내 계정의 권한으로 이메일을 보낼 수도 있습니다.

API 키는 절대 공개하면 안 됩니다.

다음과 같은 곳에 API 키를 입력하지 마세요.

• 공개된 소스코드
• GitHub 저장소
• 안티그래비티 AI 채팅창
• 카카오톡이나 이메일
• 화면 캡처 및 녹화 영상

API 키는 내 컴퓨터의 .env 파일이나 Vercel의 환경 변수에 저장해야 합니다.

3. Resend 회원가입하고 API 키 발급받기

먼저 이메일을 보내는 서비스를 준비해야 합니다.

이번 실습에서는 Resend를 사용하겠습니다.

Resend 공식 홈페이지 바로가기

① Resend 가입하기

Resend 홈페이지에 접속합니다.

오른쪽 위의 Get started를 클릭합니다.

가입 화면에서 Google 계정으로 로그인할 수 있습니다.

이미 계정이 있다면 Log in을 선택합니다.

가입에 사용한 이메일 주소를 기억해 두세요.

이번 실습에서는 이 이메일 주소로 문의 내용을 받겠습니다.

② API Keys 메뉴 선택하기

로그인하면 Resend 대시보드가 나타납니다.

왼쪽 메뉴에서 API Keys를 선택합니다.

오른쪽 위의 + Create API Key 버튼을 클릭합니다.

③ API 키 만들기

API 키를 만드는 화면에서 다음과 같이 설정합니다.

이름 (Name)

my-first-site

권한 (Permission)

Sending access

Name에는 프로젝트 이름을 입력합니다.

Permission은 Sending access를 선택합니다.

이 권한은 이메일 발송에 필요한 권한만 부여하는 설정입니다.

모든 권한을 허용하는 Full access보다 필요한 권한만 사용하는 것이 안전합니다.

설정을 확인한 후 Add 버튼을 클릭합니다.

④ API 키 복사하기

API 키가 생성되면 화면에 인증 정보가 표시됩니다.

Resend는 생성된 키를 처음 한 번만 확인할 수 있도록 제공합니다.

따라서 이때 복사해서 안전한 장소에 저장해야 합니다.

API 키를 분실했다면 기존 키를 다시 확인하려고 하지 말고 새 키를 발급받으면 됩니다.

중요한 보안 주의사항

API 키를 복사한 뒤에는 채팅창이나 메모 앱에 붙여 넣지 마세요. 바로 다음 단계에서 .env 파일에 저장합니다. 다른 사람에게 노출되었다면 해당 키를 폐기하고 새로 발급받아야 합니다.

4. .env 파일과 .gitignore 이해하기

이제 발급받은 API 키를 안전하게 보관해야 합니다.

이때 사용하는 것이 .env 파일입니다.

.env는 비밀 정보를 보관하는 파일

.env는 프로그램이 실행될 때 필요한 비밀 정보를 저장하는 파일입니다.

예를 들어 다음과 같은 정보가 들어갈 수 있습니다.

• API 키
• 이메일 주소
• 데이터베이스 비밀번호
• 외부 서비스 인증 정보

이번 실습에서는 Resend API 키와 이메일 주소를 저장하겠습니다.

.gitignore는 Git에서 제외할 파일을 지정

.gitignore는 Git이 특정 파일을 관리하지 않도록 지정하는 파일입니다.

예를 들어 .env 파일이 GitHub에 올라가면 API 키가 다른 사람에게 공개될 수 있습니다.

따라서 .env 파일을 Git의 관리 대상에서 제외해야 합니다.

두 파일의 역할은 다음과 같습니다.

.env

비밀 정보를 저장하는 파일

.gitignore

GitHub에 비밀 파일이 올라가지 않도록 제외하는 설정

5. .gitignore를 먼저 설정하기

이 단계에서는 순서가 매우 중요합니다.

먼저 .env 파일을 만들지 말고 .gitignore부터 확인해야 합니다.

안티그래비티에서 기존 프로젝트 폴더를 엽니다.

왼쪽 파일 목록에서 .gitignore를 찾아 클릭합니다.

파일 안에 다음 내용이 있는지 확인합니다.

.env*

이 설정은 .env로 시작하는 파일을 Git에서 제외한다는 의미입니다.

만약 없다면 다음 프롬프트를 사용합니다.

📋 안티그래비티 복사용 프롬프트

현재 프로젝트의 .gitignore 파일을 확인해줘. .env* 항목이 있는지 확인하고, 없다면 추가해줘. 기존 설정은 삭제하지 마. 수정한 내용을 보여줘.

설정이 완료되면 다음 단계로 넘어갑니다.

주의

이미 Git이 추적하고 있는 .env 파일은 .gitignore에 추가하는 것만으로 추적이 중단되지 않습니다. 기존에 추적된 적이 있다면 Git 추적 상태도 별도로 확인해야 합니다.

6. .env 파일 만들고 API 키 저장하기

이제 비밀 정보를 저장할 파일을 만듭니다.

안티그래비티의 왼쪽 파일 목록에서 새 파일을 생성합니다.

파일 이름은 다음과 같이 입력합니다.

.env

파일을 열고 다음 두 줄을 작성합니다.

RESEND_API_KEY=실제_API_키
CONTACT_EMAIL=내_이메일_주소

위 내용에서 실제_API_키 부분에는 Resend에서 발급받은 키를 넣습니다.

내_이메일_주소에는 Resend에 가입한 이메일 주소를 입력합니다.

실제 입력할 때는 예시 문구를 그대로 사용하지 않습니다.

작성할 때 주의할 점

• 변수 이름은 대문자로 정확히 입력합니다.
• 등호 앞뒤에 불필요한 공백을 넣지 않습니다.
• 값을 임의로 따옴표로 감싸지 않습니다.
• 파일 이름이 반드시 .env인지 확인합니다.
• 저장한 후 파일을 닫습니다.

이제 Git이 .env 파일을 제외하는지 확인해야 합니다.

안티그래비티에 다음과 같이 요청합니다.

📋 복사용 프롬프트

git status를 실행해서 현재 Git 상태를 보여줘. .env 파일이 변경 목록에 나타나는지 확인하고, API 키나 이메일 주소 같은 비밀 값은 출력하지 마. .env가 목록에 보이면 작업을 중단하고 알려줘.

.env 파일이 변경 목록에 나타나지 않아야 정상입니다.

만약 .env가 표시된다면 GitHub에 올리지 말고 .gitignore와 Git 추적 상태를 다시 확인합니다.

7. 안티그래비티로 연락하기 기능 만들기

이제 웹사이트에 이메일 문의 기능을 추가하겠습니다.

방문자가 이름과 문의 내용을 입력하고 보내기 버튼을 누르면 Resend를 통해 내 이메일로 전달되는 기능입니다.

이번 실습은 Next.js 프로젝트를 기준으로 진행합니다.

① 연락하기 기능 요청하기

안티그래비티에서 새 대화를 열고 다음 프롬프트를 입력합니다.

📋 안티그래비티 복사용 프롬프트

현재 웹사이트 맨 아래에 연락하기 기능을 만들어줘.

입력 항목은 다음과 같아.

• 이름
• 문의 내용
• 보내기 버튼

다음 조건을 지켜줘.

• 공식 Resend 패키지를 사용해줘.
• API 주소는 /api/send로 만들어줘.
• 발신 주소는 onboarding@resend.dev를 사용해줘.
• 받는 주소는 process.env.CONTACT_EMAIL에서 읽어줘.
• API 키는 process.env.RESEND_API_KEY에서 읽어줘.
• API 키와 이메일 주소를 코드에 직접 작성하지 마.
• 서버에서만 API 키를 사용하도록 만들어줘.
• Resend 객체는 요청 처리 함수 안에서 생성해줘.
• 필수 환경변수가 없으면 이해하기 쉬운 오류를 반환해줘.
• 성공하면 화면에 '보냈어요!'를 표시해줘.
• 실패하면 안전하게 처리된 오류 메시지를 보여줘.
• 입력값 검증과 기본적인 스팸 방지 처리를 고려해줘.

기존 웹사이트 디자인과 기능은 유지하고, 필요한 파일만 수정해줘.

여기서 중요한 것은 API 키를 프롬프트에 직접 입력하지 않는 것입니다.

AI에게는 환경변수 이름만 알려주면 됩니다.

② AI가 생성한 코드 확인하기

안티그래비티가 작업을 완료하면 변경된 파일을 확인합니다.

특히 Next.js 프로젝트라면 다음 파일이 생성되거나 수정될 수 있습니다.

app/api/send/route.ts

프로젝트 구조에 따라 API 경로는 다를 수 있습니다.

중요한 것은 다음 세 가지입니다.

• Resend 공식 패키지를 사용했는가?
• API 키를 process.env.RESEND_API_KEY에서 읽는가?
• 받는 주소를 process.env.CONTACT_EMAIL에서 읽는가?

또한 실제 API 키가 코드에 직접 들어가 있으면 안 됩니다.

확인 후 변경 사항을 승인합니다.

③ Resend 객체를 함수 안에서 생성하는 이유

Resend 객체를 서버 코드의 최상단에서 생성하면 환경변수가 없는 상태에서 모듈이 초기화될 때 문제가 발생할 수 있습니다.

따라서 요청 처리 함수 안에서 환경변수를 확인한 다음 객체를 생성하도록 구성하는 것이 좋습니다.

이렇게 하면 환경변수가 누락된 경우에도 사이트 전체가 아니라 이메일 전송 요청에서 오류를 처리할 수 있습니다.

8. 내 컴퓨터에서 이메일 전송 테스트하기

이제 실제로 이메일이 도착하는지 확인하겠습니다.

먼저 안티그래비티에서 개발 서버를 실행합니다.

📋 복사용 프롬프트

현재 프로젝트를 npm run dev 명령어로 실행해줘. 서버가 정상적으로 실행되면 접속할 수 있는 localhost 주소를 알려줘.

보통 다음 주소로 접속할 수 있습니다.

http://localhost:3000

3000번 포트를 다른 프로그램이 사용하고 있다면 3001번 등 다른 포트가 사용될 수 있습니다.

이메일 보내기 테스트

1. 브라우저에서 localhost 주소를 엽니다.
2. 페이지 아래쪽으로 이동합니다.
3. 연락하기 영역을 찾습니다.
4. 이름과 문의 내용을 입력합니다.
5. 보내기 버튼을 클릭합니다.
6. 보냈어요! 메시지가 나타나는지 확인합니다.
7. Resend에 가입한 이메일 계정을 확인합니다.

Gmail을 사용한다면 기본 받은편지함뿐 아니라 업데이트 탭과 스팸함도 확인하세요.

Resend 대시보드의 Emails 메뉴에서도 발송 기록과 상태를 확인할 수 있습니다.

테스트 이메일의 수신 제한

Resend의 기본 테스트 발신 주소인 onboarding@resend.dev를 사용할 때는 수신 주소에 제한이 있습니다.

일반적으로 Resend에 가입한 본인 이메일 주소로 테스트해야 합니다.

다른 사람에게도 이메일을 보내려면 본인 도메인을 Resend에 등록하고 DNS 인증을 완료하는 과정이 필요합니다.

이 부분은 다음 단계에서 도메인을 연결할 때 함께 설정할 수 있습니다.

9. GitHub에 업로드하기 전에 .env 확인하기

내 컴퓨터에서 이메일이 정상적으로 도착했다면 이제 GitHub에 변경 사항을 올립니다.

하지만 여기서 반드시 확인해야 할 것이 있습니다.

.env 파일이 GitHub에 올라가면 안 됩니다.

안티그래비티에 다음과 같이 요청합니다.

📋 복사용 프롬프트

현재 변경된 파일 목록을 확인해줘. .env와 API 키, 비밀번호 등 비밀 정보가 포함된 파일이 커밋 대상에 들어가지 않았는지 확인해줘. 비밀 값 자체는 출력하지 마. 안전한 파일만 커밋하고 GitHub로 push해줘. 커밋 메시지는 '연락하기 이메일 기능 추가'로 해줘.

AI가 보여 주는 파일 목록을 직접 확인합니다.

특히 git add 명령으로 추가되는 파일 목록에 .env가 없는지 확인하세요.

GitHub에 업로드한 뒤에도 저장소의 파일 목록을 새로 고쳐 확인합니다.

.gitignore는 보이지만 .env는 보이지 않아야 정상입니다.

이미 .env가 GitHub에 올라갔다면?

단순히 파일을 삭제하는 것만으로는 충분하지 않습니다.

1. Resend에서 노출된 API 키를 폐기합니다.
2. 새 API 키를 발급받습니다.
3. .env와 Vercel 환경 변수에 새 키를 등록합니다.
4. GitHub에 남은 비밀 정보도 안전하게 정리합니다.
5. 필요하면 Git 기록에서 해당 정보를 제거합니다.

10. Vercel 환경 변수에 API 키 등록하기

이제 가장 중요한 단계입니다.

내 컴퓨터에서는 이메일이 정상적으로 전송되었지만, 인터넷에 공개된 Vercel 주소에서는 오류가 발생할 수 있습니다.

이유는 간단합니다.

Vercel은 GitHub에 올라간 프로젝트 파일을 가져옵니다.

하지만 보안을 위해 GitHub에 올리지 않은 .env 파일까지 자동으로 가져오지는 않습니다.

따라서 Vercel에 비밀 정보를 별도로 등록해야 합니다.

① Vercel 프로젝트 열기

Vercel 홈페이지에 로그인합니다.

앞서 배포한 my-first-site 프로젝트를 선택합니다.

새로운 프로젝트를 만들 필요는 없습니다.

② Environment Variables 메뉴 선택

프로젝트 왼쪽 메뉴에서 Settings 또는 Environment Variables 항목을 찾습니다.

화면에 따라 Settings 안에서 Environment Variables를 선택해야 할 수도 있습니다.

오른쪽 위의 Add Environment Variable 버튼을 클릭합니다.

③ 첫 번째 환경 변수 등록

첫 번째 줄에는 Resend API 키를 등록합니다.

Key

RESEND_API_KEY

Value

Resend에서 발급받은 실제 API 키

Key에는 변수 이름을 입력합니다.

Value에는 실제 API 키를 입력합니다.

값을 입력할 때 앞뒤에 공백이나 따옴표가 들어가지 않도록 주의하세요.

④ 두 번째 환경 변수 등록

다음으로 + Add new variable을 눌러 두 번째 항목을 추가합니다.

Key

CONTACT_EMAIL

Value

Resend 가입에 사용한 이메일 주소

두 변수의 이름은 .env 파일에 작성한 이름과 정확히 일치해야 합니다.

대문자와 밑줄까지 확인하세요.

⑤ Production 환경 확인하기

환경 변수를 적용할 환경을 선택하는 항목이 있습니다.

이번 실습에서는 공개 웹사이트에 적용하기 위해 Production을 선택합니다.

설정을 확인한 다음 Save를 누릅니다.

11. Redeploy를 반드시 실행해야 하는 이유

환경 변수를 등록하고 저장했다고 해서 즉시 공개 웹사이트에 적용되는 것은 아닙니다.

이 부분에서 초보자들이 자주 실수합니다.

Vercel에 환경 변수를 새로 등록했다면 다시 배포해야 합니다.

이 과정을 Redeploy라고 합니다.

Redeploy 실행 순서

1. 환경 변수 두 개가 정상적으로 저장되었는지 확인합니다.
2. 환경 변수 저장 후 나타나는 Redeploy 안내를 확인합니다.
3. Redeploy 버튼을 클릭합니다.
4. 확인 창이 나타나면 다시 Redeploy를 선택합니다.
5. Deployments 메뉴에서 배포 상태를 확인합니다.

저장 안내를 놓쳤다면 Deployments 메뉴에서 해당 배포의 오른쪽에 있는 점 세 개 메뉴를 눌러 Redeploy를 선택할 수도 있습니다.

반드시 기억하세요!

환경 변수 등록 → Save → Redeploy → Ready

이 과정을 완료해야 새 환경 변수가 공개 웹사이트에 반영됩니다.

12. 공개 웹사이트에서 이메일 보내기

이제 마지막 테스트입니다.

Vercel의 Deployments 메뉴에서 가장 최근 배포 상태를 확인합니다.

초록색 Ready가 표시되어야 합니다.

그다음 공개된 .vercel.app 주소로 접속합니다.

1. 웹사이트를 새로 고침합니다.
2. 연락하기 영역으로 이동합니다.
3. 이름과 문의 내용을 입력합니다.
4. 보내기 버튼을 누릅니다.
5. 보냈어요! 메시지가 나타나는지 확인합니다.
6. Resend의 Emails 메뉴에서 발송 결과를 확인합니다.
7. 내 이메일 받은편지함을 확인합니다.

이메일이 정상적으로 도착했다면 모든 과정이 완료된 것입니다.

최종 성공 확인

① 내 컴퓨터에서 이메일 전송 성공

② GitHub에 코드 업로드 완료

③ Vercel 환경 변수 등록 완료

④ Redeploy 후 Ready 확인

⑤ 공개 주소에서 보낸 이메일이 실제 메일함에 도착

13. 자주 발생하는 오류와 해결 방법

① RESEND_API_KEY 또는 CONTACT_EMAIL이 없다는 오류

원인

Vercel에 환경 변수가 등록되지 않았거나 Redeploy를 진행하지 않은 경우입니다.

해결 방법

1. Vercel Environment Variables를 확인합니다.
2. RESEND_API_KEY가 있는지 확인합니다.
3. CONTACT_EMAIL이 있는지 확인합니다.
4. Redeploy를 실행합니다.
5. Ready 상태가 된 후 다시 테스트합니다.

② 403 오류가 발생하는 경우

다음과 같은 메시지가 표시될 수 있습니다.

You can only send testing emails to your own email address

원인

Resend의 테스트 발신 주소를 사용하는 상태에서 가입한 이메일이 아닌 다른 주소로 보내려고 했기 때문입니다.

해결 방법

CONTACT_EMAIL을 Resend 가입에 사용한 이메일 주소와 일치시키세요.

다른 사람에게 보내려면 발신 도메인 인증이 필요합니다.

③ 401 API key is invalid

원인

• API 키를 잘못 입력함
• API 키 앞뒤에 공백이 있음
• API 키가 잘려서 저장됨
• 기존 API 키가 폐기됨

해결 방법

Resend에서 새 API 키를 발급받고 .env와 Vercel에 다시 등록합니다.

그다음 Redeploy를 실행합니다.

④ 보냈어요!가 나타나지만 이메일이 오지 않는 경우

원인

발송 요청은 성공했지만 이메일이 스팸함으로 이동했거나 실제 전달에 실패했을 수 있습니다.

해결 방법

1. Gmail 업데이트 탭을 확인합니다.
2. 스팸함을 확인합니다.
3. Resend의 Emails 메뉴를 엽니다.
4. 발송 상태가 Delivered인지 확인합니다.

Queued 상태라면 잠시 기다린 후 다시 확인합니다.

⑤ .env 파일이 GitHub에 올라간 경우

원인

.gitignore 설정이 잘못되었거나 이미 Git에서 추적하고 있던 파일일 수 있습니다.

해결 방법

먼저 노출된 API 키를 Resend에서 폐기합니다.

새 키를 발급받아 .env와 Vercel에 등록합니다.

그다음 Git 기록에서 비밀 정보를 제거하고 다시는 올라가지 않도록 설정합니다.

이미 공개된 키는 GitHub에서 파일을 삭제하는 것만으로 안전해지지 않습니다.

14. API 키를 안전하게 관리하는 방법

이번 실습에서 가장 중요한 부분은 API 키를 보호하는 것입니다.

API 키는 웹사이트의 기능을 실행하는 인증 정보입니다.

다음 원칙을 지키는 것이 좋습니다.

API 키를 보관해도 되는 곳

• 내 컴퓨터의 .env 파일
• Vercel Environment Variables
• API 키를 발급한 서비스의 보안 관리 화면

API 키를 공개하면 안 되는 곳

• GitHub 공개 저장소
• HTML과 JavaScript 공개 코드
• 안티그래비티 채팅창
• 카카오톡 및 이메일
• 화면 캡처와 녹화 영상

특히 브라우저에서 실행되는 코드에 API 키를 넣으면 방문자가 개발자 도구를 통해 확인할 수 있습니다.

따라서 API 키를 사용하는 작업은 서버에서 처리해야 합니다.

마무리: 이제 웹사이트에서 직접 이메일을 받을 수 있다

이번 실습에서는 단순히 웹사이트를 보여주는 수준에서 벗어나 방문자가 직접 문의할 수 있는 기능을 만들었습니다.

Resend API를 이용하면 별도의 메일 서버를 직접 구축하지 않고도 이메일 발송 기능을 추가할 수 있습니다.

또한 .env와 Vercel 환경 변수를 이용하면 API 키를 공개하지 않고 안전하게 관리할 수 있습니다.

오늘 꼭 기억할 핵심 내용

① Resend에서 API 키를 발급받습니다.

② .gitignore를 먼저 설정합니다.

③ .env에 API 키와 이메일 주소를 저장합니다.

④ GitHub에 .env를 올리지 않습니다.

⑤ Vercel에 환경 변수를 등록합니다.

⑥ Redeploy 후 공개 주소에서 이메일을 테스트합니다.

이제 여러분이 만든 웹사이트는 단순한 소개 페이지가 아닙니다.

방문자의 문의를 직접 받을 수 있는 웹사이트로 발전한 것입니다.

다음 단계에서는 개인 도메인을 연결하고 Resend에 도메인을 인증하여 다른 사람에게도 이메일을 보낼 수 있도록 확장해 볼 수 있습니다.

참고 자료: 스마택트 바이브코딩 6차시 - API와 비밀의 방
원본 학습 자료 보기

Vercel 사용법: GitHub 프로젝트를 인터넷에 무료로 배포하는 방법

Vercel 사용법: GitHub 프로젝트를 인터넷에 무료로 배포하는 방법

안티그래비티와 같은 AI 코딩 도구로 웹사이트를 만들었다면 이제 다른 사람들도 접속할 수 있도록 인터넷에 공개해야 합니다.

내 컴퓨터에서는 잘 실행되는데 다른 사람의 컴퓨터나 스마트폰에서는 접속할 수 없다면 아직 웹사이트 배포가 완료되지 않은 것입니다.

이때 사용할 수 있는 서비스가 바로 Vercel(버셀)입니다.

Vercel은 GitHub에 저장된 프로젝트를 불러와 인터넷에 공개해 주는 웹 배포 플랫폼입니다.

복잡한 서버 설정 없이 몇 가지 단계만 거치면 나만의 웹사이트 주소를 만들 수 있습니다.

이번 글에서 배울 내용

• Vercel이 무엇인지 이해하기
• Vercel 회원가입하기
• GitHub 계정 연결하기
• 프로젝트 Import 및 Deploy
• 나만의 웹사이트 주소 확인하기
• 코드 수정 후 자동 배포하기
• 배포 오류 해결하기

1. Vercel이란 무엇일까?

Vercel은 웹사이트와 웹 애플리케이션을 인터넷에 배포할 수 있도록 도와주는 서비스입니다.

쉽게 설명하면 내가 만든 웹사이트를 인터넷에 올려주는 자동 배포 시스템입니다.

예를 들어 안티그래비티로 웹사이트를 만들었다고 가정해 보겠습니다.

내 컴퓨터에서는 다음 주소로 접속할 수 있습니다.

http://localhost:3000

하지만 이 주소는 내 컴퓨터에서만 사용할 수 있습니다.

다른 사람에게 이 주소를 알려줘도 접속할 수 없습니다.

Vercel을 이용하면 다음과 같은 인터넷 주소를 만들 수 있습니다.

https://my-first-site.vercel.app

이제 다른 사람들도 인터넷을 통해 내 웹사이트에 접속할 수 있습니다.

Vercel은 어떻게 작동할까?

안티그래비티

웹사이트 제작 및 수정

↓

GitHub

프로젝트 코드 저장

↓

Vercel

프로젝트 자동 배포

↓

인터넷 웹사이트

누구나 접속 가능한 주소 생성

한 번 GitHub와 Vercel을 연결하면 이후에는 GitHub에 새로운 코드가 올라갈 때마다 Vercel이 자동으로 배포를 진행합니다.

매번 Vercel에 들어가서 Deploy 버튼을 누를 필요가 없습니다.

2. Vercel 무료로 사용할 수 있을까?

Vercel에는 Hobby, Pro, Enterprise 요금제가 있습니다.

처음 웹사이트를 만들어 보는 개인 사용자라면 Hobby 요금제를 살펴볼 수 있습니다.

Hobby 요금제

$0 / 월

• 개인 프로젝트용 무료 플랜
• GitHub 저장소 연결
• 자동 배포 기능
• HTTPS 지원
• vercel.app 주소 제공

다만 중요한 조건이 있습니다.

Hobby 요금제는 개인적이고 비상업적인 용도로 제한됩니다.

회사 업무나 영리 목적의 서비스라면 Pro 등 적합한 요금제를 확인해야 합니다.

또한 무료 요금제에도 사용량과 기능 제한이 있습니다.

따라서 실제 운영에 사용할 때는 최신 요금제와 사용 조건을 확인해야 합니다.

Vercel 공식 요금제 확인하기

3. Vercel 회원가입하기

먼저 Vercel 공식 홈페이지에 접속합니다.

Vercel 공식 홈페이지 바로가기

① Sign Up 클릭하기

홈페이지 오른쪽 위에 있는 Sign Up을 누릅니다.

회원가입 화면이 나타나면 사용할 계정을 선택합니다.

② Google 또는 GitHub 계정으로 가입하기

다음과 같은 로그인 방법을 선택할 수 있습니다.

• Continue with Google
• Continue with GitHub

이미 GitHub를 사용하고 있다면 GitHub 계정으로 연결하는 것도 편리합니다.

Google 계정으로 가입해도 나중에 GitHub 저장소를 연결할 수 있습니다.

③ Hobby 요금제 선택하기

사용 목적을 묻는 화면이 나오면 개인 프로젝트에 해당하는 Hobby를 선택합니다.

Team Name을 입력하는 화면에서는 개인 프로젝트라면 안내에 따라 기본 설정을 진행하면 됩니다.

가입이 완료되면 Vercel 대시보드로 이동합니다.

4. GitHub와 Vercel 연결하기

이제 가장 중요한 과정입니다.

GitHub에 저장된 프로젝트를 Vercel로 가져와야 합니다.

먼저 GitHub에 프로젝트가 올라가 있어야 합니다.

아직 GitHub에 프로젝트를 올리지 않았다면 이전 글의 Git과 GitHub 사용법을 먼저 확인하세요.

① Create New → Project 선택

Vercel 대시보드에 접속합니다.

오른쪽 위의 Create New 버튼을 누릅니다.

메뉴에서 Project를 선택합니다.

화면에 따라 Import Project라는 버튼으로 표시될 수도 있습니다.

② GitHub 선택하기

Import Git Repository 화면에서 GitHub를 선택합니다.

처음 연결하는 경우 GitHub 권한 승인 화면이 나타납니다.

Authorize Vercel을 눌러 연결을 승인합니다.

③ GitHub 저장소 접근 권한 설정

Vercel이 GitHub 저장소에 접근할 수 있도록 허용해야 합니다.

Install 화면에서 저장소 접근 범위를 선택합니다.

• All repositories: 모든 저장소 접근 허용
• Only select repositories: 선택한 저장소만 허용

처음 사용하는 경우에는 모든 저장소를 허용하거나 배포할 저장소만 선택하면 됩니다.

선택한 후 Install을 눌러 진행합니다.

저장소가 보이지 않는다면?

GitHub 권한 설정에서 해당 저장소가 선택되어 있는지 확인하세요. 다른 사람 소유의 저장소라면 필요한 소유자 또는 조직 권한이 있는지도 확인해야 합니다.

5. GitHub 프로젝트 Import 하기

GitHub 연결이 완료되면 내 저장소 목록이 표시됩니다.

예를 들어 GitHub에 my-first-site라는 저장소가 있다면 목록에서 해당 프로젝트를 찾습니다.

저장소 이름 옆에 있는 Import 버튼을 누릅니다.

저장소가 많다면 검색창에 프로젝트 이름을 입력하면 쉽게 찾을 수 있습니다.

프로젝트 설정 확인하기

Import를 누르면 New Project 설정 화면이 나타납니다.

Vercel은 프로젝트의 구조를 분석해 적절한 프레임워크를 자동으로 인식합니다.

예를 들어 Next.js 프로젝트라면 Application Preset에 Next.js가 표시될 수 있습니다.

처음 배포하는 단순한 프로젝트라면 자동으로 인식된 설정을 확인하고 진행하면 됩니다.

다만 프로젝트 구조가 특수하거나 하위 폴더에 실제 앱이 있다면 Root Directory를 확인해야 합니다.

또한 환경변수를 사용하는 프로젝트라면 Environment Variables에 필요한 값을 등록해야 합니다.

6. Deploy 버튼으로 웹사이트 공개하기

설정 확인이 끝났다면 Deploy 버튼을 누릅니다.

이제 Vercel이 프로젝트를 분석하고 웹사이트를 만드는 작업을 시작합니다.

이 과정을 배포(Deploy)라고 합니다.

배포 진행 과정

1. GitHub에서 프로젝트 코드 가져오기
2. 프로젝트 구조와 프레임워크 분석
3. 필요한 패키지 설치
4. 프로젝트 빌드
5. 인터넷에 공개

배포가 진행되는 동안 Build Logs에 작업 내용이 표시됩니다.

처음에는 시간이 조금 걸릴 수 있습니다.

작업이 완료될 때까지 화면을 닫지 말고 기다립니다.

정상적으로 완료되면 Congratulations 화면이 나타납니다.

배포 성공!

Congratulations 화면이 나타났다면 첫 번째 웹사이트 배포가 완료된 것입니다. 이제 Continue to Dashboard를 눌러 프로젝트 관리 화면으로 이동합니다.

7. 나만의 Vercel 웹사이트 주소 확인하기

배포가 끝나면 인터넷에서 접속할 수 있는 주소가 만들어집니다.

Vercel 프로젝트 화면에서 Domains 항목을 확인합니다.

다음과 비슷한 주소가 표시됩니다.

https://my-first-site.vercel.app

이 주소가 바로 내 웹사이트의 인터넷 주소입니다.

주소를 클릭하면 새 브라우저 탭에서 웹사이트가 열립니다.

주소 뒤에 다른 단어가 붙는 이유

내가 원하는 프로젝트 이름이 이미 사용되고 있다면 Vercel이 구분을 위해 추가 문자를 붙일 수 있습니다.

예를 들어 다음과 같은 주소가 만들어질 수 있습니다.

my-first-site-demo-gules.vercel.app

이것은 오류가 아닙니다.

정확한 주소는 프로젝트 화면의 Domains 항목에서 확인하면 됩니다.

스마트폰에서도 확인하기

PC에서 만든 웹사이트를 스마트폰으로 열어 봅니다.

1. Vercel에서 공개 주소를 복사합니다.
2. 카카오톡 나와의 채팅에 주소를 보냅니다.
3. 스마트폰에서 해당 주소를 누릅니다.
4. 웹사이트가 정상적으로 열리는지 확인합니다.

이제 다른 사람에게도 웹사이트 주소를 공유할 수 있습니다.

개인정보 공개 주의

공개된 웹사이트는 누구나 접속할 수 있습니다. 전화번호, 집 주소, 주민등록번호, 개인 비밀번호, API 키 등을 웹페이지나 공개 저장소에 올리지 않도록 주의하세요.

8. GitHub 수정 사항은 자동으로 배포된다

Vercel의 가장 편리한 기능 중 하나가 자동 배포입니다.

처음 한 번 GitHub와 Vercel을 연결해 놓으면 이후에는 GitHub에 새로운 작업 기록을 올릴 때마다 자동으로 배포가 시작됩니다.

매번 Vercel에 로그인해서 Deploy를 누를 필요가 없습니다.

자동 배포 실습하기

이번에는 안티그래비티에서 웹사이트에 문장 하나를 추가해 보겠습니다.

안티그래비티 채팅창에 다음 프롬프트를 입력합니다.

📋 복사용 프롬프트

메인 페이지 맨 아래에 "오늘 처음으로 인터넷에 웹사이트를 공개했습니다!"라는 문장을 추가해줘. 글자색은 빨간색으로 해줘. 다른 부분은 건드리지 마. 수정이 끝나면 변경 내용을 커밋하고 GitHub로 push해줘. 커밋 메시지는 "첫 공개 기념 문장 추가"로 해줘.

AI가 작업을 완료하면 다음 세 가지가 순서대로 진행됩니다.

1. 웹사이트 코드 수정
2. Git 커밋 및 GitHub Push
3. Vercel 자동 배포

여기서 중요한 점은 세 번째 단계입니다.

GitHub에 Push가 완료되면 Vercel이 변경 사항을 감지해 자동으로 새로운 배포를 시작합니다.

따라서 Vercel 화면에서 Deploy 버튼을 다시 누를 필요가 없습니다.

자동 배포가 시작되었는지 확인하기

Vercel 대시보드에서 내 프로젝트를 선택합니다.

왼쪽 메뉴의 Deployments를 클릭합니다.

가장 위에 새로운 배포 기록이 나타나는지 확인합니다.

배포가 진행되는 동안 Building 등의 상태가 표시될 수 있습니다.

잠시 기다리면 Ready로 변경됩니다.

이후 공개 주소를 새로 고침하면 방금 추가한 문장이 나타납니다.

자동 배포의 핵심

코드 수정 → 커밋 → GitHub Push → Vercel 자동 배포

이 과정을 반복하면 웹사이트를 계속 업데이트할 수 있습니다.

9. Vercel Ready와 Error 상태 확인하기

GitHub에 코드를 올렸다고 해서 무조건 웹사이트 공개까지 완료된 것은 아닙니다.

Vercel에서 실제 배포가 성공했는지 확인해야 합니다.

Ready는 배포 성공

Deployments 화면에서 초록색 표시와 함께 Ready가 나타나면 해당 배포가 성공한 것입니다.

이제 공개 주소를 새로 고침하여 변경 사항을 확인하면 됩니다.

Error는 배포 실패

빨간색 Error가 나타나면 배포 과정에서 문제가 발생한 것입니다.

이때 이전에 성공한 버전이 계속 공개 주소에 표시될 수 있습니다.

따라서 GitHub에 Push한 것만 확인하지 말고 Ready까지 확인하는 습관이 중요합니다.

배포 오류 해결하기

먼저 Vercel Deployments에서 실패한 배포 항목을 클릭합니다.

Build Logs를 열어 빨간색 오류 메시지를 찾습니다.

오류 내용을 복사한 다음 안티그래비티 채팅창에 붙여 넣습니다.

📋 복사용 오류 해결 프롬프트

Vercel 웹사이트 배포가 실패했어.

아래 오류 내용을 분석해줘.

[여기에 Build Logs 오류 내용 붙여 넣기]

초보자도 이해할 수 있도록 원인을 설명하고, 기존 기능을 삭제하지 않는 방법으로 수정해줘. 수정 후 로컬에서 빌드가 정상적으로 되는지 확인하고, 커밋과 GitHub Push까지 진행해줘.

AI가 문제를 수정하고 GitHub에 다시 Push하면 Vercel에서 새로운 배포가 시작됩니다.

이번에도 Ready가 표시되는지 확인해야 합니다.

10. Vercel에서 자주 발생하는 문제와 해결 방법

① GitHub 저장소가 목록에 보이지 않는다

원인

• GitHub 저장소 접근 권한이 없음
• Vercel GitHub 앱에 해당 저장소가 선택되지 않음
• 다른 GitHub 계정으로 로그인함

해결 방법

GitHub 연결 설정에서 Vercel 앱이 해당 저장소에 접근할 수 있는지 확인합니다.

② 웹사이트 주소를 열었는데 예전 화면이 보인다

원인

새로운 배포가 아직 완료되지 않았거나 브라우저에 이전 화면이 캐시되어 있을 수 있습니다.

해결 방법

1. Vercel Deployments에서 Ready 확인
2. 브라우저에서 Ctrl + F5 누르기
3. 그래도 바뀌지 않으면 시크릿 창에서 열기

③ Deployments에 Error가 나타난다

원인

• 프로그램 코드 오류
• 필요한 패키지가 설치되지 않음
• 빌드 명령어 설정 오류
• 환경변수 누락

해결 방법

Build Logs를 확인하고 오류 메시지를 안티그래비티에 전달합니다.

④ 프로젝트는 배포되었는데 일부 기능이 작동하지 않는다

원인

로컬 환경에만 설정된 환경변수나 외부 서비스 인증 정보가 배포 환경에 등록되지 않았을 수 있습니다.

해결 방법

Vercel 프로젝트의 Settings → Environment Variables에서 필요한 환경변수를 등록합니다.

값을 등록한 뒤에는 새 배포가 필요할 수 있습니다.

⑤ 웹사이트 접속 시 404 오류가 나타난다

원인

잘못된 경로로 접속했거나 프로젝트의 페이지 경로 및 빌드 설정에 문제가 있을 수 있습니다.

해결 방법

먼저 Domains에 표시된 정확한 주소를 사용하고, 접속한 경로와 프로젝트의 페이지 구성을 확인합니다.

11. Vercel 사용 시 꼭 기억해야 할 사항

처음 웹사이트를 배포할 때는 다음 내용을 기억하면 좋습니다.

• GitHub에 프로젝트가 먼저 올라가 있어야 합니다.
• Vercel과 GitHub를 한 번 연결하면 자동 배포를 사용할 수 있습니다.
• 코드 수정 후 커밋과 Push를 진행해야 합니다.
• Deployments에서 Ready 상태를 확인해야 합니다.
• 공개 웹사이트에 개인정보를 올리지 않아야 합니다.
• API 키와 비밀번호는 환경변수로 안전하게 관리해야 합니다.
• 무료 Hobby 요금제는 개인적이고 비상업적인 용도에 한정됩니다.

마무리: 이제 내가 만든 웹사이트를 인터넷에 공개해 보자

Vercel을 사용하면 복잡한 서버를 직접 구축하지 않아도 웹사이트를 인터넷에 공개할 수 있습니다.

처음에는 회원가입과 GitHub 연결 과정이 조금 낯설 수 있습니다.

하지만 한 번 연결해 놓으면 이후에는 훨씬 편리합니다.

안티그래비티에서 코드를 수정하고 GitHub에 Push하면 Vercel이 자동으로 새로운 버전을 배포하기 때문입니다.

오늘의 핵심 정리

① Vercel 회원가입

② GitHub 계정 연결

③ 프로젝트 Import

④ Deploy 버튼 클릭

⑤ vercel.app 주소 확인

⑥ GitHub Push 후 Ready 상태 확인

이제 여러분이 만든 웹사이트는 내 컴퓨터 안에만 있는 프로그램이 아닙니다.

인터넷 주소를 통해 다른 사람들과 공유할 수 있는 실제 웹사이트가 된 것입니다.

다음 단계에서는 Vercel에 배포한 웹사이트에 사용자 입력 기능이나 문의하기 기능을 추가해 보세요.

참고 자료: 스마택트 바이브코딩 5차시 - 한 사이클 천천히
원본 학습 자료 보기

Git과 GitHub 사용법 총정리: 초보자를 위한 커밋과 푸시 따라 하기

Git과 GitHub 사용법 총정리: 

초보자를 위한 커밋과 푸시 따라 하기

바이브코딩으로 웹사이트나 프로그램을 만들다 보면 한 가지 걱정이 생깁니다. 열심히 만든 프로젝트가 컴퓨터 고장이나 실수로 사라지면 어떻게 해야 할까요?

Git과 GitHub 사용법을 알아두면 이런 걱정을 크게 줄일 수 있습니다. 작업한 내용을 단계별로 저장하고, 인터넷에 백업할 수 있기 때문입니다.

특히 안티그래비티(Antigravity)와 같은 AI 코딩 도구를 사용한다면 Git과 GitHub는 꼭 알아두면 좋은 기본 도구입니다.

이번 글에서는 개발 경험이 없는 초보자도 따라 할 수 있도록 Git 설치부터 GitHub 업로드까지 설명하겠습니다.

이 글에서 배울 내용

• Git과 GitHub의 차이
• Git 설치 및 초기 설정
• 프로젝트 폴더를 Git 저장소로 만들기
• 커밋으로 작업 기록 저장하기
• GitHub에 프로젝트 백업하기
• 자주 발생하는 오류 해결 방법

1. Git과 GitHub는 무엇일까?

Git과 GitHub는 이름이 비슷하지만 역할은 서로 다릅니다.

쉽게 이해하려면 컴퓨터 게임의 세이브 기능을 생각하면 됩니다.

Git은 게임의 세이브 포인트

게임을 하다가 중요한 지점에서 저장해 두면 나중에 문제가 생겨도 저장한 시점부터 다시 시작할 수 있습니다.

Git도 비슷합니다.

프로그램을 만들면서 중요한 변경 사항이 있을 때마다 기록을 남깁니다. 나중에 문제가 생기면 이전 작업 기록을 확인하거나 복구할 수 있습니다.

GitHub는 인터넷에 있는 보관 금고

Git으로 저장한 기록이 내 컴퓨터에만 있다면 컴퓨터가 고장 났을 때 문제가 생길 수 있습니다.

이때 GitHub를 사용합니다.

GitHub는 Git 저장소를 인터넷에 보관하고 관리할 수 있는 서비스입니다.

핵심 개념 정리

🔹 Git : 프로젝트 변경 기록을 관리하는 도구

🔹 Commit : 현재 작업 상태를 저장하는 것

🔹 Repository : 프로젝트 기록을 관리하는 저장소

🔹 GitHub : 인터넷에서 저장소를 보관하는 서비스

🔹 Push : 내 컴퓨터의 저장 기록을 GitHub로 올리는 것

2. Git 설치 여부 확인하기

먼저 내 컴퓨터에 Git이 설치되어 있는지 확인해야 합니다.

안티그래비티를 실행하고 작업할 프로젝트 폴더를 엽니다.

그다음 AI 채팅창에 다음 프롬프트를 입력합니다.

📋 복사용 프롬프트

내 컴퓨터에 git이 설치되어 있는지 확인해줘. git --version 명령어를 실행하고 결과를 한국어로 설명해줘.

정상적으로 설치되어 있다면 다음과 비슷한 결과가 나옵니다.

git version 2.54.0.windows.1

버전 숫자가 표시되면 설치가 완료된 것입니다.

버전이 표시되지 않는다면 Git을 설치해야 합니다.

공식 홈페이지에 접속하여 Windows용 설치 파일을 다운로드합니다.

Git 공식 다운로드 바로가기

설치 과정에서는 특별한 설정이 필요하지 않다면 기본값을 유지하고 Next를 선택하면 됩니다.

설치가 끝나면 안티그래비티를 완전히 종료한 후 다시 실행합니다.

3. Git에 사용자 이름과 이메일 등록하기

Git은 누가 작업 내용을 저장했는지 기록합니다.

따라서 처음 사용할 때 이름과 이메일을 등록해야 합니다.

안티그래비티 채팅창에 다음과 같이 입력합니다.

📋 복사용 프롬프트

내 컴퓨터에서 Git을 처음 사용하는 거야. 사용자 이름은 "myname", 이메일은 "가입한 이메일 주소"로 등록해줘. 설정이 정상적으로 완료되었는지도 확인해줘.

여기서 myname은 본인이 원하는 영문 이름이나 닉네임으로 변경하면 됩니다.

이메일은 GitHub 계정에 연결한 이메일을 사용하는 것이 좋습니다.

정상적으로 등록되면 다음 두 가지 설정이 확인됩니다.

user.name
user.email

이미 설정되어 있다는 메시지가 나오면 현재 등록된 정보를 확인하고 그대로 사용해도 됩니다.

4. 프로젝트 폴더를 Git 저장소로 만들기

이제 실제 작업 폴더를 Git이 관리하도록 설정하겠습니다.

예를 들어 웹사이트 프로젝트 폴더 이름이 my-first-site라고 가정하겠습니다.

프로젝트 폴더를 안티그래비티에서 연 상태로 다음 프롬프트를 입력합니다.

📋 복사용 프롬프트

현재 열려 있는 프로젝트 폴더를 Git 저장소로 초기화해줘. 기본 브랜치 이름은 main으로 설정해줘. git init -b main 명령어를 사용하고, 완료 후 git status로 현재 상태를 보여줘.

Git은 프로젝트 폴더에 .git이라는 관리 정보를 만들어 기록을 관리합니다.

작업대에 다음과 비슷한 문구가 나타나면 정상적으로 초기화된 것입니다.

Initialized empty Git repository
On branch main

빨간색 파일이 표시되면 오류일까?

초보자가 가장 많이 당황하는 부분입니다.

git status를 실행했을 때 빨간색 파일 이름이 여러 개 나타날 수 있습니다.

하지만 이것은 오류가 아닙니다.

아직 Git에 저장 기록을 남기지 않은 파일이라는 뜻입니다.

참고로 이미 Git 저장소로 초기화된 폴더라면 Reinitialized existing Git repository라는 문구가 나올 수도 있습니다. 이 경우에도 반드시 오류인 것은 아닙니다.

5. 커밋(Commit)으로 작업 저장하기

이제 가장 중요한 과정입니다.

Git에서 작업 내용을 저장하는 것을 커밋(Commit)이라고 합니다.

커밋은 단순히 파일을 저장하는 것과 다릅니다.

현재 프로젝트의 상태를 기록하고, 나중에 어떤 작업을 했는지 확인할 수 있도록 메시지를 남기는 과정입니다.

첫 번째 커밋 만들기

안티그래비티에 다음과 같이 요청합니다.

📋 복사용 프롬프트

현재 프로젝트 폴더의 파일 전체를 첫 번째 커밋으로 저장해줘. 변경 파일을 git add로 추가하고, 커밋 메시지는 "처음 시작 - 프로젝트 생성"으로 해줘. 완료 후 git log로 저장 기록을 보여줘.

정상적으로 완료되면 첫 번째 작업 기록이 만들어집니다.

커밋 메시지는 왜 중요할까?

커밋을 할 때는 무엇을 변경했는지 알 수 있도록 메시지를 작성하는 것이 좋습니다.

좋지 않은 메시지	좋은 메시지
수정	소개 문장 추가
변경	배경색 변경
완료	로그인 기능 추가

나중에 작업 기록을 살펴볼 때 메시지만 보고도 무엇을 했는지 알 수 있어야 합니다.

두 번째 커밋 만들기

이번에는 프로젝트의 일부를 수정한 후 다시 저장해 보겠습니다.

예를 들어 웹사이트 이름의 글자색을 변경했다고 가정하겠습니다.

📋 복사용 프롬프트

프로젝트의 이름 글자색을 청록색으로 변경해줘. 변경이 정상적으로 적용되었는지 확인하고, 두 번째 커밋을 만들어줘. 커밋 메시지는 "이름 글자색 청록으로 변경"으로 해줘. 마지막에 git log로 전체 기록을 보여줘.

이제 커밋 기록이 두 개가 됩니다.

이것이 Git을 사용하는 기본적인 방식입니다.

수정 → 확인 → 커밋

작업이 완료될 때마다 이 과정을 반복하면 됩니다.

6. GitHub에 저장소 만들기

지금까지 저장한 커밋은 내 컴퓨터에만 있습니다.

이제 GitHub에 프로젝트를 보관할 공간을 만들어 보겠습니다.

① GitHub 회원가입 및 로그인

먼저 GitHub 홈페이지에 접속합니다.

GitHub 공식 홈페이지 바로가기

계정이 없다면 회원가입을 진행하고 로그인합니다.

② New repository 선택

로그인한 후 오른쪽 위의 + 버튼을 누릅니다.

메뉴에서 New repository를 선택합니다.

③ 저장소 이름 입력

Repository name에 프로젝트 이름을 입력합니다.

예를 들어 다음과 같이 입력할 수 있습니다.

my-first-site

저장소 이름은 영문과 숫자를 사용하는 것이 편리합니다.

④ 공개 여부 선택하기

GitHub에서는 저장소를 두 가지 방식으로 만들 수 있습니다.

• Public : 다른 사람도 저장소의 내용을 볼 수 있습니다.
• Private : 허용된 사용자만 저장소에 접근할 수 있습니다.

학습용 예제나 공개해도 되는 프로젝트라면 Public을 선택할 수 있습니다.

개인 프로젝트나 공개하고 싶지 않은 소스코드는 Private를 선택하는 것이 좋습니다.

주의할 점

Public 저장소는 소스코드가 공개됩니다. API 키, 비밀번호, 개인정보, .env 파일 등의 비밀 정보가 포함되지 않았는지 반드시 확인하세요.

⑤ 추가 옵션은 비워 두기

이번 실습은 내 컴퓨터에 이미 프로젝트와 커밋 기록이 있는 상태입니다.

따라서 처음 연결할 때는 다음 옵션을 추가하지 않는 방식으로 진행합니다.

• Add README : Off
• Add .gitignore : No .gitignore
• Add license : No license

이렇게 빈 저장소를 만들면 기존 로컬 저장소와 연결하는 과정을 단순하게 진행할 수 있습니다.

마지막으로 Create repository 버튼을 누릅니다.

⑥ HTTPS 주소 복사하기

저장소가 만들어지면 HTTPS 주소가 표시됩니다.

주소는 다음과 비슷한 형태입니다.

https://github.com/아이디/my-first-site.git

오른쪽의 복사 아이콘을 눌러 주소를 복사합니다.

이 주소는 다음 단계에서 사용합니다.

7. GitHub로 프로젝트 업로드하기 (Push)

이제 마지막 단계입니다.

내 컴퓨터의 Git 저장소와 GitHub의 저장소를 연결하고 작업 기록을 업로드하겠습니다.

안티그래비티 채팅창에 다음 프롬프트를 입력합니다.

📋 복사용 프롬프트

방금 GitHub에 빈 저장소를 만들었어.

저장소 주소는 다음과 같아.

[여기에 복사한 HTTPS 주소 입력]

이 주소를 원격 저장소(origin)로 등록하고, 현재까지의 커밋 기록을 main 브랜치로 push해줘. 실행 결과를 확인하고 한국어로 설명해줘.

AI가 명령어 실행을 요청하면 실행 내용을 확인한 후 허용합니다.

이때 GitHub 로그인이 필요할 수 있습니다.

GitHub 로그인 인증하기

Windows에서 처음 업로드할 때 로그인 인증을 요청할 수 있습니다.

로그인 창이 나타나지 않는다면 AI에게 다음과 같이 요청합니다.

📋 복사용 프롬프트

브라우저 인증코드 방식으로 GitHub에 로그인하고 싶어. 인증코드를 받는 방법을 안내해줘.

인증코드를 받았다면 다음 순서로 진행합니다.

1. 브라우저에서 GitHub Device Activation 페이지를 엽니다.
2. 화면에 표시된 계정이 내 계정인지 확인합니다.
3. AI가 알려준 8자리 인증코드를 입력합니다.
4. Continue를 누릅니다.
5. Authorize GitHub CLI를 선택합니다.
6. 승인이 완료되면 안티그래비티로 돌아갑니다.

인증코드 보안 주의

인증코드는 본인 확인을 위한 일회성 코드입니다. 다른 사람에게 전달하거나 공개하지 마세요.

Push 성공 여부 확인하기

업로드가 완료되면 다음과 비슷한 결과를 확인할 수 있습니다.

Your branch is up to date with 'origin/main'

이 메시지가 나타나면 로컬 main 브랜치와 GitHub의 origin/main 브랜치가 최신 상태로 일치한다는 의미입니다.

8. GitHub에 파일이 제대로 올라갔는지 확인하기

AI가 성공했다고 알려주더라도 직접 확인하는 습관이 중요합니다.

다음 순서로 확인합니다.

1. GitHub에서 방금 만든 저장소 페이지를 엽니다.
2. 키보드의 F5를 눌러 새로 고침 합니다.
3. 프로젝트 파일과 폴더가 표시되는지 확인합니다.
4. 커밋 메시지가 보이는지 확인합니다.
5. Commits를 눌러 저장 기록을 확인합니다.

파일 목록과 두 개의 커밋 기록이 모두 보인다면 정상적으로 업로드된 것입니다.

최종 확인 체크리스트

• 프로젝트 파일이 보이는가?
• 폴더 구조가 정상적으로 올라갔는가?
• 첫 번째 커밋 메시지가 보이는가?
• 두 번째 커밋 메시지가 보이는가?

9. Git과 GitHub 사용 중 자주 발생하는 오류

처음 Git을 사용할 때는 영어 오류 메시지가 나타날 수 있습니다.

당황하지 말고 오류 내용을 확인하면 대부분 해결할 수 있습니다.

① src refspec main does not match any

원인: main이라는 브랜치가 없거나 아직 커밋이 만들어지지 않은 경우입니다.

해결 프롬프트

현재 브랜치와 커밋 기록을 확인해줘. main 브랜치가 없다면 main으로 변경하고, 커밋이 없다면 현재 파일을 확인한 후 첫 커밋을 만들어줘.

② rejected (fetch first)

원인: GitHub 저장소에 이미 파일이나 커밋이 존재하는 경우입니다.

로컬 저장소와 원격 저장소의 기록이 서로 달라서 업로드가 거부될 수 있습니다.

해결 방법

먼저 두 저장소의 상태를 비교하도록 요청합니다.

로컬 저장소와 GitHub 원격 저장소의 커밋 기록을 비교해줘. 기존 작업을 삭제하지 말고 안전하게 통합할 방법을 제시해줘.

무조건 저장소를 삭제하거나 강제 푸시하지 마세요. 기존 작업이 사라질 수 있습니다.

③ remote origin already exists

원인: 이미 origin이라는 원격 저장소가 등록되어 있는 상태입니다.

해결 프롬프트

현재 등록된 원격 저장소 주소를 확인해줘. 기존 주소와 새 GitHub 주소를 비교하고, 필요한 경우 안전하게 변경해줘.

④ GitHub 업로드가 로그인에서 멈춘 경우

원인: GitHub 인증이 완료되지 않은 상태일 수 있습니다.

브라우저 인증코드 방식으로 로그인하고 승인을 완료했는지 확인합니다.

⑤ GitHub 페이지에 파일이 보이지 않는 경우

원인: Push가 완료되지 않았거나 다른 저장소에 연결되었을 수 있습니다.

해결 프롬프트

현재 Git 원격 저장소 주소와 브랜치 상태를 확인해줘. 마지막 커밋이 GitHub에 정상적으로 올라갔는지도 확인하고, 문제가 있다면 원인을 설명해줘.

10. 여러 사람이 사용하는 컴퓨터라면 로그아웃하기

교육장이나 공용 컴퓨터에서 GitHub에 로그인했다면 작업이 끝난 후 로그아웃해야 합니다.

로그인 정보가 컴퓨터에 남아 있으면 다음 사용자가 내 계정으로 작업할 위험이 있습니다.

다음 두 가지를 진행합니다.

① GitHub 웹사이트에서 로그아웃

1. GitHub 오른쪽 위 프로필 사진을 누릅니다.
2. Sign out을 선택합니다.
3. 로그아웃이 완료되었는지 확인합니다.

② 컴퓨터에 저장된 인증 정보 정리하기

안티그래비티에 다음과 같이 요청할 수 있습니다.

📋 복사용 프롬프트

이 컴퓨터에 저장된 GitHub CLI 로그인 정보와 Git Credential Manager의 GitHub 인증 정보를 확인하고 로그아웃해줘. Windows 자격 증명에 남아 있는 GitHub 관련 인증 정보도 확인해줘.

실행 전에 어떤 인증 정보가 삭제되는지 확인하고 허용해야 합니다.

개인 컴퓨터라면 매번 로그아웃할 필요는 없습니다.

11. 앞으로 Git을 사용하는 기본 습관

Git과 GitHub를 처음 설정하는 과정은 조금 복잡해 보일 수 있습니다.

하지만 한 번 설정해 놓으면 이후에는 훨씬 간단하게 사용할 수 있습니다.

프로젝트를 수정할 때마다 다음 과정을 반복하면 됩니다.

Git 기본 작업 순서

1단계. 프로젝트 수정

AI에게 필요한 기능이나 디자인 변경을 요청합니다.

2단계. 변경 사항 확인

웹사이트나 프로그램이 정상적으로 작동하는지 확인합니다.

3단계. 커밋 만들기

변경된 내용을 의미 있는 메시지와 함께 저장합니다.

4단계. GitHub에 푸시

저장한 작업 기록을 인터넷 저장소에 업로드합니다.

5단계. 업로드 확인

GitHub에서 파일과 커밋 기록을 확인합니다.

이 과정을 습관화하면 작업 중 문제가 발생해도 이전 기록을 확인할 수 있습니다.

12. Git과 GitHub 핵심 용어 정리

• Git: 파일의 변경 기록을 관리하는 도구
• GitHub: Git 저장소를 인터넷에서 관리하는 서비스
• Repository: 프로젝트의 파일과 기록을 관리하는 저장소
• Commit: 작업 상태를 기록하는 과정
• Push: 로컬 커밋을 원격 저장소에 업로드하는 과정
• Remote: 내 컴퓨터 외부에 있는 원격 저장소
• Branch: 독립적인 작업 흐름을 관리하는 가지
• main: 일반적으로 사용하는 기본 브랜치 이름
• git status: 현재 파일 변경 상태를 확인하는 명령어
• git log: 과거 커밋 기록을 확인하는 명령어

마무리: 바이브코딩을 한다면 Git은 필수 도구

AI 코딩 도구의 발전으로 프로그래밍을 잘 모르는 사람도 웹사이트와 프로그램을 만들 수 있는 시대가 되었습니다.

하지만 프로그램을 만드는 것만큼 중요한 것이 작업 결과를 안전하게 보관하는 것입니다.

Git은 작업 과정을 기록하고, GitHub는 그 기록을 인터넷에 보관하는 역할을 합니다.

처음에는 커밋과 푸시 같은 용어가 낯설 수 있습니다.

하지만 오늘 소개한 순서대로 한 번만 따라 해 보면 어렵지 않게 사용할 수 있습니다.

오늘 꼭 기억할 세 가지

① Git은 내 컴퓨터에서 작업 기록을 저장합니다.

② GitHub는 작업 기록을 인터넷에 보관합니다.

③ 중요한 작업을 마칠 때마다 커밋하고 푸시하는 습관을 들이세요.

다음 단계에서는 GitHub에 올린 프로젝트를 Vercel과 연결하여 실제 인터넷에서 누구나 접속할 수 있는 웹사이트로 배포하는 방법을 배워보면 좋습니다.

참고 자료: 스마택트 바이브코딩 4차시 - 세이브 포인트, 깃과 깃허브
원본 학습 자료 보기

안티그래비티 사용법 : AI로 웹페이지 꾸미기

안티그래비티 사용법 : AI로 웹페이지 꾸미기

지난 시간에는 안티그래비티(Antigravity)를 이용해 나만의 첫 웹사이트를 만드는 방법을 알아봤습니다.

하지만 웹사이트가 실행된다고 해서 모든 작업이 끝난 것은 아닙니다.

제목이 작거나 색상이 어울리지 않는다면 방문자는 페이지를 읽기 불편할 수 있습니다.

이번 글에서는 AI 코딩 도구인 안티그래비티를 활용해 웹페이지 디자인을 개선하는 방법을 알아보겠습니다.

이번 글에서 배울 내용

• 웹페이지 제목과 글꼴 크기 조정
• 배경색과 글자색 변경
• 사진을 웹페이지에 추가하기
• 여백을 조정해 깔끔하게 만들기
• 모바일 화면 확인하기

1. 웹페이지 꾸미기 전 준비하기

웹페이지를 수정하기 전에 현재 화면을 먼저 캡처해 두세요.

수정 전과 수정 후를 비교하면 디자인이 얼마나 달라졌는지 쉽게 확인할 수 있습니다.

윈도우 화면 캡처 방법

1. 크롬에서 내 웹페이지를 엽니다.
2. 윈도우 키와 Shift 키, S 키를 누릅니다.
3. 캡처할 영역을 마우스로 선택합니다.
4. 캡처 이미지를 저장합니다.

이제 디자인을 수정할 준비가 끝났습니다.

2. 웹페이지 제목 꾸미기

웹페이지에서 가장 먼저 눈에 들어오는 것은 바로 제목입니다.

제목이 본문과 비슷한 크기라면 방문자는 중요한 내용을 구분하기 어렵습니다.

제목은 크게, 본문은 읽기 편한 크기로 설정하는 것이 좋습니다.

AI에게 이렇게 요청하세요.

안티그래비티 입력 프롬프트

맨 위 제목을 더 크고 굵게 만들어줘. 제목과 소개 문장은 가운데 정렬해줘. 전체적으로 깔끔하고 보기 좋게 수정해줘.

프롬프트를 입력하면 안티그래비티가 관련 코드를 수정합니다.

수정 결과를 확인한 후 마음에 들면 Accept all을 눌러 적용하세요.

제목이 너무 크다면 다음과 같이 추가 요청하면 됩니다.

제목이 너무 커. 한 줄에 자연스럽게 들어가도록 글자 크기를 조금 줄여줘.

3. 웹페이지 색상 변경하기

웹페이지에 너무 많은 색상을 사용하면 화면이 복잡해 보일 수 있습니다.

초보자라면 세 가지 색상을 중심으로 디자인하는 것을 추천합니다.

① 배경색

페이지 전체에 적용하는 색상입니다. 연한 하늘색이나 회색처럼 눈에 부담이 적은 색상이 좋습니다.

② 글자색

본문을 읽기 쉽게 만드는 색상입니다. 짙은 회색이나 남색을 추천합니다.

③ 포인트색

제목이나 중요한 부분에 사용하는 색상입니다. 청록색이나 주황색처럼 눈에 잘 띄는 색상을 선택할 수 있습니다.

AI에게 색상 변경 요청하기

안티그래비티 입력 프롬프트

페이지 배경색은 아주 연한 하늘색으로 바꿔줘. 글자색은 짙은 남색으로 설정해줘. 제목과 중요한 부분에는 청록색을 사용해줘. 전체적으로 차분하고 깔끔한 디자인으로 만들어줘.

색상은 많이 사용하는 것보다 일관성 있게 사용하는 것이 중요합니다.

4. 내 사진을 웹페이지에 추가하기

웹페이지에 사진을 추가하면 사이트가 더욱 개성 있게 바뀝니다.

프로필 사진이나 풍경 사진 등 원하는 이미지를 사용할 수 있습니다.

① 사진 파일 이름 변경하기

먼저 사용할 사진을 준비합니다.

파일 이름은 영어 소문자로 간단하게 정리하는 것이 좋습니다.

예를 들어 다음과 같이 변경합니다.

추천 파일 이름

my-photo.jpg

파일 확장명도 확인하세요. JPG 파일은 .jpg, PNG 파일은 .png로 끝나야 합니다.

확장명이 두 번 붙지 않도록 주의하는 것이 좋습니다.

② public 폴더에 사진 넣기

1. 안티그래비티에서 프로젝트를 엽니다.
2. 왼쪽 파일 목록에서 public 폴더를 찾습니다.
3. 준비한 사진을 폴더 안에 넣습니다.
4. 사진 파일이 정상적으로 들어갔는지 확인합니다.

public 폴더가 없다면 AI에게 폴더를 만들어 달라고 요청할 수 있습니다.

③ 사진을 웹페이지에 표시하기

안티그래비티 입력 프롬프트

public 폴더에 있는 my-photo.jpg 사진을 페이지 제목 아래에 넣어줘. 사진은 너무 크지 않게 해줘. 동그란 모양으로 표시하고 전체 디자인과 자연스럽게 어울리게 만들어줘.

파일 이름은 실제 사진 이름과 정확하게 일치해야 합니다.

5. 여백을 조정해 깔끔하게 만들기

웹페이지 디자인에서 생각보다 중요한 요소가 바로 여백입니다.

글자와 사진이 화면 가장자리에 붙어 있으면 답답한 느낌을 줄 수 있습니다.

반대로 적절한 여백을 주면 같은 내용도 훨씬 편하게 읽을 수 있습니다.

특히 제목과 사진, 소개 문장 사이의 간격을 적절하게 조정하는 것이 좋습니다.

AI에게 여백 조정 요청하기

안티그래비티 입력 프롬프트

내용이 화면 가장자리에 너무 붙어 있어. 위아래와 좌우에 여백을 넉넉하게 줘. 제목과 사진, 소개 문장 사이의 간격도 보기 좋게 조정해줘. 전체적으로 여유 있고 깔끔하게 만들어줘.

6. 모바일 화면 확인하기

웹사이트는 컴퓨터뿐 아니라 스마트폰에서도 잘 보여야 합니다.

컴퓨터에서는 괜찮아 보이던 페이지가 스마트폰에서는 깨져 보일 수 있습니다.

글자가 잘리거나 사진이 화면 밖으로 나갈 수도 있습니다.

따라서 웹사이트를 완성하기 전에 모바일 화면을 반드시 확인해야 합니다.

크롬에서 모바일 화면 확인하기

1. 크롬에서 내 웹페이지를 엽니다.
2. 키보드에서 F12를 누릅니다.
3. 개발자 도구가 열리면 휴대폰 모양 아이콘을 누릅니다.
4. 또는 Ctrl + Shift + M을 누릅니다.
5. 원하는 휴대폰 화면 크기를 선택합니다.

이제 스마트폰과 비슷한 크기로 웹페이지를 확인할 수 있습니다.

모바일 화면 수정 프롬프트

휴대폰처럼 좁은 화면에서도 글자와 사진이 잘리지 않도록 수정해줘. 화면 크기에 맞춰 요소의 크기와 배치를 조정해줘. 모바일에서도 읽기 편한 반응형 웹디자인으로 만들어줘.

수정이 끝났다면 실제 스마트폰에서도 접속해 확인하는 것이 좋습니다.

7. 수정한 화면이 바뀌지 않을 때

디자인 변경을 요청했는데 크롬 화면이 그대로라면 다음 내용을 확인해 보세요.

화면이 바뀌지 않는 경우

수정 사항이 적용되었는지 확인하세요. 필요하다면 크롬에서 F5를 눌러 새로고침합니다.

사진이 보이지 않는 경우

사진이 public 폴더에 있는지 확인하세요. 파일 이름과 확장명도 다시 확인합니다.

글자가 잘 보이지 않는 경우

배경색과 글자색의 대비를 높여 달라고 AI에게 요청하면 됩니다.

사이트가 열리지 않는 경우

개발 서버가 실행 중인지 확인하세요. 서버가 종료되었다면 다시 실행해야 합니다.

디자인을 되돌리고 싶은 경우

방금 수정한 디자인이 마음에 들지 않아. 수정 전 상태로 되돌려줘. 다른 방식으로 다시 만들어줘.

중요한 파일을 수정하기 전에는 별도로 백업해 두는 것이 안전합니다.

8. 안티그래비티 웹페이지 꾸미기 정리

이번 시간에는 안티그래비티를 활용해 웹페이지 디자인을 개선하는 방법을 알아봤습니다.

• 제목: 크고 굵게 설정하기
• 색상: 세 가지 색상을 중심으로 사용하기
• 사진: public 폴더에 넣어 표시하기
• 여백: 요소 사이에 적절한 공간 주기
• 모바일: 스마트폰 화면에서 확인하기

안티그래비티를 활용하면 복잡한 코드를 직접 작성하지 않아도 됩니다.

원하는 디자인을 한국어로 설명하면 AI가 코드를 수정하도록 요청할 수 있습니다.

처음부터 모든 것을 바꾸려고 하지 마세요. 제목부터 시작해서 색상과 사진, 여백 순서로 하나씩 수정하면 됩니다.

다음 단계: GitHub에 작업 저장하기

이제 나만의 웹페이지에 제목과 색상, 사진까지 추가했습니다.

하지만 지금까지 만든 웹사이트는 아직 내 컴퓨터의 프로젝트 폴더에 저장되어 있습니다.

다음 단계에서는 Git과 GitHub를 이용해 작업 내용을 안전하게 저장하는 방법을 알아보겠습니다.

GitHub를 활용하면 작업 이력을 기록하고 필요할 때 이전 상태를 확인하거나 복구하는 데 도움이 됩니다.

이 글은 안티그래비티 초보자를 위한 바이브코딩 학습 내용을 바탕으로 재구성했습니다. 실제 메뉴와 화면은 프로그램 버전에 따라 다르게 보일 수 있습니다.

안티그래비티 사용법: 코딩 초보자를 위한 AI 웹사이트 만들기

안티그래비티(Antigravity) 사용법: 

코딩을 몰라도 AI와 함께 첫 웹사이트 만들기

웹사이트를 만들고 싶지만 코딩을 배워야 한다는 부담 때문에 시작하지 못하고 있나요?

이제는 프로그래밍 언어를 처음부터 공부하지 않아도 AI의 도움을 받아 웹사이트를 제작할 수 있습니다.

구글의 AI 개발 도구인 안티그래비티(Antigravity)를 활용하면 한국어로 원하는 작업을 설명하고, AI가 작성한 코드를 이용해 실제 웹페이지를 만들 수 있습니다.

이번 글에서는 안티그래비티 설치부터 작업 환경 설정, 첫 프로젝트 생성, 웹사이트 실행까지 초보자 관점에서 차근차근 알아보겠습니다.

1. 안티그래비티란 무엇인가?

안티그래비티는 AI를 활용해 소프트웨어와 웹사이트를 개발할 수 있도록 도와주는 개발 도구입니다.

기존에는 웹사이트를 만들려면 HTML, CSS, JavaScript 등의 프로그래밍 지식이 필요했습니다.

하지만 AI 개발 도구를 이용하면 만들고 싶은 기능이나 화면을 자연어로 설명하고, AI가 작성한 코드를 검토하면서 개발을 진행할 수 있습니다.

예를 들어 다음과 같이 요청할 수 있습니다.

"간단한 개인 소개 웹사이트를 만들어줘. 이름과 자기소개가 화면 중앙에 보이도록 해줘."

AI는 요청을 분석한 뒤 필요한 파일과 코드를 작성합니다.

따라서 코딩 경험이 적은 사람도 아이디어를 실제 웹사이트로 구현하는 과정을 경험할 수 있습니다.

개발 과정에서 사용하는 주요 도구

도구	역할
Antigravity	AI와 대화하며 코드를 작성하고 수정하는 개발 환경
작업 폴더	프로젝트 파일을 모아 두는 공간
PowerShell	명령어를 실행하는 윈도우 터미널
Node.js	웹 개발 환경과 실행 도구를 제공하는 프로그램
Chrome	제작한 웹사이트를 확인하는 브라우저

2. 안티그래비티 설치하기

가장 먼저 개발에 필요한 프로그램을 설치해야 합니다.

이번 과정에서는 다음 세 가지를 준비합니다.

• 안티그래비티 개발 도구
• 구글 계정
• Node.js

① 안티그래비티 다운로드

아래 공식 사이트에 접속합니다.

안티그래비티 공식 다운로드 페이지 바로가기

다운로드 페이지에서 일반 개발 환경에 해당하는 Antigravity IDE를 선택합니다.

운영체제에 맞는 설치 파일을 내려받아 설치하면 됩니다. 다른 용도의 제품이나 설치 항목과 혼동하지 않도록 선택 항목을 확인하세요.

② 구글 계정으로 로그인

프로그램을 실행한 다음 개인 구글 계정으로 로그인합니다.

공용 컴퓨터를 사용하는 경우에는 이전 사용자의 계정이 남아 있지 않은지 확인해야 합니다.

③ Node.js 설치

다음으로 Node.js를 설치합니다.

Node.js 공식 홈페이지에 접속한 뒤 LTS 버전을 선택합니다.

윈도우 사용자는 설치 파일인 MSI 파일을 내려받아 실행하면 됩니다.

별도의 설정을 변경할 필요가 없다면 기본 설치 옵션을 그대로 사용해도 됩니다.

중요: Node.js 설치가 끝나면 안티그래비티를 완전히 종료한 뒤 다시 실행하는 것이 좋습니다. 그래야 새로 설치된 개발 환경을 인식할 수 있습니다.

3. 프로젝트 전용 폴더 만들기

프로그램 설치가 끝났다면 이제 첫 번째 프로젝트를 준비할 차례입니다.

처음 시작할 때는 컴퓨터 전체를 작업 공간으로 사용하지 말고, 별도의 프로젝트 폴더를 만드는 것이 좋습니다.

이렇게 하면 AI가 작업해야 할 파일의 범위를 명확하게 지정할 수 있습니다.

폴더 이름 정하기

프로젝트 폴더 이름은 영어 소문자와 하이픈(-)을 이용해 간단하게 작성하는 것을 추천합니다.

권장하는 이름	피하는 이름
my-first-site	내 첫 사이트
stock-project	Stock Project (1)

윈도우에서 폴더 만들기

1. 바탕화면에서 마우스 오른쪽 버튼을 클릭합니다.
2. 새로 만들기에서 폴더를 선택합니다.
3. 폴더 이름을 my-first-site로 지정합니다.
4. Enter 키를 눌러 저장합니다.

안티그래비티에서 폴더 열기

1. 안티그래비티를 실행합니다.
2. 상단 메뉴에서 File을 선택합니다.
3. Open Folder를 클릭합니다.
4. 방금 만든 my-first-site 폴더를 선택합니다.

폴더를 신뢰할 것인지 확인하는 메시지가 나오면 직접 만든 폴더인지 확인한 뒤 승인합니다.

다른 사람이 보내 준 폴더라면 내용을 확인하지 않고 무조건 신뢰해서는 안 됩니다.

4. AI에게 작업 범위와 진행 방법 알려주기

이제 본격적으로 AI와 함께 개발을 시작합니다.

처음부터 무조건 코드를 작성하라고 요청하기보다는 AI가 작업할 범위와 진행 순서를 먼저 지정하는 것이 좋습니다.

특히 다음 두 가지 원칙을 기억하세요.

• 현재 프로젝트 폴더 안에서만 작업하도록 요청합니다.
• 실제 작업을 시작하기 전에 계획을 먼저 확인합니다.

처음 사용할 AI 프롬프트

아래 내용을 복사해 안티그래비티의 AI 채팅창에 입력합니다.

안녕하세요. 지금 열려 있는 폴더를 이용해 첫 번째 웹 프로젝트를 만들려고 합니다. 다음 규칙을 반드시 지켜주세요. 1. 현재 프로젝트 폴더 안에서만 작업합니다. 2. 폴더 외부의 파일은 수정하거나 삭제하지 않습니다. 3. 가장 간단한 Next.js 프로젝트를 구성합니다. 4. TypeScript, App Router, Tailwind CSS를 사용합니다. 5. 내 컴퓨터는 윈도우이며 PowerShell 기준으로 명령어를 작성합니다. 6. 실제 작업을 시작하기 전에 실행할 작업과 생성할 파일을 5단계로 설명합니다. 7. 내가 승인하기 전에는 파일을 만들거나 명령어를 실행하지 않습니다. 먼저 작업 계획을 설명해 주세요.

맥을 사용하는 경우에는 운영체제에 관한 내용을 맥 환경에 맞게 수정하면 됩니다.

AI가 제시한 계획 확인하기

프롬프트를 전송하면 AI가 먼저 작업 계획을 보여 줍니다.

이때 어떤 프로그램을 설치하고 어떤 파일을 생성하는지 확인합니다.

내용이 적절하다면 채팅창에 "좋아. 진행해줘."라고 입력합니다.

이후 AI가 터미널 명령어 실행이나 파일 변경에 대한 승인을 요청할 수 있습니다.

승인 창이 나타나면 실행할 내용을 확인한 뒤 필요한 작업만 허용합니다.

무슨 작업인지 이해되지 않는다면 먼저 AI에게 다음과 같이 물어보세요.

이 명령어가 어떤 작업을 수행하는지 초보자도 이해할 수 있도록 설명해 줘.

5. PowerShell 사용법과 오류 확인하기

AI가 프로젝트를 생성하기 시작하면 화면 아래쪽에 PowerShell이라는 터미널 창이 나타날 수 있습니다.

처음에는 검은 화면에 글자가 계속 출력되기 때문에 어렵게 느껴질 수 있지만, 기본적인 상태만 이해하면 됩니다.

터미널에서 확인할 세 가지 상태

화면 상태	의미
글자가 계속 출력됨	프로그램이 작업 중이므로 기다립니다.
PS 경로가 다시 표시됨	명령어 실행이 끝난 상태입니다.
빨간색 오류 메시지	오류 내용을 확인하고 해결해야 합니다.

오류가 발생했을 때 해결하는 방법

코딩을 처음 시작하면 오류가 발생하는 것은 자연스러운 일입니다.

오류 메시지를 이해하지 못하더라도 당황할 필요는 없습니다.

빨간색으로 표시된 오류 내용을 복사해 AI 채팅창에 붙여 넣습니다.

방금 실행한 명령어에서 다음 오류가 발생했습니다. 오류가 발생한 원인을 초보자도 이해할 수 있도록 설명해 주세요. 가능하다면 현재 프로젝트의 다른 파일에 영향을 주지 않는 안전한 해결 방법을 제시해 주세요. 오류 내용: [여기에 오류 메시지 붙여 넣기]

이처럼 오류 내용을 AI에게 전달하면 문제의 원인을 파악하고 수정하는 데 도움을 받을 수 있습니다.

윈도우에서 스크립트 실행 오류가 발생한다면?

Node.js 설치 후 PowerShell에서 스크립트 실행이 차단되는 경우가 있습니다.

이때 오류 메시지가 PowerShell의 실행 정책과 관련된 것인지 먼저 확인합니다.

해당 오류가 맞다면 현재 사용자 계정에 적용되는 실행 정책을 설정할 수 있습니다.

PowerShell에 입력할 명령어:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

변경 여부를 묻는 메시지가 나오면 내용을 확인한 뒤 Y를 입력합니다.

이 설정은 현재 사용자 범위에 적용됩니다. 보안 설정을 변경하는 작업이므로 명령어의 의미를 이해한 뒤 실행하세요.

6. 첫 번째 웹사이트 실행하기

프로젝트 파일 생성이 끝났다면 이제 웹사이트를 실행할 차례입니다.

직접 복잡한 명령어를 입력할 필요 없이 AI에게 개발 서버 실행을 요청할 수 있습니다.

AI에게 웹사이트 실행 요청하기

이제 현재 프로젝트의 웹사이트를 실행해 줘. Next.js 개발 서버를 시작하고, 크롬에서 확인할 수 있는 로컬 주소를 알려줘. 오류가 발생하면 원인을 확인하고 해결 방법을 설명해 줘.

AI가 명령어를 실행하면 승인 요청이 나올 수 있습니다. 실행 내용을 확인하고 승인합니다.

정상적으로 실행되면 다음과 비슷한 주소가 표시됩니다.

http://localhost:3000

크롬에서 접속하기

1. 구글 크롬을 실행합니다.
2. 주소창에 AI가 알려 준 주소를 입력합니다.
3. Enter 키를 누릅니다.
4. 프로젝트의 첫 화면이 표시되는지 확인합니다.

만약 3000번 포트를 다른 프로그램이 사용하고 있다면 3001 등 다른 번호가 표시될 수 있습니다.

이때는 임의로 주소를 입력하지 말고 AI가 알려 준 주소를 그대로 사용합니다.

주의할 점: localhost 주소는 현재 컴퓨터에서만 접속할 수 있는 로컬 개발 주소입니다. 아직 인터넷에 공개된 웹사이트가 아닙니다.

또한 개발 서버가 실행 중인 터미널을 종료하면 웹사이트도 중단될 수 있습니다.

7. 웹페이지에 내 이름과 소개 문장 넣기

첫 화면이 나타났다면 이제 자신만의 페이지로 꾸며 보겠습니다.

처음부터 여러 기능을 추가하기보다는 제목과 소개 문장부터 수정하는 것이 좋습니다.

① 메인 제목 변경하기

AI에게 다음과 같이 요청합니다.

메인 페이지에서 가장 큰 제목 한 줄을 다음 문장으로 변경해 줘. "안녕하세요, 홍길동입니다." 다른 문장이나 디자인, 파일은 변경하지 마. 제목 한 줄만 수정해 줘.

홍길동 대신 자신의 이름을 입력하면 됩니다.

② 자기소개 문장 추가하기

이번에는 제목 아래에 자신이 만들고 싶은 서비스나 웹사이트의 목적을 한 문장으로 작성합니다.

메인 제목 아래에 소개 문장 한 줄을 추가해 줘. 내용은 다음과 같아. "주식 투자에 필요한 정보를 쉽게 정리해 제공하는 웹사이트입니다." 제목보다 글자 크기는 작게 하고, 차분한 디자인으로 만들어 줘. 기존의 다른 요소는 수정하지 마.

이렇게 하면 자신만의 첫 소개 페이지가 만들어집니다.

③ 수정 결과 확인하기

AI가 코드를 변경하면 변경 내용을 확인합니다.

• 요청한 부분만 수정되었는지 확인합니다.
• 변경된 내용을 승인합니다.
• 크롬 화면에서 결과를 확인합니다.
• 화면이 갱신되지 않으면 F5 키를 누릅니다.

AI가 요청하지 않은 부분까지 수정했다면 이전 상태로 되돌리도록 요청할 수 있습니다.

방금 수정한 내용을 취소하고 이전 상태로 복구해 줘. 내가 요청한 제목 부분만 다시 수정해 줘.

8. 안티그래비티 사용 중 자주 발생하는 문제

처음 개발 환경을 구성하다 보면 여러 가지 문제가 발생할 수 있습니다.

대표적인 오류와 해결 방법을 정리했습니다.

문제 1. npm을 찾을 수 없다는 오류

Node.js가 정상적으로 설치되지 않았거나 설치 후 개발 도구를 다시 실행하지 않은 경우 발생할 수 있습니다.

해결 방법

1. 안티그래비티를 완전히 종료합니다.
2. Node.js 설치 상태를 확인합니다.
3. 안티그래비티를 다시 실행합니다.
4. 문제가 계속되면 AI에게 오류 메시지를 전달합니다.

문제 2. 크롬에서 웹사이트가 열리지 않는 경우

개발 서버가 실행되지 않았거나 잘못된 주소로 접속했을 가능성이 있습니다.

해결 방법

• 터미널에서 개발 서버가 실행 중인지 확인합니다.
• AI가 알려 준 localhost 주소를 확인합니다.
• 주소에 표시된 포트 번호가 정확한지 확인합니다.

문제 3. Port already in use 오류

이미 다른 프로그램이 같은 포트를 사용하고 있다는 의미입니다.

AI에게 다음과 같이 요청할 수 있습니다.

현재 포트가 이미 사용 중이라고 나와. 사용 가능한 다른 포트를 찾아서 개발 서버를 실행해 줘.

문제 4. AI가 요청하지 않은 부분까지 수정한 경우

AI에게 작업 범위를 구체적으로 알려 주지 않으면 예상보다 많은 파일이나 디자인이 변경될 수 있습니다.

이런 경우에는 변경 내역을 확인하고 되돌리기를 요청합니다.

앞으로는 프롬프트에 다음 문장을 추가하는 것이 좋습니다.

요청한 부분만 수정하고 다른 파일과 기능은 절대 변경하지 마.

문제 5. 개발 서버를 실수로 종료한 경우

터미널을 닫거나 실행을 중단하면 웹사이트가 더 이상 표시되지 않을 수 있습니다.

AI에게 개발 서버를 다시 실행해 달라고 요청하면 됩니다.

9. 오늘 배운 내용 정리

이번 과정에서는 코딩을 처음 접하는 사람도 AI를 활용해 웹사이트를 제작하는 기본 과정을 살펴봤습니다.

핵심 내용을 정리하면 다음과 같습니다.

1. 안티그래비티와 Node.js를 설치합니다.
2. 프로젝트 전용 폴더를 만듭니다.
3. AI에게 작업 범위와 진행 규칙을 알려 줍니다.
4. AI가 제시한 계획을 확인하고 승인합니다.
5. 터미널에서 실행 상태와 오류 메시지를 확인합니다.
6. 개발 서버를 실행하고 크롬에서 웹사이트를 확인합니다.
7. AI에게 제목과 소개 문장 수정을 요청합니다.

가장 중요한 것은 코드를 직접 작성하는 능력보다 AI에게 원하는 작업을 정확하게 설명하고 결과를 확인하는 습관입니다.

10. 다음 단계: 나만의 웹사이트로 발전시키기

이제 첫 번째 웹페이지를 만들었다면 다음 단계로 넘어갈 수 있습니다.

단순한 소개 페이지에 사진과 색상을 추가하고, 메뉴와 버튼을 만들고, 실제로 사용할 수 있는 기능을 하나씩 구현해 보세요.

예를 들어 다음과 같은 프로젝트를 만들어 볼 수 있습니다.

• 개인 포트폴리오 및 소개 사이트
• 주식 테마와 종목 정보를 정리하는 사이트
• 일정과 할 일을 관리하는 웹페이지
• 간단한 블로그 및 콘텐츠 관리 페이지
• 업무 자동화를 위한 개인용 도구

처음부터 완벽한 웹사이트를 만들려고 할 필요는 없습니다.

작은 기능 하나를 만들고, 실행해 보고, 수정하는 과정을 반복하면 됩니다.

코딩을 몰라도 아이디어가 있다면 시작할 수 있습니다. 

AI와 함께 나만의 첫 번째 웹사이트를 만들어 보세요.

---

참고 자료

• Google Antigravity 공식 다운로드
• Node.js 공식 홈페이지

※ 이 글은 안티그래비티를 처음 사용하는 초보자를 위한 실습형 안내 자료입니다. 프로그램의 메뉴와 설치 화면은 버전에 따라 달라질 수 있습니다.

```