API 키와 .env

소프트웨어를 만들다 보면 외부 서비스를 붙일 때가 생겨요. 이메일을 보내거나, 결제를 받거나, AI 기능을 넣거나요. 그때마다 AI가 "API 키를 발급받아서 .env에 넣어주세요"라고 해요. API 키가 뭔지, .env가 뭔지, 왜 코드에 바로 적지 않고 굳이 따로 두는지 정리해드릴게요.

API 키는 출입증이에요

외부 서비스는 아무 요청이나 받아주지 않아요. 가입하면 sk-a1b2c3... 같은 긴 문자열을 주는데, 이게 API 키예요. 내 코드가 그 서비스를 부를 때마다 이 키를 함께 내밀어서 "이 요청은 이 계정에서 온 거예요"를 증명해요.

그래서 키를 가진 쪽이 곧 나예요. 누가 내 키를 주워가면 그 사람이 쓴 사용량이 내 앞으로 청구되고, 내 계정의 데이터에도 손댈 수 있어요.

다만 모든 키가 비밀인 것은 아니에요. Supabase의 publishable key처럼 브라우저에 공개하는 것을 전제로 만든 키도 있습니다. 이 키가 데이터 접근 권한 자체를 갖지 않는 이유는 RLS가 로그인한 사용자별로 허용할 데이터를 다시 검사하기 때문이에요.

코드에 직접 적으면 안 돼요

키를 코드 안에 그대로 적으면 당장은 편해요. 그런데 코드는 GitHub에 올라가고, 다른 사람과 공유하고, 언젠가 공개될 수도 있어요. 코드에 적힌 키는 코드가 가는 곳마다 따라가요. 공개 저장소에 올라온 키를 긁어모으는 봇이 늘 돌아다니고 있어서, 실수로 올린 키는 금방 남의 손에 들어가요.

.env — 환경변수를 담는 파일이에요

그래서 이런 값들은 코드 밖에, .env라는 파일에 따로 담아요.

DATABASE_URL=postgres://...
SITE_URL=http://localhost:3000
RESEND_API_KEY=re_a1b2c3...

코드에는 값 대신 이름만 적고, 실제 값은 프로그램이 실행될 때 .env에서 채워져요. 이렇게 다루는 값을 환경변수라고 불러요.

이름에 "환경"이 붙은 데는 이유가 있어요. .env에는 비밀값만 들어가는 게 아니라, 실행되는 환경마다 달라지는 설정값이 다 들어가요. 데이터베이스 주소, 사이트 주소, 결제를 테스트 모드로 돌릴지 실제 모드로 돌릴지 같은 것들요. 코드는 하나지만, 어떤 환경에서 도느냐에 따라 다른 값을 끼워 넣는 거예요.

그리고 .env는 GitHub에 올리지 않아요. .gitignore라는 목록에 적어두면 Git이 이 파일을 기록하지 않아요. 비밀값이 코드를 따라다니는 문제가 여기서 해결돼요.

배포 환경에는 배포 환경의 값이 있어요

localhost에서 잘 되던 기능이 배포하면 안 돌아가는 일이 자주 있어요. 이메일이 안 나가고, AI 응답이 비어 있고요. .env가 GitHub에 안 올라가니, GitHub에서 코드를 가져가는 배포 서버에는 .env가 없기 때문이에요.

그래서 Vercel 같은 배포 서비스에는 환경변수를 등록하는 화면이 따로 있어요. 여기에 같은 이름으로 값을 넣어주면 배포된 사이트도 제 몫의 값을 갖게 돼요.

같은 API 키인데 Git에는 넣으면 안 되고 Vercel에는 직접 입력해도 되는 이유는 Git 기록과 배포 환경변수의 차이에서 더 자세히 설명했습니다.

따로 등록하는 게 번거로워 보이지만, 사실 이게 환경변수의 쓸모예요. 작업실과 매장은 다른 환경이라 값도 달라야 하거든요. 개발할 땐 결제를 테스트 키로 돌리다가 매장에는 실제 키를 걸고, 사이트 주소도 localhost 대신 진짜 주소로 바꿔 끼우는 식이에요. 코드는 그대로 두고 환경변수만 갈아 끼우면 돼요.

특히 개발과 운영에서 같은 데이터베이스 주소를 사용하면 테스트 작업이 실제 데이터에 영향을 줄 수 있습니다. 환경마다 DATABASE_URL을 어떻게 나누는지는 개발·운영 데이터베이스를 분리해야 하는 이유에서 자세히 살펴볼 수 있어요.

바이브코딩에서는

.env 파일을 만들고 .gitignore에 넣는 것까지는 AI가 알아서 해요. "이메일 발송 붙여줘"라고 시키면 코드에는 이름만 적어두고, 어떤 키를 발급받아 어디에 넣을지 알려줘요. 우리가 직접 하는 일은 발급받은 키를 .env에 붙여넣는 것, 그리고 배포할 때 배포 서비스에도 등록하는 것 정도예요.

키가 실수로 GitHub에 올라갔다면 파일을 지우는 걸로는 부족해요. 커밋 기록에 그대로 남아 있거든요. 올라간 키는 버리고 새로 발급받아야 해요.

정리

• API 키는 외부 서비스가 나를 알아보는 출입증이에요. 키를 가진 쪽이 곧 나예요.
• 환경변수는 환경마다 달라지는 설정값이에요. 비밀값도, 데이터베이스 주소도, 테스트/실제 모드도 여기에 담아요.
• 코드에는 이름만 적고 값은 .env에 둬요. .env는 GitHub에 올리지 않아요.
• 배포 환경의 값은 배포 서비스의 환경변수 화면에 따로 등록해요. 배포 후 안 돌아가면 이것부터 확인해보세요.
• 유출된 키는 지워도 커밋 기록에 남아요. 재발급해야 해요.

처음 외부 서비스를 붙이는 날 .env 때문에 한 번은 헤매게 돼요. 그때 "환경마다 값이 다르구나"만 기억하면 헤매는 시간이 훨씬 짧아져요. 배포하고 뭔가 안 되면, 매장에 값을 걸어뒀는지부터 봐 주세요.

API를 직접 연결하는 과정은 바이브코딩 가이드 9장에서, 배포 전 비밀값 점검은 12장에서 실습할 수 있어요.

비밀 키뿐 아니라 로그인·권한·입력값·파일 업로드까지 공개 전에 확인하려면 바이브코딩 웹앱 보안 체크리스트를 함께 사용하세요.