VS Code에서 API 키 적용하기 환경 변수와 설정 안내

준비 환경과 파일 위치

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인 경우에는 사용자 settings.json에 키를 직접 작성하는 방식을 지양합니다.

복사 가능한 최소 명령 또는 코드 예제

프로젝트 내에서 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) + '...');

실행 순서 5단계 이상과 예상 출력

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. ShortKey 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 오류가 발생하면, 환경 변수를 설정하기 전에 열려 있던 기존 터미널 세션을 유지하고 있는지 확인합니다. VS Code의 통합 터미널은 터미널이 생성되는 시점의 환경 변수만 로드하므로, settings.json 수정 후에는 반드시 Terminal 메뉴에서 New Terminal을 실행하여 새 세션을 생성합니다.

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

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

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

장비 및 입력 환경 문제로 특정 단축키 입력이 동작하지 않을 때에는 '준비물·장비 선택 기준' 소제목에서 요구되는 운영체제별 키보드 입력 조건 및 대체 메뉴 경로를 확인합니다.

준비물·장비 선택 기준

VS Code 단축키 및 명령 팔레트를 조작할 때 레이아웃 표준을 지원하는 기본 키보드 장비가 필요합니다. 특정 가스켓 구조나 영문 전용 레이아웃을 사용하더라도 OS 상의 입력 언어 설정이 단축키 매핑과 호환되는지 점검합니다.

가상 키보드나 소프트웨어 입력기를 사용하는 환경에서는 Ctrl+Shift+P 또는 Cmd+Shift+P 조합 키 조합이 다른 프로그램의 핫키와 충돌할 수 있습니다. 키보드 장비 변경 없이 조작할 때는 VS Code 상단 메뉴의 View > Command Palette 경로를 마우스로 직접 클릭하여 명령 창을 호출합니다.

별도의 물리 키보드나 특수 장비를 추가 구매할 필요는 없으며 OS 기본 입력기가 설치된 환경이면 충분합니다. 시스템 단축키 충돌이 우려되는 경우에는 VS Code 설정 메뉴에서 Keyboard Shortcuts 항목을 찾아 해당 명령의 단축키 지정을 변경합니다.