Next.js 환경변수 공개 검사표: 접두사와 빌드 시점을 함께 보는 이유
Next.js 환경변수는 기본적으로 서버 전용이지만, NEXT_PUBLIC_ 접두사가 붙은 값은 빌드 시점에 브라우저 JavaScript에 포함될 수 있습니다. 공개 여부를 판단하려면 변수 이름과 사용 위치를 살핀 뒤, 실제 비밀값 대신 가짜 표식을 넣은 검사본에서 브라우저로 전달된 내용을 확인하는 방식이 유용합니다. 실행 환경의 값만 바꿔서는 이미 빌드에 들어간 값이 자동으로 바뀌지 않습니다.
이번 영수증은 실행 결과가 아니라 문서의 경계다
검토 기준일은 2026-09-09, 근거 묶음의 검토 시각은 같은 날 09:20:58 KST입니다. 이 글은 공식 환경변수 문서에 근거한 필드 테스트 설계입니다. 운영 서비스를 검사했거나 고객 설치에 성공했다는 보고서는 아닙니다.
조건도 분명합니다. 아래 예시는 Next.js의 문서상 동작을 기준으로 하며, 실제 적용에는 프로젝트 설정과 실행 환경 확인이 필요합니다. 호환 도구라는 설명만으로 같은 결과를 전제할 수는 없습니다.
요약은 다음과 같습니다.
- 환경변수는 기본적으로 서버 전용입니다.
NEXT_PUBLIC_값은 빌드 때 브라우저 코드에 포함될 수 있습니다.- 이미 포함된 값은 실행 환경만 바꾼다고 자동 갱신되지 않습니다.
이름은 출발점이고, 도착지는 브라우저다
저는 공개 변수 검사표에서 공개해도 되는 값인지와 실제로 전달됐는지를 별도 항목으로 둡니다. 접두사는 프레임워크의 처리 방식을 설명하지만, 애플리케이션이 값을 어디에 사용하는지까지 대신 설명하지는 않기 때문입니다.
예를 들어 서버 전용으로 의도한 값을 화면 출력이나 응답에 넣는 코드가 있는지는 별도로 검토할 대상입니다. 이는 이번에 발견한 유출 사례가 아니라, 접두사 검사만으로 검토를 끝내지 않기 위한 확인 항목입니다.
반대로 공개 변수라는 이름만 보고 해당 값이 모든 페이지에 반드시 들어간다고 단정하지도 않습니다. 실제 사용 코드와 브라우저에 전달되는 결과가 판단 근거입니다.
공개 변수의 이름을 찾는 일과 브라우저에 도착한 값을 확인하는 일은 서로 다른 검사입니다.
비밀값 대신 명백한 가짜 표식을 넣는다
가상 예시는 ‘편의점 행사 안내 앱’입니다. 별도 검사본에 아래 값을 둔다는 가정이며, 실제로 실행하거나 관찰한 결과는 아닙니다.
| 용도 | 가상 변수와 값 | 확인하려는 질문 |
|---|---|---|
| 공개 표시용 | NEXT_PUBLIC_NOTICE_MARKER=FAKE_PUBLIC_BUILD_MARKER | 클라이언트에서 사용하는 표식이 브라우저 결과에 나타나는가 |
| 서버 전용 비교용 | PRIVATE_CHECK_MARKER=FAKE_SERVER_ONLY_MARKER | 서버에만 남도록 의도한 표식이 브라우저로 전달되는가 |
| 변경 비교용 | 공개 표시용 값을 FAKE_PUBLIC_CHANGED_MARKER로 변경 | 재빌드 여부에 따라 어떤 표식이 전달되는가 |
표식은 인증 기능이 전혀 없는 문자열입니다. 실제 키 일부를 잘라 쓰거나 실제 비밀값과 닮게 만들 이유도 없습니다. 검사 기록과 화면을 남길 때 가짜 값임이 바로 읽히는 편이 좋습니다.
검증 과정은 변수 선언, 참조 코드, 빌드 결과, 브라우저 전달 내용을 연결합니다. 검사본에서 공개 표식을 클라이언트 코드가 직접 참조하도록 구성하고, 빌드 당시 값을 기록합니다. 이후 브라우저 개발자 도구에서 전달된 JavaScript와 문서·응답 내용을 확인하는 방식입니다.
저라면 파일 이름이나 변수 이름만 검색한 결과와 표식 문자열 자체를 찾은 결과를 나눠 적겠습니다. 무엇을 검색했는지 불분명하면, ‘못 찾았다’는 기록도 해석하기 어렵습니다.
비교 도식 캡션: 가짜 공개 표식이 빌드를 거쳐 브라우저 JavaScript로 전달되는 경로와 서버 전용 표식의 확인 지점. 실제 검사 결과가 아닌 점검용 도식.
값을 바꿨는데 화면이 그대로일 때
공식 문서에서 도입 검토에 바로 영향을 주는 부분은 빌드 시점입니다. 공개 변수가 브라우저 코드에 인라인됐다면, 그 값은 만들어진 결과물에 들어 있습니다.
따라서 같은 결과물을 둔 채 실행 환경의 공개 변수만 바꾸는 조건과, 변경된 값을 제공하고 다시 빌드하는 조건을 구분해야 합니다. 전자의 화면이 그대로라는 이유만으로 환경변수 설정 전체가 실패했다고 판단할 수는 없습니다.
다만 후자에서도 새 값이 보일 것이라고 무조건 보장하지는 않습니다. 실제로 해당 값을 참조하는지, 어떤 결과물을 실행했는지, 사용 중인 도구가 어떤 동작을 지원하는지 확인이 남습니다.
공개 값의 변경 여부를 판단하려면 실행 환경의 값뿐 아니라 빌드 당시의 값도 기록해야 합니다.
복사해서 쓰는 공개 변수 검사표
아래 표는 소스 도입 검토 메모에 그대로 옮길 수 있는 산출물입니다. 결과 칸에는 관찰한 내용만 적고, 확인하지 못한 항목은 미확인으로 남기는 구성이 좋겠습니다.
| 검사 항목 | 남길 근거 | 판단 기준 |
|---|---|---|
| 공개 가능성 | 변수의 용도와 공개 허용 여부 | 비밀 유지가 필요한 값은 공개 변수로 취급하지 않음 |
| 접두사 | 변수 이름 | NEXT_PUBLIC_라면 빌드 시 공개 포함 가능성 검토 |
| 사용 위치 | 참조 코드와 출력 경로 | 서버 사용과 브라우저 전달을 구분 |
| 빌드 조건 | 빌드 당시 가짜 표식 | 실행 시점 값과 혼동하지 않음 |
| 전달 결과 | 확인한 JavaScript·문서·응답 | 표식 발견 여부와 확인 범위를 함께 기록 |
| 변경 조건 | 재빌드 여부와 실행한 결과물 | 실행 환경 변경과 빌드 변경을 구분 |
| 적용 범위 | 실제 런타임·설정·설치 문서 | 호환이라는 표현만으로 동일 동작을 확정하지 않음 |
찾지 못했다는 결과에도 범위가 있다
가짜 서버 표식이 브라우저에서 발견된다면, 의도와 다른 전달 경로를 살필 근거가 됩니다. 그렇다고 실제 비밀값 유출이 발생했다고 쓰지는 않습니다. 이번 예시는 가짜 값으로 경로를 확인하는 설계이기 때문입니다.
반대로 표식을 찾지 못해도 전체 서비스의 안전을 증명한 것은 아닙니다. 확인하지 않은 페이지나 응답이 있을 수 있고, 검사 코드가 해당 변수를 사용하지 않았을 수도 있습니다. 기록은 ‘확인한 범위에서 미발견’까지가 정직합니다.
소스 도입 판단은 설치 조건까지 이어진다
최종 판단 기준은 접두사의 유무만이 아닙니다. 공개 허용 여부, 참조 위치, 빌드 시점, 브라우저 전달 결과를 연결해서 설명할 수 있는지가 핵심입니다. 이 검사에는 상품 구매가 필요하지 않습니다.
선택적 도입 사례인 사주 웹앱 소스 라이선스도 같은 경계에서 볼 수 있습니다. 한 프로젝트용 소스라는 설명이 모든 Next.js 런타임과의 호환성을 뜻하지는 않습니다. 관련 소스를 검토 중이라면 현재 제공 범위와 설치 조건 확인하기가 다음 판단 지점입니다.
이어지는 기록
Next.js 환경변수의 공개 여부는 접두사·사용 위치·빌드 시점·브라우저 전달 결과를 함께 기록해야 판단할 수 있습니다.
재사용 체크리스트.
- 입력과 기대 결과를 적어요.
- 출처·불확실성·사람 검토 항목을 표시해요.
- 수동 대안과 중단 기준을 남겨요.