NEXT_PUBLIC_API_BASE_URL을 바꾼 뒤 같은 빌드 파일을 실행한다고 하자. 서버 프로세스의 새 환경값이 정상이어도 브라우저는 이전 주소를 사용할 수 있다. 브라우저가 읽는 값이 이미 JavaScript에 들어갔기 때문이다.

이 글의 질문은 바뀐 환경값이 새 브라우저 산출물을 만드는 입력으로 사용됐는가다. Turborepo에서 Next.js를 빌드하는 구성을 기준으로 값 전달과 빌드 치환, 캐시 복원을 분리한다.

process.env가 읽히는 시점을 먼저 찾는다

다음처럼 정적으로 참조한 공개 변수는 Next.js가 next build 시점 값으로 브라우저 번들에 포함한다.

const apiBaseUrl = process.env.NEXT_PUBLIC_API_BASE_URL;

빌드 뒤 실행 서버의 값을 바꿔도 이 상수는 다시 치환되지 않는다. 동적 변수명 참조는 같은 방식으로 inline되지 않으므로 코드의 읽기 방식도 확인한다. 환경별로 빌드할지, 동일 산출물을 승격하고 별도 API로 런타임 공개 설정을 제공할지 먼저 정한다. Next.js의 공개 변수와 런타임 변수가 이 구분을 설명한다.

값은 CI → Turbo 작업 프로세스 → 프레임워크 빌드 → 산출물 → 실행 서버·브라우저를 지난다. CI에 값이 있는지, 작업이 받았는지, 빌드가 읽었는지, 새 파일이 배포됐는지는 각각 확인해야 한다.

전달되는 값과 해시에 들어가는 값은 다르다

빌드 결과를 바꾸는 환경값은 캐시 해시에도 반영돼야 한다. Turborepo의 env는 해당 작업의 값을, globalEnv는 모든 작업의 값을 해시에 반영한다. 반면 passthrough 설정은 값을 전달하지만 변경을 해시에 포함하지 않는다. Turborepo 환경변수 설정을 사용하는 버전과 대조한다.

{
  "$schema": "https://turborepo.dev/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "env": ["NEXT_PUBLIC_API_BASE_URL", "BUILD_ENV"],
      "outputs": [".next/**", "!.next/cache/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

예제에서는 API 주소와 빌드 환경을 build 입력으로 선언한다. 출력 경로는 실제 Next.js 버전과 빌드 모드에 맞춰 조정한다. 모든 변수를 전역으로 넣으면 무관한 작업도 캐시를 잃으므로 결과를 바꾸는 작업에 좁혀 선언한다.

strict 환경 모드는 선언하지 않은 변수를 필터링한다. 프레임워크 추론이나 passthrough가 관여할 수 있어 설정에 변수 이름이 없다는 사실만으로 누락을 확정하지 않는다. 런타임 비밀키를 공개 변수로 바꾸는 방법은 전달 문제를 해결하는 선택지가 아니다.

환경값이 작업에 전달된 뒤 해시에 반영되는지에 따라 새 빌드 또는 이전 산출물 재사용으로 나뉘는 흐름

그림은 값 전달이 성공한 뒤에도 캐시 입력이 빠질 수 있는 경우를 보여준다. 해시가 달라졌는지와 브라우저 결과가 바뀌었는지를 이어서 확인해야 한다.

세 비교로 조사 범위를 줄인다

첫 비교는 작업 안의 값 존재 여부다. 비밀값을 출력하지 않고 필요한 변수의 존재와 비민감 환경 식별자를 확인한다. Turbo·Next.js 버전, 환경 모드와 작업 디렉터리도 남긴다.

두 번째는 API 주소만 바꾼 두 빌드의 작업 해시와 cache hit 여부다. run summary에서 같은 입력 조건을 비교한다. 해시가 같으면 누락된 입력을 조사하고, 해시가 다르면 값 로딩 경로와 산출물부터 확인한다.

세 번째는 캐시를 우회한 빌드와 정상 빌드의 결과다. 강제 실행에서만 새 주소가 나오면 캐시 입력·출력의 단서가 된다. 강제 실행도 같으면 .env 로딩 우선순위나 실제 앱 디렉터리를 본다. 이 비교는 진단이며 캐시를 영구적으로 끄는 결론은 아니다.

서버의 새 파일이 확인돼도 CDN이나 서비스 워커가 이전 파일을 전달할 수 있다. 빌드 ID와 브라우저가 받은 파일·네트워크 주소를 함께 연결하면 빌드 이후 경계도 구분할 수 있다.

환경값 다음에는 파일 입력과 출력도 확인한다

루트 설정과 코드 생성 입력도 결과를 바꾼다면 해시에 들어가야 한다. 반대로 outputs를 선언하지 않으면 작업 로그는 복원돼도 필요한 파일은 캐시에서 복원되지 않는다. Turbo 캐시의 입력·출력을 기준으로 실제 빌드 계약을 적는다.

이 접근은 공개 설정이 빌드 결과에 포함되는 서비스에서 유효하다. 다음 점검에서는 서버 환경값보다 먼저 값을 읽는 시점과 작업 해시를 확인한다. 런타임 설정이 필요한 구조라면 환경마다 다시 빌드하는 비용과 공개 설정을 제공하는 별도 경로를 비교해 선택한다.