Next.js 프리뷰 배포에서 환경변수 불일치 줄이는 운영 체크리스트

지난분기 금요일 밤에 실제로 겪은 일이 하나 있습니다. 프리뷰에서는 멀쩡하던 결제 직전 검증 API가 프로덕션에서만 401을 뱉었습니다. 처음엔 코드 롤백 얘기가 바로 나왔는데, 로그를 따라가 보니 원인은 단순했습니다. NEXT_PUBLIC_API_BASE_URL은 새 도메인을 보고 있었고, 서버 런타임에서 읽는 시크릿은 이전 프로젝트의 키를 잡고 있었습니다. 겉으로 보기엔 “환경변수 하나 틀림” 같은 사건이지만, 본질은 누가 어떤 시점에 어떤 값을 주입하는지 팀이 합의하지 않았다는 데 있었습니다. Next.js에서는 이 차이가 특히 크게 드러납니다. 브라우저 번들에 박히는 값과 서버가 기동 시 읽는 값이 섞이기 시작하면, 테스트 통과 여부가 사실상 운에 가까워집니다.

그 뒤로 팀에서 제일 먼저 바꾼 건 문서가 아니라 용어였습니다. 모든 변수를 빌드 시점, 서버 런타임, 클라이언트 노출 셋 중 하나로만 분류하고, 분류가 빠진 PR은 리뷰에서 바로 반려했습니다. 처음엔 “이 정도까지?”라는 반응도 있었는데, 두 주 지나니 오히려 배포 속도가 빨라졌습니다. 논쟁이 줄었기 때문입니다. 어디서 깨졌을 때도 대화가 빨라집니다. “로그인 이상해요” 대신 “프로덕션 런타임 시크릿과 프리뷰 값이 어긋난 것 같다”처럼 바로 조사 범위를 좁힐 수 있습니다. 이건 화려한 도구보다 훨씬 현실적인 개선이었습니다.

실무에서 효과가 컸던 절차는 아래 여섯 가지입니다. env.schema에 필수 키와 형식을 선언하고, CI에서 누락과 타입 오류를 실패로 처리합니다. 프리뷰 배포 직전에 실제 주입된 키 목록을 덤프해서 스키마와 비교합니다. 프로덕션 승격 전에는 프리뷰와 프로덕션 차이를 허용 목록 기반으로만 통과시킵니다. 서버 전용 키는 부팅 단계에서 즉시 검증하고, NEXT_PUBLIC_*는 빌드 단계에서만 검증합니다. 배포 후 10분 동안 로그인, 결제, 외부 API 호출 같은 핵심 경로 synthetic check를 자동으로 돌립니다. 마지막으로 실패율이 기준치를 넘으면 사람 승인 없이 롤백합니다. 핵심은 “운영자가 콘솔을 눈으로 확인하는 단계”를 없애는 겁니다. 그 단계가 남아 있으면 야간 배포에서 언젠가 반드시 놓칩니다.

주의할 점도 분명합니다. 긴급하다고 콘솔에서 값을 직접 고치고 이력을 남기지 않으면, 다음 배포에서 같은 문제가 더 큰 형태로 돌아옵니다. 시크릿 변경과 코드 변경을 한 PR에 묶는 습관도 위험합니다. 원인 분리가 어려워집니다. 또 환경을 팀별로 너무 많이 쪼개면 비교 자체가 무의미해집니다. 이름만 같은 “프리뷰”가 여러 개 생기고, 실제로는 의존 서비스 버전도 다르기 때문입니다. 저희는 예외 환경을 늘리기보다 공통 템플릿 하나를 유지하고, 꼭 필요한 예외값은 만료일이 있는 임시 키로 운영합니다. 불편해 보여도 사고가 줄어듭니다.

배포 당일에 실제로 쓰는 3분 점검도 공유하겠습니다. 첫째, 이번 릴리스에서 추가/삭제된 환경변수 키를 한 줄로 읽어 봅니다. 둘째, 프로덕션 기준으로 바뀐 값이 “의도된 변경”인지 담당자가 음성으로 다시 확인합니다. 셋째, 배포 후 첫 실패 요청의 로그에서 request_id, 릴리스 버전, 환경명을 바로 확인합니다. 이 세 가지만 습관화해도 “어디부터 봐야 하지?”라는 공백 시간이 크게 줄어듭니다. 결국 장애 복구 시간의 절반은 기술 난이도보다 초기 방향 설정에서 갈리더군요.

정리하면, 환경변수 문제는 설정 실수가 아니라 운영 설계 문제에 가깝습니다. “누가 바꿨나”를 추궁하는 회고는 다음 사고를 못 막습니다. 대신 어떤 검증이 비어 있었는지, 왜 자동으로 걸러지지 않았는지를 남겨야 합니다. 이 기준으로만 회고를 두 번 해도 체감이 옵니다. 프리뷰에서는 되는데 프로덕션에서만 깨지는 사건이 확실히 줄어듭니다. Next.js 프로젝트를 오래 운영할수록, 환경변수는 코드 옆에 붙은 부가정보가 아니라 배포 신뢰도를 결정하는 핵심 자산이라는 말을 자주 하게 됩니다.