로컬에서 테스트했는데 운영 설정이 바뀐다면? Flagship의 두 기본값을 보세요

Cloudflare Flagship을 쓰는 개발팀이라면 ‘로컬에서 실행한다’는 말만으로 운영 환경과 분리됐다고 판단해서는 안 됩니다. 로컬 개발 중 플래그를 읽어 판단하는 동작은 로컬 저장소를 쓰지만, CLI로 플래그를 바꾸는 명령은 여전히 원격 앱이 기본 대상입니다. 그 원격 앱이 운영용이라면 실제 운영 설정을 바꿀 수 있으므로, 조회와 변경 명령의 대상을 각각 확인해야 합니다.

기능을 켜고 끄는 기준을, 내 컴퓨터에서 시험합니다

현재 공식 문서에서 베타로 안내하는 Flagship은 기능 플래그를 다루는 서비스입니다. 기능 플래그는 코드를 다시 배포하지 않고 특정 기능의 활성화 여부 등을 결정하는 설정입니다. 예를 들어 새 화면을 표시할지 판단하는 코드가 플래그 값을 읽을 수 있습니다.

Cloudflare의 11월 2일 공지에 따르면 로컬 개발의 Flagship 바인딩은 원격 앱을 호출하는 대신 로컬 플래그 저장소를 사용합니다. 인터넷 연결 없이 개발하거나 운영 플래그를 건드리지 않고 값을 시험할 수 있도록 한 변화입니다.

다만 로컬 저장소는 비어 있는 상태로 시작합니다. 플래그를 넣기 전에는 코드에서 지정한 기본값이 반환됩니다. 로컬 화면이 예상과 다르다고 해서 곧바로 운영 설정이 잘못됐다고 볼 수 없는 이유입니다.

‘평가’는 로컬, ‘변경 명령’은 원격이 기본입니다

이번 변화에서 놓치기 쉬운 부분은 CLI입니다. 공식 설정 문서는 플래그 명령의 기본 대상이 여전히 원격 앱이라고 명시합니다. 로컬 플래그를 만들거나 수정하려면 해당 명령에 --local을 붙여야 합니다.

예를 들어 새 화면을 켜는 플래그를 로컬에서 읽고 있었다고 해도, 뒤이어 실행하는 플래그 수정 명령까지 자동으로 로컬 대상이 되는 것은 아닙니다. 두 동작은 서로 다른 기본값을 가집니다.

따라서 팀의 실행 안내에는 ‘로컬 개발 서버를 켠다’는 설명만 적기보다, 설정을 읽는 경로와 변경 명령의 대상을 각각 명시하는 편이 좋습니다. AI 코딩 도구에 명령을 맡길 때도 실행 전에 앱과 대상 환경을 확인해야 합니다.

운영 값을 자동으로 가져오는 것은 아닙니다

원격 앱의 플래그를 로컬 저장소로 복사하는 pull 기능은 제공되지만, 자동으로 가져오지는 않습니다. 로컬에서 바꾼 값이 덮어써지지 않도록 의도적으로 나눈 동작입니다.

또한 도구가 서로 다른 저장 디렉터리를 사용하면 같은 플래그를 보고 있다고 착각할 수 있습니다. 공식 문서는 --persist-to로 개발 서버와 같은 디렉터리를 지정하는 방법을 안내합니다. 복사한 뒤 값이 보이지 않는다면 플래그 이름뿐 아니라 저장 위치도 확인할 필요가 있습니다.

원격 앱을 대상으로 평가하려면 바인딩에 remote: true를 설정할 수 있습니다. 이 설정을 사용하는 경우에는 ‘로컬 실행’과 ‘로컬 데이터 사용’을 같은 의미로 취급하면 안 됩니다.

버전과 대상 환경을 함께 기록하세요

로컬 플래그 저장소는 Wrangler 4.135.0 또는 Cloudflare Vite 플러그인 1.56.0 이상이 필요합니다. Local Explorer에서 Flagship을 다루는 기능은 각각 4.148.0 또는 1.63.0 이상이 필요하므로 두 기준을 혼동하지 않아야 합니다.

지금 확인할 것은 세 가지입니다. 사용하는 도구 버전, 바인딩의 로컬·원격 설정, 변경 명령의 --local 유무입니다. 로컬 값이 비어 있을 때 반환되는 기본값도 함께 시험하세요.

이번 변화는 운영 환경과 분리된 시험을 돕지만, 모든 명령의 대상을 알아서 바꾸는 보호 장치는 아닙니다. 어디에서 실행하는지와 어디의 설정을 바꾸는지는 따로 확인해야 합니다.