개발 기본
환경변수(Environment Variable)
환경변수는 프로그램에 필요한 API 키나 서버 주소 등을 코드 밖에서 이름과 값으로 전달하는 설정입니다.
쉬운 설명
앱에는 코드뿐 아니라 연결할 서버 주소나 API 키 같은 설정도 필요해요. 환경변수는 이런 값을 코드에 직접 적는 대신, 프로그램이 이름으로 찾아 읽게 하는 설정이에요. 같은 코드라도 내 컴퓨터와 배포한 서버에서 서로 다른 값을 쓸 수 있어요. 다만 환경변수에 넣었다는 이유만으로 비밀값이 자동으로 보호되지는 않아요.
이런 상황에서 만나요
AI와 함께 만든 회의록 요약 앱이 내 컴퓨터에서는 되는데, 공유한 사이트에서는 실패했어요. AI가 ‘배포한 서버에도 AI_API_KEY 환경변수가 있는지 확인해 보세요’라고 안내할 수 있어요. 이때 앱을 배포한 곳의 설정 화면을 열어 봅니다.
AI_API_KEY배포한 앱의 서버
내 컴퓨터의 설정과 별도로 확인- 1이름: 코드에서 읽는 이름을 그대로 넣습니다. AI_API_KEY는 이 앱을 가정한 예시입니다.
- 2값: 연결할 서비스에서 받은 값을 넣는 자리입니다. 여기서는 비밀값 대신 가림 표시를 사용했습니다.
- 3적용할 곳: 내 컴퓨터가 아닌, 사람들이 접속할 앱의 서버에 설정하는지 확인합니다.
AI에게 확인을 요청할 때는 ‘내 컴퓨터에서는 요약이 되는데 배포한 사이트에서만 실패해요. 서버에 AI_API_KEY라는 이름으로 설정했어요’처럼 증상과 설정 이름을 알려 주세요. 키 원문을 보내는 대신 값이 비어 있는지, 이름이 일치하는지 확인하면 됩니다. 환경변수가 제대로 설정되어 있다면 오류 메시지를 바탕으로 다른 원인을 살펴봅니다.
헷갈리기 쉬운 점
.env 파일에 넣었는데, 배포한 앱에서는 왜 못 읽나요?
내 컴퓨터의 .env 파일과 배포 서버의 설정은 별도로 관리되는 경우가 많습니다. 내 컴퓨터에 값이 있어도 배포한 곳에 자동으로 등록됐다고 볼 수는 없습니다. 코드가 읽는 변수 이름과 배포 설정의 이름이 같은지, 실제로 사용하는 환경에 값이 있는지 확인합니다. 값을 바꾼 뒤에는 도구에 따라 재시작이나 재배포가 필요할 수 있습니다.
환경변수는 값을 숨겨 주는 기능 자체가 아닙니다. 브라우저에 전달되는 변수에 비밀 API 키를 넣으면 방문자에게 노출될 수 있습니다. 비밀값이 든 .env 파일은 Git에 올리지 않고, 값을 확인하려고 키 전체를 로그나 AI 대화에 붙여 넣지 않습니다.
왜 알아야 할까요?
설정 누락은 코드 수정만으로 해결되지 않을 수 있습니다. 어느 환경에서 실패하는지와 어떤 이름의 설정이 필요한지를 알면, AI에게 비밀값을 보여 주지 않고도 문제를 구체적으로 설명할 수 있습니다.
조금 더 자세히
APP_ENV=development라는 예시에서 APP_ENV는 이름이고 development는 값입니다. 프로그램에 APP_ENV를 읽는 코드가 있어야 이 설정을 사용할 수 있습니다. 변수 이름은 프로젝트가 정해 둔 이름을 따르며, 이름을 비슷하게 바꾸면 다른 설정으로 취급될 수 있습니다.
.env는 이름과 값을 모아 적는 파일입니다. 파일이 존재한다고 모든 프로그램이 자동으로 읽는 것은 아닙니다. 사용하는 프레임워크가 읽어 주거나, 실행할 때 파일을 불러오도록 설정해야 합니다. 배포 서비스에서는 파일 대신 설정 화면에서 값을 등록하기도 합니다.
설정이 반영되는 시점도 다릅니다. 빌드할 때 코드에 들어가는 값은 결과물을 다시 만들어 배포해야 바뀝니다. 서버가 시작할 때 읽는 값은 재시작이 필요할 수 있습니다. 설정을 바꿨는데 동작이 그대로라면 사용 중인 도구의 반영 방법을 확인합니다.
환경변수에는 공개해도 되는 값도 있습니다. 예를 들어 Vite의 기본 설정에서 VITE_로 시작하는 변수는 브라우저용 코드에 포함됩니다. 비밀 키를 그런 변수에 넣으면 안 됩니다. 변수의 이름과 공개 범위를 확인하고, 비밀 키는 서버에서만 읽도록 구성합니다.
직접 사용할 때 확인해 보세요
- 코드가 읽는 변수 이름과 설정한 이름이 일치하는지 확인한다
- 내 컴퓨터와 배포한 서버 중 어디에서 값이 필요한지 확인한다
- 값을 바꾼 뒤 필요한 재시작이나 재배포를 진행한다
- 비밀값이 브라우저 코드·Git·로그에 남지 않는지 확인한다
관계 지도
