VS Code API 키 설정: .env·settings.json 환경 변수 등록

저장 위치별 비교

VS Code에서 API 키를 프로젝트 단위로 관리하려면 프로젝트 루트 디렉터리의 .env 파일을 사용합니다. 모든 프로젝트에 공통으로 적용해야 하는 경우에는 사용자 설정 파일인 settings.json을 사용합니다.

설정 방식별 저장 위치, 적용 대상, 보안 위험을 비교한 표입니다.

운영체제별 사용자 settings.json 기본 저장 경로는 다음과 같습니다. Windows는 %APPDATA%\Code\User\settings.json, macOS는 ~/Library/Application Support/Code/User/settings.json, Linux는 ~/.config/Code/User/settings.json 경로를 사용합니다.

단순 테스트 목적인 경우에는 프로젝트 .env 방식을 사용하고, 시스템 전체 연동이 필요한 경우에는 OS 환경 변수 방식을 사용합니다. 개인 PC가 아닌 공용 PC라면 사용자 settings.json에 키를 직접 작성하지 않아야 합니다.

.env와 .gitignore 최소 설정 코드

프로젝트에서 API 키를 호출하려면 .env 파일 설정과 .gitignore 제외 설정을 함께 진행해야 합니다. 다음은 Node.js 환경에서 dotenv 패키지로 환경 변수를 불러오는 최소 구현 코드입니다.

# .env 파일 예시

OPENAI_API_KEY="sk-proj-example-key-value"
API_REQUEST_TIMEOUT="5000"

# .gitignore 파일 예시

.env
.env.local
*.pem

// app.js 실행 예시
require('dotenv').config();

const apiKey = process.env.OPENAI_API_KEY;
if (!apiKey) {
  console.error('오류: OPENAI_API_KEY 환경 변수가 설정되지 않았습니다.');
  process.exit(1);
}
console.log('API 키 로드 성공:', apiKey.substring(0, 7) + '...');

키 등록과 확인 절차

VS Code의 탐색기, 설정 창, 통합 터미널에서 API 키를 등록하고 확인하는 순서입니다.

1. VS Code 메뉴에서 File > Open Folder를 클릭하여 작업할 프로젝트 폴더를 열고, Explorer 창에서 .env 파일을 생성합니다.
2. 생성한 .env 파일 내부에 API_KEY=your_actual_key_here 형태로 변수명과 키 값을 입력하고 저장합니다.
3. Explorer 창에서 .gitignore 파일을 생성하거나 연 뒤, 내용에 .env를 추가하여 Git 추적 대상에서 제외합니다.
4. 단축키 Ctrl+Shift+P (macOS는 Cmd+Shift+P)를 눌러 Command Palette를 연 후 Preferences: Open User Settings (JSON)을 선택합니다.
5. settings.json 파일에 "terminal.integrated.env.windows": { "MY_API_KEY": "your_actual_key_here" } 구문을 추가하고 저장합니다.
6. VS Code 상단 메뉴에서 Terminal > New Terminal을 선택하여 터미널을 새로 열고, echo %MY_API_KEY% (Windows cmd) 또는 echo $MY_API_KEY (Bash/zsh) 명령을 실행하여 설정 값을 확인합니다.

터미널 화면에 설정한 your_actual_key_here 값이 출력되면 환경 변수 적용이 완료된 것입니다.

소스 코드와 공개 저장소의 제외 항목

소스 코드 파일(.js, .py, .java 등)에는 API 키 문자열을 직접 하드코딩하지 않습니다. 소스 코드에 실제 키 값이 포함된 상태로 Git commit을 실행하면 버전 관리 이력에 영구적으로 남아 유출될 수 있습니다.

공개 저장소(GitHub, GitLab 등)에 코드를 푸시할 때는 .env 파일, 개인 인증서 파일(.pem, .p12), 로컬 데이터베이스 접속 암호를 저장소 추적 목록에서 제외해야 합니다. 이를 위해 .gitignore 파일에 관련 확장자와 파일명을 명시합니다.

조직 계정을 사용하는 경우에는 관리자 콘솔 정책에 따라 터미널 환경 변수 주입이 제한될 수 있습니다. 회사 기밀 데이터를 외부 AI 모델 API로 전송해야 한다면 보안 담당자의 사전 승인을 받은 뒤 전송 범위 조건을 검토해야 합니다.

undefined 오류와 .env 인식 실패의 원인과 조치

환경 변수를 설정했는데도 프로그램 실행 시 undefined 오류가 발생하면, 설정 전에 열려 있던 기존 터미널 세션을 그대로 사용하고 있는지 확인합니다. VS Code 통합 터미널은 터미널이 생성되는 시점의 환경 변수만 불러오므로, settings.json을 수정한 뒤에는 반드시 Terminal 메뉴에서 New Terminal을 실행해 새 세션을 만들어야 합니다.

.env 파일의 값을 인식하지 못하는 경우에는 실행 스크립트의 위치와 .env 파일의 위치가 일치하는지 확인합니다. 프로젝트 루트가 아닌 하위 디렉터리에서 스크립트를 실행하면 dotenv 라이브러리가 파일 경로를 찾지 못할 수 있습니다.

Git 저장소에 .env 파일이 이미 올라간 경우에는 .gitignore에 뒤늦게 등록해도 추적이 중단되지 않습니다. 이때는 터미널에서 git rm --cached .env 명령을 실행해 Git Index에서 파일 추적을 제거한 후 commit을 수행합니다.

이미 유출된 API 키는 해당 서비스 제공자 콘솔에 접속해 즉시 폐기하고 재발급받아야 합니다. 공식 지원이나 커뮤니티 문의가 필요한 경우에는 실제 API 키 문자열을 마스킹 처리한 뒤 설정 구조만 공유합니다.

단축키가 동작하지 않는 경우에는 VS Code 상단 메뉴의 View > Command Palette를 마우스로 직접 열어 같은 명령을 실행하는 것이 대안입니다.