LAB작은 아이디어를 직접 만들어 봅니다.

LAB 6개 중Mapbox 지도 예제02
서울특별시 금천구

Mapbox 지도 예제.

스트리트와 위성, 두 장의 지도를 한 화면에서 비교합니다.

Mapbox GL JS 3D 건물 지도
금천구 지도를 불러오고 있어요건물과 위성 지도를 준비합니다.

드래그로 이동, 휠로 확대, 가운데 선을 끌어 지도 비교, 바람 비 눈 선택

마우스: 드래그로 지도를 옮기고, 오른쪽 버튼이나 Ctrl을 누른 채 드래그하면 회전과 기울기가 바뀝니다. 휠로 확대하고 축소합니다. 터치: 한 손가락으로는 페이지가 스크롤되고, 두 손가락으로 지도를 옮기고 확대합니다. 비교선: 가운데 선을 좌우로 끌면 스트리트와 위성 지도의 경계가 움직입니다. 키보드로는 선을 선택한 뒤 좌우 방향키를 씁니다. 기상 효과: 오른쪽 위의 바람, 비, 눈 버튼을 각각 켜고 끌 수 있고, 여러 개를 함께 켤 수도 있습니다.
MAP DATA

금천구 건물 17,042채와 행정동 경계 GeoJSON을 사용한 데모입니다. 지도 위 아이콘 45개는 임의 위치에 둔 목업이며, 건물 높이는 데이터의 HEIGHT 값(m)입니다. 바람은 무작위로 만든 샘플 값을 입자로 보여 주며, 실제 풍속을 미터 단위로 환산해 30배 빠르게 재생합니다. 비와 눈은 기본 강도로 표현한 효과입니다. 지도 © Mapbox © OpenStreetMap 기여자.

만든 이유와 과정

이 기술로 무엇을 할 수 있을지 먼저 적고, 이어서 두 장의 지도를 겹쳐 비교하고 날씨 효과를 얹기까지의 과정을 실제 코드와 함께 적었습니다.

1. 지도 위에 데이터를 얹으면 무엇을 할 수 있을까요

Mapbox GL JS 같은 지도 플랫폼의 강점은 지도의 기본기를 맡아 준다는 점입니다. 타일, 스타일, 카메라, 라벨은 플랫폼이 처리하고, 개발자는 그 위에 자기 데이터를 레이어로 얹는 일에 집중할 수 있습니다. 건물 높이, 시설 위치, 날씨처럼 위치를 가진 데이터라면 무엇이든 지도 위에서 한눈에 보여 줄 수 있습니다.

제가 떠올린 쓰임은 이런 것들입니다. 도시의 시설 상태를 지도 위에 띄우는 관제 화면, 개발 전후나 위성 사진과 일반 지도를 나란히 놓는 비교 화면, 배송 차량이나 매장 위치를 보여 주는 현황판, 비나 바람 같은 기상 정보를 겹쳐 보는 상황판입니다.

이 페이지에서는 그런 화면에 자주 나올 만한 기능 세 가지를 하나씩 만들어 봤습니다. 지도 두 장을 겹쳐 비교하기, 건물을 높이만큼 세우기, 날씨를 효과로 덮기입니다. 플랫폼이 어디까지 대신해 주고 어디부터 직접 해야 하는지 보는 게 목표였습니다.

2. 만든 것과 Mapbox를 쓰는 이유

이 페이지는 금천구를 대상으로 한 Mapbox GL JS 예제입니다. 같은 자리에 스트리트 지도와 위성 지도를 겹쳐 놓고 가운데 선을 끌어 비교하고, 건물 17,042채를 높이만큼 입체로 세웠고, 바람과 비와 눈을 효과로 켤 수 있습니다. 예전에 만들어 둔 mapbox-demo를 이 블로그의 LAB으로 옮겨 온 것이고, 원본은 스마트 주차, 스마트 폴, 스마트 쉘터 아이콘을 지도에 얹는 데모였습니다.

스트리트 지도와 위성 지도를 비교선으로 나눠 보는 화면
비교선을 기준으로 왼쪽은 스트리트, 오른쪽은 위성 지도입니다. 두 지도의 시점은 항상 같습니다.

앞의 우리동네 지도는 Three.js로 장면부터 직접 만들었다면, 이쪽은 Mapbox GL JS가 지도의 기본기(타일, 스타일, 카메라, 라벨)를 맡습니다. 그 위에 데이터 레이어를 올리는 일에 집중할 수 있는 대신, 렌더링의 많은 부분이 Mapbox가 정한 규칙을 따릅니다. 두 방식을 비교해 보려는 것도 이 페이지를 둔 이유입니다.

Mapbox는 요청 단위가 아니라 지도 로드(map load) 단위로 과금합니다. Map 인스턴스를 만들 때마다 한 번으로 세어지고 월 5만 번까지 무료입니다. 이 페이지는 지도를 두 장 만들기 때문에 방문 한 번이 두 번으로 계산됩니다. 개인 블로그 규모에서는 문제가 없지만, 알고 시작해야 하는 비용 구조입니다.

3. 지도 두 장을 겹쳐 비교선으로 나누기

스와이프 비교 라이브러리(mapbox-gl-compare)도 있지만, 원리가 단순해서 직접 구현했습니다. 지도 컨테이너 두 개를 같은 자리에 겹치고, 위에 놓인 스트리트 지도를 비교선 위치까지만 보이도록 잘라 냅니다. 원본 데모는 바깥 상자의 너비를 줄이고 안쪽 지도 컨테이너는 화면 너비(100vw)로 고정해 두는 방식이었습니다. 지도 틀이 화면 전체를 차지할 때는 맞지만, 이 블로그처럼 지도 틀이 화면보다 좁은 레이아웃에서는 어긋납니다. 그래서 두 컨테이너를 같은 크기로 두고 보이는 영역만 자르는 CSS clip-path: inset()으로 바꿨습니다. 지도의 크기가 변하지 않으니 내용도 움직이지 않습니다.

src/components/lab/MapboxDemo.tsx
<div ref={rightHost} className={styles.map} role="region" aria-label="금천구 위성 지도" />
<div ref={leftHost} className={styles.map} style={{ clipPath: `inset(0 ${100 - split}% 0 0)` }} role="region" aria-label="금천구 스트리트 지도" />

inset(0 30% 0 0)은 위, 오른쪽, 아래, 왼쪽 순서로 안쪽 여백을 정하는 값입니다. 오른쪽만 30%를 잘라 내므로 왼쪽 70%만 보입니다. 잘린 부분은 마우스 이벤트도 받지 않아서, 사용자의 드래그는 보이는 쪽 지도가 받습니다. 어느 쪽에서 움직이든 다음 단계에서 두 지도가 같은 시점을 갖게 합니다.

비교선은 포인터 이벤트로 끕니다. 드래그가 비교선 밖으로 벗어나도 계속 따라오도록 setPointerCapture를 쓰고, 터치 화면에서도 쓸 수 있도록 마우스 대신 포인터 이벤트로 통일했습니다. 키보드로 쓸 수 있도록 role="slider"와 좌우 방향키 처리도 넣었습니다.

src/components/lab/MapboxDemo.tsx
onPointerDown={(event) => { event.currentTarget.setPointerCapture(event.pointerId); moveSplit(event.clientX); }}
onPointerMove={(event) => { if (event.currentTarget.hasPointerCapture(event.pointerId)) moveSplit(event.clientX); }}
onKeyDown={(event) => { if (event.key === "ArrowLeft") setSplit((v) => Math.max(0, v - 5)); else if (event.key === "ArrowRight") setSplit((v) => Math.min(100, v + 5)); else return; event.preventDefault(); }}

4. 두 지도의 시점을 맞추고 무한 반복 막기

지도 두 장이 따로 움직이면 비교가 되지 않으므로, 한쪽이 움직일 때마다 다른 쪽에 같은 중심, 확대, 방위, 기울기를 적용합니다. Mapbox는 지도가 움직이는 동안 move 이벤트를 계속 내보냅니다. 이 이벤트에서 상대 지도의 jumpTo를 부르면 상대 지도도 move를 내보내고, 그것이 다시 이쪽을 움직이는 식으로 무한히 이어집니다.

그래서 "지금 동기화 중"이라는 깃발(syncing)을 두었습니다. 내가 상대를 움직이는 동안에는 깃발이 서 있고, 상대가 내보낸 move는 깃발을 보고 무시합니다. jumpTo가 move 이벤트를 동기적으로 발생시키기 때문에 이 간단한 방식으로 충분합니다.

src/components/lab/MapboxDemo.tsx
let syncing = false;
const link = (from: MapboxMap, to: MapboxMap) => from.on("move", () => {
  if (syncing) return;
  syncing = true;
  to.jumpTo({ center: from.getCenter(), zoom: from.getZoom(), bearing: from.getBearing(), pitch: from.getPitch() });
  syncing = false;
});

동기화는 처음 연출이 끝난 뒤에 연결합니다. 시작할 때는 두 지도가 각자 전체 경계에 맞추고 가까이 다가가는데, 이 동안 서로를 끌어당기면 두 지도가 움직임을 서로 덮어씁니다. 연출은 먼저 fitBounds로 건물과 행정동 경계가 한 화면에 들어오게 맞춘 뒤, moveend 이벤트를 받아 easeTo로 기울기를 주며 다가갑니다. 두 지도가 모두 끝나면 비로소 서로 연결합니다.

src/components/lab/MapboxDemo.tsx
for (const map of [left, right]) {
  map.fitBounds(merged, { maxZoom: Math.min(top + MAP_SETTINGS.fit.maxZoomBoost, MAP_SETTINGS.fit.maxZoomClamp), bearing: MAP_SETTINGS.bearing, pitch: 0 });
  map.once("moveend", () => {
    map.easeTo({ center, zoom: Math.min(top + MAP_SETTINGS.fit.easeZoomBoost, MAP_SETTINGS.fit.maxZoomClamp), pitch: MAP_SETTINGS.pitch, bearing: MAP_SETTINGS.bearing, duration: 600 });
    map.once("moveend", () => { if (++done === 2) { link(left, right); link(right, left); finish(); } });
  });
}

5. 건물을 높이만큼 세우기

건물 윤곽 GeoJSON을 Mapbox에 넘기면 면 돌출(fill-extrusion) 레이어로 입체를 만들 수 있습니다. 레이어의 높이와 색은 데이터의 속성을 읽는 표현식(expression)으로 정합니다. 건물 높이 속성은 HEIGHT이고, 값이 없거나 숫자가 아니면 10m로 칩니다. 색은 높이에 따라 연한 회색에서 짙은 회색으로 보간(interpolate)합니다.

src/components/lab/MapboxDemo.tsx
map.addSource("geumcheon-buildings", { type: "geojson", data: buildings });
const [low, mid, high] = day ? MAP_SETTINGS.colors.day : MAP_SETTINGS.colors.night;
const beforeId = map.getStyle()?.layers?.find((layer) => layer.type === "symbol")?.id;
map.addLayer({
  id: "geumcheon-buildings-extrusion", type: "fill-extrusion", source: "geumcheon-buildings",
  paint: {
    "fill-extrusion-color": ["interpolate", ["linear"], ["to-number", ["get", "HEIGHT"], 10], 0, low, 40, mid, 80, high],
    "fill-extrusion-height": ["to-number", ["get", "HEIGHT"], 10], "fill-extrusion-base": 0,
    "fill-extrusion-opacity": satellite ? 0.95 : day ? 0.85 : 0.6,
  },
}, beforeId);

addLayer의 두 번째 인자(beforeId)가 중요합니다. 레이어는 위에 추가된 것이 아래 것을 덮기 때문에, 그냥 추가하면 건물이 지도의 글자까지 덮어 버립니다. 스타일에서 처음 나오는 글자(symbol) 레이어를 찾아 그 바로 아래에 건물을 끼워 넣어 글자가 건물 위에 보이게 했습니다.

금천구 건물이 높이만큼 입체로 올라간 위성 지도
위성 지도 위에 건물이 높이만큼 올라간 모습. 높은 건물일수록 색이 짙습니다.

원본 건물 GeoJSON은 13MB였습니다. 파일을 열어 보니 건물마다 필지 번호, 용도 코드, 건폐율 같은 속성이 26개씩 붙어 있었는데, 이 페이지에서 쓰는 것은 높이와 이름뿐입니다. 쓰는 속성만 남기는 변환을 한 번 돌려 파일을 5.3MB로 줄였습니다. 17,042채 중 높이가 비어 있는 건물은 3채였고, 중앙값은 7m, 가장 높은 건물은 283m였습니다.

6. 낮과 밤을 태양 위치로 고르기

지금 시각이 낮인지 밤인지는 일출과 일몰 시각으로 판단합니다. 이 계산은 SunCalc 라이브러리가 해 줍니다. 지도의 중심 좌표와 현재 시각을 넘기면 그날의 일출과 일몰을 돌려줍니다. 극지방처럼 값이 없는 경우를 대비해 값이 없으면 낮으로 칩니다.

src/components/lab/MapboxDemo.tsx
const now = new Date(), { sunrise, sunset } = SunCalc.getTimes(now, MAP_SETTINGS.center[1], MAP_SETTINGS.center[0]);
const day = !sunrise || !sunset || (now >= sunrise && now < sunset);
// ...
const left = base(leftHost.current, day ? "mapbox://styles/mapbox/streets-v12" : "mapbox://styles/mapbox/navigation-night-v1");

낮이면 스트리트 스타일, 밤이면 야간 내비게이션 스타일을 쓰고, 건물 색과 투명도(낮 0.85, 밤 0.6), 바람 입자의 색도 낮과 밤에 맞춥니다. 위성 지도는 시각과 무관하게 같은 사진이므로 그대로 둡니다. 라이브러리의 호출이 순수한 계산이라서 지도를 만들기 직전에 한 번만 실행하면 됩니다.

7. 바람 입자 그리기

바람은 입자들이 바람 방향으로 흘러가는 모습으로 그렸습니다. Mapbox에는 사용자가 직접 그리는 사용자 정의 레이어(custom layer)라는 확장점이 있어서, 지도 위에 2D 캔버스를 하나 얹고 그 위에 그리는 방식으로 만들었습니다. 레이어는 onAdd와 onRemove로 시작과 끝을 알리고, 지도가 그려지기 직전마다 prerender가 호출됩니다.

입자의 꼬리는 잔상으로 만듭니다. 매 프레임 캔버스 전체를 지우는 대신, 이전 프레임을 아주 조금만 투명하게 만들고 그 위에 새 위치를 이어 그립니다. 그러면 오래된 선은 서서히 사라지고 최신 선만 진하게 남아 꼬리가 생깁니다. destination-out 합성 모드로 "기존 그림을 일정 비율만 지우는" 사각형을 덮는 것이 핵심입니다.

src/components/lab/WindParticleLayer.ts
this.ctx.globalCompositeOperation = 'destination-out';
this.ctx.fillStyle = `rgba(0, 0, 0, ${1 - this.fadeOpacity})`;
this.ctx.fillRect(0, 0, this.canvas.width, this.canvas.height);
this.ctx.globalCompositeOperation = 'source-over';

입자 하나가 받는 바람은 가장 가까운 관측 지점의 값입니다. 관측 지점은 약 2km 간격의 격자라서 지점 수가 많지 않으므로, 입자마다 모든 지점과의 거리를 비교하는 단순한 최근접 탐색으로 충분합니다. 풍향은 관례상 바람이 불어오는 방향이라(0도가 북풍), 입자는 그 반대쪽으로 흘러가야 합니다. 그래서 동쪽과 북쪽 성분 모두에 음수를 붙여 이동 벡터로 바꿉니다.

src/components/lab/WindParticleLayer.ts
const directionRad = (closestWind.direction * Math.PI) / 180;
const speed = closestWind.speed;
return {
    vx: -Math.sin(directionRad) * speed,
    vy: -Math.cos(directionRad) * speed,
    speed,
};

처음 옮겨 온 코드는 이 부분이 달랐습니다. 매 프레임 풍속에 임의의 작은 수를 곱한 만큼 경위도를 옮겼는데, 계산해 보니 풍속 5m/s가 1초에 13km 넘게 움직이는 속도였습니다. 실제 바람보다 2,600배쯤 빠른 셈이고, 프레임 단위라 주사율이 높은 화면일수록 더 빨라졌습니다. 동서 방향만 부호가 반대여서 바람이 엉뚱한 쪽으로 흐르기도 했습니다.

그래서 실제로 흐른 시간(초)과 풍속(m/s)으로 이동 거리를 미터 단위로 구하고, 위도 1도의 길이(약 111,320m)와 그 위도에서의 경도 1도 길이로 나눠 경위도 차이로 바꾸게 고쳤습니다. 다만 실제 속도 그대로면 이 축척(1픽셀에 약 3.8m)에서 5m/s 바람이 1초에 1픽셀 남짓만 움직여 멈춰 보입니다. 그래서 실제 속도의 30배로 재생합니다. 배율이 모든 입자에 똑같이 걸리므로 바람 사이의 빠르기 차이는 실제 비율 그대로 남고, 이 배율은 지도 아래 안내 문구에도 적었습니다.

src/components/lab/WindParticleLayer.ts
const meters = dt * this.timeScale;
particle.lat += (particle.vy * meters) / METERS_PER_DEGREE;
particle.lng += (particle.vx * meters) / (METERS_PER_DEGREE * Math.cos((particle.lat * Math.PI) / 180));
바람 입자가 지도 위로 흐르는 화면
바람 버튼을 켠 모습. 입자가 풍향을 따라 흐르며 꼬리를 남깁니다.

8. 비와 눈 효과 추가하기

원본 데모에는 바람만 있었는데, 비와 눈도 고를 수 있게 같은 사용자 정의 레이어 방식으로 추가했습니다. 바람은 지도 좌표에 묶여 지도를 움직이면 입자도 따라 움직이지만, 비와 눈은 화면 위에서 떨어지는 효과라서 지도 좌표에 묶지 않았습니다. 지도를 확대하거나 옮겨도 같은 강도로 보이는 편이 자연스럽습니다.

하나의 클래스가 rain과 snow 두 종류를 맡습니다. 비는 길고 빠른 선, 눈은 작고 느린 원이고, 눈에는 좌우로 흔들리는 움직임을 사인 함수로 더했습니다. 입자가 화면 아래로 벗어나거나 옆으로 너무 멀어지면 위에서 다시 시작하는 방식으로 재사용합니다.

src/components/lab/PrecipitationLayer.ts
for (const drop of this.drops) {
  drop.y += drop.speed * scale;
  drop.x += (this.slant + (this.kind === "snow" ? Math.sin(this.tick / 40 + drop.phase) * drop.sway : 0)) * scale;
  if (drop.y > canvas.height + 20 || drop.x < -120 || drop.x > canvas.width + 120) Object.assign(drop, this.spawn(false));
  if (this.kind === "rain") {
    ctx.moveTo(drop.x, drop.y);
    ctx.lineTo(drop.x - this.slant * scale * 0.9, drop.y - drop.length * scale);
  } else {
    ctx.beginPath(); ctx.arc(drop.x, drop.y, drop.length * scale, 0, Math.PI * 2); ctx.fill();
  }
}

scale은 캔버스의 실제 픽셀 수와 화면에 보이는 크기의 비율입니다. 고해상도 화면에서는 캔버스가 화면 크기보다 크기 때문에 이 비율을 곱하지 않으면 입자가 작고 느리게 보입니다. 같은 이유로 선 두께도 scale을 곱했습니다.

비와 눈이 바람 방향으로 기울게 하려고 관측 지점의 평균 가로 바람을 구해 slant로 넘깁니다. 강도는 관측된 강수량(mm/h)으로 정합니다. 강수량이 0이어도 효과가 보이도록 기본 강도 0.35를 두고, 시간당 8mm에서 강도 1이 되도록 선형으로 늘렸습니다. 이 수식은 눈으로 보고 정한 값이며 기상학적 기준이 아닙니다.

src/components/lab/MapboxDemo.tsx
const slant = winds.reduce((sum, w) => sum + Math.sin(w.direction * Math.PI / 180) * w.speed, 0) / winds.length * -0.6;
const intensity = (mm: number | undefined) => mm === undefined ? 0.5 : Math.min(1, 0.35 + mm / 8);

세 효과는 각각 켜고 끌 수 있고, 여러 개를 동시에 켜도 됩니다. 버튼의 상태(weather)가 바뀔 때마다 지도 두 장에서 해당 레이어를 추가하거나 제거합니다. 같은 레이어가 두 번 추가되지 않도록 추가하기 전에 getLayer로 확인합니다.

src/components/lab/MapboxDemo.tsx
const sync = (kind: WeatherKind, id: string, create: () => never) => {
  if (!weather[kind]) { if (map.getLayer(id)) map.removeLayer(id); return; }
  if (!map.getLayer(id)) map.addLayer(create());
};
// ...
sync("rain", "rain-layer", () => new PrecipitationLayer("rain-layer", "rain", { count: 500, intensity: intensity(seen?.rain), slant }) as never);
비와 눈 효과를 함께 켠 화면
비와 눈을 함께 켠 모습. 두 효과는 서로 독립된 레이어입니다.

9. 날씨 데이터 가져오기

바람과 강수량은 OpenWeatherMap의 현재 날씨 API에서 받습니다. 이 API는 좌표 하나당 한 번씩 호출하는 방식이라, 지도 영역을 약 2km 간격 격자로 나눠 지점마다 요청합니다. 금천구 정도의 범위에서는 지점 수가 많지 않습니다.

요청을 한꺼번에 보내면 호출 제한에 걸릴 수 있어서 지점마다 100ms씩 늦춰 보냅니다(i * 100). 응답을 받으면 바람의 방향과 속도를 모으고, 지난 1시간 강수량(rain.1h, snow.1h)은 지점 평균을 냅니다. 한 지점이 실패해도 나머지로 계속하도록 요청마다 오류를 삼켜서 null로 돌려줍니다.

src/components/lab/MapboxDemo.tsx
const results = await Promise.all(points.map(async ([lng, lat], i) => {
  await new Promise((resolve) => setTimeout(resolve, i * 100)); // 호출 제한을 고려해 조금씩 늦춘다.
  try {
    const response = await fetch(`https://api.openweathermap.org/data/2.5/weather?lat=${lat}&lon=${lng}&appid=${OPENWEATHER_KEY}&units=metric`, { signal });
    const data = await response.json();
    return data.wind ? { wind: { lng, lat, direction: data.wind.deg ?? 0, speed: data.wind.speed ?? 0 }, rain: data.rain?.["1h"] ?? 0, snow: data.snow?.["1h"] ?? 0 } : null;
  } catch { return null; }
}));

원본 데모는 이 요청이 끝날 때까지 기다린 뒤에야 지도를 보여 줬습니다. 이 구현은 순서를 바꿨습니다. 먼저 무작위 샘플 바람을 넣어 지도를 바로 띄우고, 날씨 요청은 뒤에서 진행해 끝나면 실제 값으로 바꿉니다. 키가 없거나 요청이 모두 실패해도 효과는 샘플 값으로 동작하고, 페이지 하단 문구가 실제 관측값인지 샘플인지 알려 줍니다. 컴포넌트가 사라질 때는 AbortController로 진행 중인 요청을 취소합니다.

10. Next.js에서 겪은 문제들

Mapbox GL JS는 브라우저의 window와 WebGL이 있어야 동작하므로 서버 렌더링 중에 불러오면 오류가 납니다. 그래서 useEffect 안에서 동적으로 불러왔고, 지도를 만드는 데 필요한 suncalc와 데이터 파일 요청을 한꺼번에 시작합니다. 컴포넌트가 사라지면 active 깃발을 내리고 지도 두 개를 모두 제거(remove)합니다. 제거하지 않으면 WebGL 컨텍스트가 쌓입니다.

src/components/lab/MapboxDemo.tsx
const [{ default: mapboxgl }, { default: SunCalc }, buildings, boundary] = await Promise.all([
  import("mapbox-gl"), import("suncalc"),
  fetchJson<Buildings>("/maps/geumcheon/buildings.geojson"), fetchJson<Boundary>("/maps/geumcheon/boundary.geojson"),
]);
// ...
return () => { active = false; abort.abort(); maps.forEach((map) => map.remove()); leftMap.current = rightMap.current = null; };

가장 헷갈렸던 문제는 지도가 보이지 않고 어두운 빈 화면만 나오는 현상이었습니다. 콘솔에 오류는 없었고, 캔버스 크기를 확인해 보니 높이가 300픽셀로 잡혀 있었습니다. 지도 컨테이너에 position: absolute; inset: 0을 줬는데, Mapbox가 불러오는 mapbox-gl.css가 컨테이너에 position: relative를 지정하고 있었습니다. 내용이 없는 상대 위치 요소는 높이가 0이라서 Mapbox가 기본 크기로 캔버스를 만든 것입니다. 선택자를 한 단계 더 구체적으로 써서 이기게 했습니다.

src/components/lab/MapboxDemo.module.css
/* mapbox-gl.css가 컨테이너를 position: relative로 바꾸므로 선택자를 한 단계 높여 덮어쓴다. */
.viewport > .map { position: absolute; inset: 0; width: 100%; height: 100%; }

개발 서버에서는 또 다른 문제가 있었습니다. 같은 3000번 포트에 다른 개발 서버가 IPv6 주소(::1)로 떠 있어서, 브라우저의 localhost가 이 블로그가 아닌 그쪽으로 연결되었습니다. 127.0.0.1로 접속하면 이번에는 Next.js가 다른 출처의 개발용 리소스 요청이라며 막아서 화면이 하이드레이션되지 않았습니다. allowedDevOrigins에 127.0.0.1을 넣어 풀었습니다.

next.config.ts
const nextConfig: NextConfig = {
  allowedDevOrigins: ["127.0.0.1"],
};

11. 토큰과 배포

Mapbox 접근 토큰은 NEXT_PUBLIC_MAPBOX_TOKEN 환경 변수로 읽습니다. 이름에 NEXT_PUBLIC_이 붙으면 빌드 때 코드에 박혀 방문자에게 보입니다. 브라우저에서 직접 지도를 불러오는 구조라 피할 수 없고, 공개용(pk.로 시작하는 토큰)으로 만들어진 값이라 문제가 없습니다. 대신 Mapbox 계정에서 토큰을 쓸 수 있는 URL을 이 블로그 주소로 제한해 두면 다른 곳에서 가져다 쓰는 일을 막을 수 있습니다.

배포는 Vercel에 환경 변수를 등록하는 것이 먼저입니다. NEXT_PUBLIC_ 값은 빌드 때 코드에 들어가므로 변수를 추가한 뒤에 다시 배포해야 반영됩니다. Vercel CLI로 등록할 때 이름이 NEXT_PUBLIC_으로 시작하는 변수에 대해 공개 노출을 명시하라는 확인이 나왔고, 두 값 모두 --type config로 공개 변수로 등록했습니다. 토큰이 없는 환경에서는 오류 화면 대신 "토큰이 설정되어 있지 않다"는 안내가 뜨도록 만들어 두었습니다.

OpenWeather 키도 같은 방식으로 공개되므로 호출 한도가 소진될 수 있습니다. 그때는 키가 없을 때와 같이 샘플 값으로 동작하도록 설계해 두었습니다.