이럴 때 막혀요
안녕하세요, 칼퇴하는 예린이에요.
메모 앱에 AI 요약 기능을 붙인다고 해 볼게요. AI가 “API 키를 환경변수로 설정하고 .env에 넣으세요”라고 안내해요.
키는 준비했는데, 어디에 넣으라는 말인지 막막하죠. 오늘은 앱이 기능을 실행할 때 필요한 값을 어디에서 읽어 오는지로 쉽게 풀어 볼게요.
1. 한 줄로 먼저 이해하기
.env = 가게 열쇠를 넣어 두는
잠긴 서랍
코드는 가게 운영 매뉴얼이에요. 열쇠(API 키)는 매뉴얼에 붙여 두지 않고 서랍에 따로 넣어요. 매뉴얼에는 “열쇠는 서랍에 있음”이라고만 적어 둬요.
단, 이 서랍은 저절로 잠기지 않아요. .env는 암호가 걸린 금고가 아니라 그냥 글자가 적힌 파일이에요.
실제로 환경변수는 프로그램이 실행되는 환경에서 받는 설정값이에요. .env는 개발할 때 그 설정값을 적어 두는 데 자주 쓰는 파일이에요.
서랍을 잠그는 건 결국 내 몫이에요. 서랍째 남에게 들고 가지 않도록, 즉 코드와 함께 올리지 않도록 챙겨야 해요.
그러니까 AI가 “.env에 넣으세요”라고 하면, ‘열쇠를 매뉴얼에 적지 말고 서랍에 따로 넣으세요’라는 말로 들으면 돼요.
2. 조금 더 자세히
코드는 동작을, 설정은 쓸 값을 정해요
AI가 요약 버튼의 코드를 써 줄 수는 있어요. 하지만 어떤 서비스의 어떤 API 키를 쓸지는 따로 설정해야 할 수 있어요. 코드에 키를 직접 써넣는 대신 실행 환경에서 값을 읽게 하면, 동작과 설정을 나눌 수 있어요.
설정에는 이름과 값이 있어요. AI가 “API 키 설정 이름은 AI_API_KEY입니다”라고 알려 주면, 앱이 그 이름으로 값을 찾도록 만들어졌다는 뜻이에요.
이름은 정확히 맞추고, 실제 키 값은 비공개로 다뤄요. 이름을 비슷하게만 바꿔도 앱이 값을 못 찾을 수 있어요.
.env는 설정을 적어 두는 그냥 파일이에요
개발 도구나 프레임워크(앱을 만들 때 쓰는 기본 틀과 도구 모음) 중에는 .env에 적힌 값을 읽어 실행 환경에 넣어 주는 기능이 있어요. 하지만 파일을 만들었다고 모든 프로그램이 자동으로 읽는 건 아니에요. AI가 .env를 만들라고 하면, 지금 프로젝트가 그 파일을 어떻게 읽는지도 함께 물어보세요.
.env는 보통 일반 텍스트 파일이라, 파일을 열 수 있는 사람은 안의 값을 볼 수 있어요. 이름 앞에 점이 붙었다고 금고가 되는 건 아니에요. 그래서 저장소(코드를 보관하고 공유하는 곳)에 넣지 않고, 필요한 실행 환경에서만 쓰도록 구성해야 해요.
내 컴퓨터 설정과 배포한 앱 설정은 따로예요
내 컴퓨터에서 .env를 읽어 요약이 잘되더라도, 배포한 앱(인터넷에 올려 다른 사람도 쓰게 한 앱)에는 같은 값이 없을 수 있어요. 그래서 배포 서비스의 비공개 설정 화면에 필요한 값을 따로 등록하는 경우가 많아요.
“내 컴퓨터에서는 되는데 공유 주소에서는 안 돼”라면, 배포 환경에도 필요한 설정이 있는지 AI에게 확인해 달라고 하세요. 설정을 바꾼 뒤 다시 실행하거나 배포해야 하는지는 쓰는 도구마다 달라요.
브라우저로 가는 값과 서버에만 둘 값을 나눠요
브라우저에서 실행되는 코드는 사용자가 들여다볼 수 있어요. 브라우저로 전달된 값은 비밀로 지켜진다고 기대하면 안 돼요. 그래서 비밀 키는 서버 쪽에서 쓰는 구조가 필요한 경우가 일반적이에요.
어떤 도구는 이름 앞에 붙은 표시(접두어)로 ‘화면에 공개해도 되는 값’을 구분해요(예: Next.js의 NEXT_PUBLIC_). 결국 중요한 건 .env에 들어 있는지보다, 그 값이 최종적으로 누구에게 전달되는지예요.
3. 실제로 이렇게 써요
제가 겪은 일
저는 뉴스 수집기를 만들 때 Jev라는 AI의 API 키를 썼어요. 이 키를 코드에 쓰지 않고, 컴퓨터 환경변수 TYPESAFE_API_KEY에 등록해 뒀어요. 맥은 터미널에서 ~/.zshrc에 한 줄을 넣고, 윈도우는 setx로 등록해요.
이 경우엔 서랍이 .env 파일이 아니라 컴퓨터 자체 설정인 셈이에요. 덕분에 프로그램 파일(zip)을 다른 사람에게 줘도 키는 따라가지 않아요. 다른 컴퓨터에서 쓰려면 그 컴퓨터에서 키를 따로 한 번 등록하면 돼요.
만약 키를 코드에 직접 적어 뒀다면, zip 파일을 건네는 순간 열쇠까지 함께 건넨 셈이 됐을 거예요. 매뉴얼과 열쇠를 나눠 둔 덕분에 마음 편히 파일을 공유할 수 있어요.
대신 한 가지는 늘 조심해요. 키가 채팅이나 화면 녹화에 나오지 않게 하는 거예요.
눈으로 보는 예시
.env 파일은 실제로 이렇게 생겼어요. 아래 값은 가짜예요.
# .env (저장소에 올리지 않아요) AI_API_KEY=여기에_내_키
= 왼쪽이 이름, 오른쪽이 값이에요. 이름은 AI가 알려 준 그대로 쓰고, 값 자리에만 내 키를 넣어요. #으로 시작하는 줄은 메모라서 앱이 읽지 않아요.
코드에는 키 값이 아니라 AI_API_KEY라는 이름만 적혀 있어요. 앱은 실행될 때 이 이름으로 값을 찾아 읽어요.
그리고 .gitignore(저장소에 올리지 않을 파일 목록)에 .env를 한 줄 넣어 두면, 코드를 올릴 때 이 파일이 빠져요.
# .gitignore .env
값을 넣는 곳마다 볼 수 있는 사람이 달라요.
| 위치 | 어디에 넣나 | 누가 볼 수 있나 |
|---|---|---|
| 내 컴퓨터 | .env 파일, 또는 컴퓨터 환경변수 | 그 파일이나 컴퓨터를 열 수 있는 사람 |
| 배포 서비스 | 배포 서비스의 비공개 설정 화면 | 그 설정 화면에 들어갈 수 있는 사람 |
| 브라우저 | 브라우저로 전달되는 코드(공개용 표시가 붙은 값 등) | 앱을 쓰는 누구나. 비밀 키는 여기에 두면 안 돼요. |
같은 키라도 어디에 두느냐에 따라 볼 수 있는 사람이 완전히 달라져요. 비밀 키는 위의 두 칸에만 두세요.
AI에게 이렇게 말해 보세요
AI에게 키 원문을 보내야 코드가 완성되는 건 아니에요. 설정 이름, 입력할 화면이나 파일, 그 값이 필요한 이유를 먼저 물어보세요. 실제 키는 지정된 비공개 위치에 내가 직접 넣으면 돼요.
이 앱의 요약 기능에 필요한 환경변수 이름과 용도를 설명해 줘. 실제 키는 내가 비공개 설정에 직접 입력할게. 내 컴퓨터와 배포 환경에서 각각 어디에 설정해야 하는지 알려 주고, 비밀 키가 브라우저에 전달되지 않는 구조인지 확인해 줘.
설정을 마친 뒤에는 이렇게 확인을 부탁해 보세요.
키 값을 화면이나 로그에 그대로 출력하지 않으면서, 앱이 설정값을 제대로 읽고 있는지 확인하는 방법을 알려 줘.
잘 됐는지 확인하기
설정을 적어 둔 것과 앱이 그 값으로 실제 작동하는 건 다른 일이에요. 아래 항목을 하나씩 확인해 보세요.
- 코드 안에 키 원문이 직접 적혀 있지 않아요.
- .gitignore에 .env가 들어 있어요.
- 배포한 앱에도 같은 이름으로 값이 등록돼 있어요.
- 비밀 키가 브라우저로 전달되지 않는 구조인지 AI에게 확인받았어요.
- 요약 버튼을 눌러 실제 결과가 나오고, 키 값은 화면이나 로그에 보이지 않아요.
4. 오늘 정리
오늘 기억할 3줄
1. .env는 열쇠(API 키)를 코드와 따로 넣어 두는 서랍이에요.
2. 서랍은 저절로 잠기지 않아요. .env는 그냥 글자 파일이니 저장소에 올리지 않아요.
3. 중요한 건 값이 최종적으로 누구에게 전달되는지예요. 비밀 키는 브라우저로 보내지 않아요.
다음 7편에서는 AI가 라이브러리나 패키지를 설치하자고 하는 이유와 npm·pip의 역할을 알아봐요.
설명에 참고한 공식 자료
Next.js 공식 문서: .env와 공개되는 환경변수의 구분
그럼 오늘도 스마트한 칼퇴 하세요.
— yerin0n_off