<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/"><channel>
<title>Kavotin Studio 블로그</title><link>https://kavotin.com/blog</link><description>AI로 1인 회사가 게임과 웹을 만든 기록. 직접 잰 숫자와 실패, 고친 방법.</description><language>ko</language><lastBuildDate>Sat, 21 Nov 2026 00:00:00 GMT</lastBuildDate><atom:link href="https://kavotin.com/blog/rss.xml" rel="self" type="application/rss+xml"/>
<item><title>three.js 게임, 무료 3D 모델 대신 코드로 만든 이유</title><link>https://kavotin.com/blog/code-built-3d</link><guid isPermaLink="true">https://kavotin.com/blog/code-built-3d</guid><pubDate>Sat, 21 Nov 2026 00:00:00 GMT</pubDate><category>게임 만들기</category><description>「무료 3D 모델을 받아 쓰면 더 빠르지 않을까?」 같은 병원 접수 구석을 두 방식으로 만들어 내려받는 양 148KB 대 18,004KB, 그리기 17번 대 51번을 잰 기록.</description><content:encoded><![CDATA[<p>three.js로 브라우저 3D 게임을 만들 때, 무료로 풀린 3D 모델과 재질을 받아 쓰는 길과 배경을 코드로 하나하나 짜는 길 가운데 어느 쪽이 나을까?</p>
<p>웹 3D 병원 게임 「온콜」을 만들면서 2026년 11월 4일에 이 물음을 실험으로 정했다. 같은 병원 접수 구석 하나를 두 가지 방식으로 따로 만들고, 같은 화면 크기와 같은 조건에서 내려받는 양 · 초당 그림 수 · 그리기 횟수를 쟀다.</p>
<p>결과만 먼저 적으면 코드 길은 148KB, 자료 길은 18,004KB였다.</p>
<p>그리고 숫자보다 더 크게 갈린 것은 「받을 수 있는 자료 안에 우리가 필요한 물건이 있느냐」였다.</p>
<h2>두 길을 같은 자리에서 비교한 방법</h2>
<p>시험장은 게임 본편과 떨어진 작은 폴더에 따로 만들었다. 둘 다 three.js 0.187을 쓰고, 카메라 위치 · 방 크기(가로 14.4m, 천장 3.6m) · 화면 크기를 똑같이 맞췄다. 시험장 코드는 AI 코딩 세션이 짰고, 사람 손으로 모델링한 부품은 없다.</p>
<ul><li><strong>코드 길</strong>: 접수대 · 서류장 · 번호표 기계 · 줄 기둥 · 간판 · 의사 캐릭터를 모두 three.js 도형(상자 · 둥근 상자 · 회전체)으로 짰다. 접수 구석 파일 <code>reception.js</code>가 485줄, 의사 캐릭터 <code>doctor.js</code>가 150줄, 빛 굽기 <code>bake.js</code>가 202줄이다.</li><li><strong>자료 길</strong>: Poly Haven에서 CC0로 풀린 모델 8개(화분 · 클립보드 · 메모장 · 문구 · 플라스틱 의자 · 젖은 바닥 표지 · 철제 책상 · 텔레비전), 재질 3개(대리석 타일 · 오크 무늬목 · 흰 회벽), 실내 HDRI 1개를 받아 같은 방에 놓았다. 모두 1K 해상도 판이고, 공개 API 약관을 읽은 뒤 API로 받았다.</li></ul>
<p>자료를 고를 때는 받기 전에 각 사이트의 robots.txt와 사용 조건을 먼저 읽었다. robots.txt 주소가 403 · 404를 내서 규칙을 확인할 수 없는 곳 세 군데는 받지 않았다. 무료 3D 모델 사이트로 자주 소개되는 곳도 있었지만, 규칙을 모르는 채로는 받지 않았다. 그래서 비교에 쓴 자료는 조건이 분명한 한 곳에서만 왔다.</p>
<p>측정 조건은 폰을 흉내 낸 360×640 화면, 낮은 화질 설정, 크롬 개발자 도구의 CPU 4배 늦추기다.</p>
<h2>내려받는 양 148KB 대 18,004KB</h2>
<div class="tbl"><table><thead><tr><th>폰 화면 흉내</th><th>코드 길</th><th>자료 길</th></tr></thead><tbody><tr><td>내려받는 양</td><td>148KB</td><td>18,004KB</td></tr><tr><td>GPU 초당 그림</td><td>58.1</td><td>59.8</td></tr><tr><td>삼각형</td><td>36,034</td><td>24,384</td></tr><tr><td>그리기 횟수</td><td>17</td><td>51</td></tr></tbody></table></div>
<p>코드 길은 자바스크립트 번들 하나가 전부다. 간판 글자 · 나뭇결 · 모니터 화면 같은 그림도 실행할 때 캔버스에 코드로 그리므로 따로 내려받을 그림 파일이 없다.</p>
<p>자료 길은 모델 파일(glTF)과 1K 재질 그림, HDRI가 합쳐 18,004KB가 됐다. 코드 길의 약 122배다. 게다가 자료 길에는 사람이 없고 소품 수도 코드 길보다 적다. 같은 수준으로 채우면 더 커진다.</p>
<p>모바일 데이터로 처음 들어오는 손님에게 18MB는 게임이 뜨기도 전에 떠날 이유가 된다.</p>
<h2>소품을 넣을수록 벌어진 차이</h2>
<p>위 표는 소품까지 다 놓은 뒤의 수치다. 소품을 놓기 전 단계에서도 한 번 쟀다.</p>
<ul><li>코드 길: 소품 전 148KB → 소품 뒤 148KB. 소품 전과 뒤가 같은 파일이다. 삼각형은 10,502개에서 36,034개로 늘었지만 그리기 횟수는 13번에서 17번으로 4번만 늘었다.</li><li>자료 길: 소품 전 7,176KB → 소품 뒤 18,004KB. 소품 몇 개를 놓는 사이에 약 10.8MB가 더 붙었다.</li></ul>
<p>차이는 구조에서 나온다. 코드 길에서 소품 하나를 더하는 일은 번들에 함수 몇 줄이 느는 것이라 압축하면 거의 티가 안 난다. 자료 길에서는 소품 하나마다 모델 파일과 그 모델이 쓰는 재질 그림이 따라온다. 화면을 채울수록 내려받는 양이 소품 수에 맞춰 커진다.</p>
<p>병원 게임은 방이 하나가 아니다. 접수 구석 하나에서 이 정도 차이가 나면, 층과 방이 늘어날수록 차이도 그만큼 커진다.</p>
<h2>프레임 숫자는 왜 판정에 못 썼나</h2>
<p>GPU 쪽 초당 그림 수는 두 길 모두 60 가까이 나왔다. 하지만 이 측정은 CPU만 늦춘 것이라 실제 옛날 폰보다 낙관적이다.</p>
<p>GPU 가속을 끈 소프트웨어 렌더링(해상도 0.75)으로도 쟀는데, 코드 길은 같은 조건에서 40.5와 9.8로 크게 흔들렸다. 자료 길은 6.5로 낮았다. 측정하던 PC에서 다른 작업이 함께 돌았기 때문으로 보이지만 원인을 끝까지 확인하지는 않았다.</p>
<p>코드 길 첫 측정에서 나온 「가장 긴 한 장 183ms」도 그렇다. 결함을 고친 판에서 두 번 다시 쟀을 때는 17ms였고 183ms는 다시 나오지 않았다. 원인은 아직 모른다.</p>
<p>고친 판에서 소프트웨어 렌더링을 소품 전 · 뒤로 번갈아 세 번씩 다시 재 봤다. 소품 전 28.8 · 11.1 · 12.9, 소품 뒤 10.7 · 10.1 · 13.2였다. 둘째 측정부터는 소품 전과 뒤가 거의 같았다. 측정 환경 자체가 천장에 닿아 소품의 부담을 가르지 못한 것이다.</p>
<p>그래서 이 실험에서는 프레임 숫자로 끊김 여부를 판정하지 않았다. 판정은 내려받는 양과 그리기 횟수, 그리고 아래의 자료 문제로 했다.</p>
<p>실제 폰 측정은 본편 로비를 만든 뒤 따로 했다. 11월 6일 아이폰으로 5G 망에서 잰 1층 로비는 삼각형 97,958개, 그리기 60번에서 초당 60.0프레임이었다. 측정 방법과 사람이 22명일 때 결과는 <a href="https://kavotin.com/blog/oncall-free-tier" rel="noopener">Cloudflare 무료로 3D 멀티플레이 게임 서버 돌리기</a> 글에 적었다.</p>
<h2>그리기 17번을 만든 빛 굽기</h2>
<p>그리기 횟수(draw call)는 GPU에 「이것을 그려라」라고 명령하는 횟수다. 폰에서는 삼각형 수보다 이 횟수가 먼저 발목을 잡는 일이 많다.</p>
<p>자료 길은 모델마다 재질이 달라 51번을 그렸다. 코드 길은 삼각형이 더 많은데도 17번이다. 비결은 <code>bake.js</code>의 두 가지다.</p>
<ol><li>같은 재질을 쓰는 부품을 <code>mergeGeometries</code>로 한 덩어리로 합친다. 접수대 나무 살 수십 개가 한 번에 그려진다.</li><li>빛을 실행 중에 계산하지 않는다. 장면을 불러오는 순간 각 꼭짓점의 밝기를 계산해 정점 색에 구워 넣는다. 실행 중에는 재질 계산이 없으니 옛날 폰에서도 부담이 적다.</li></ol>
<p>대가도 있다. 구운 빛은 움직이지 않는다. 물결 같은 움직이는 빛이나 바닥의 또렷한 반사, 상판의 윤기는 코드 길이 약하다.</p>
<p>결함을 고치면서 그리기 횟수는 조금 늘었다. 아크릴 가림막에 윤기와 모서리 · 금속 받침을 더한 뒤, 모서리를 합치기 전 판은 23번이었고 합친 지금 판은 21번 · 삼각형 36,652개다. GPU 쪽은 초당 60.1장 · 가장 긴 한 장 17ms였고, 번들은 gzip 150,210바이트로 거의 그대로였다.</p>
<figure><img src="https://kavotin.com/img/b-oncall-code-path-1200.5ac2b566.jpg" width="1200" height="750" alt="코드로만 만든 병원 접수 구석. 「접수 · 수납」 간판과 창구 번호 전광판, 나무 살 접수대, 번호표 기계, 가운 입은 의사가 보인다"><figcaption>코드 길(11월 4일 시험장, 1280폭). 간판 · 전광판 · 번호표 기계 글자는 실행할 때 캔버스에 그린다. 내려받는 양 148KB.</figcaption></figure>
<figure><img src="https://kavotin.com/img/b-oncall-asset-path-1200.631b3908.jpg" width="1200" height="750" alt="받은 CC0 자료로 만든 같은 접수 구석. 대리석 바닥과 흰 벽, 모니터 셋이 놓인 상자 접수대, 화분과 젖은 바닥 표지만 있다"><figcaption>자료 길(같은 날, 같은 카메라). 접수대 모델이 없어 상자에 받은 재질을 입혔고, 쓸 만한 사람 모델이 없어 사람은 넣지 않았다. 내려받는 양 18,004KB.</figcaption></figure>
<h2>결정을 가른 것은 없는 물건이었다</h2>
<p>두 사진을 나란히 놓으면 차이가 숫자보다 분명하다. 받을 수 있는 자료 안에는 병원 접수대도, 한글 간판도, 번호표 기계도, 가운을 입힐 수 있는 의사 캐릭터도 없었다.</p>
<p>접수대는 결국 상자에 받은 재질을 입혀 흉내 냈다. 사람은 조건이 분명한 CC0 모델 가운데 쓸 만한 것을 찾지 못했다.</p>
<p>반대로 코드 길의 1280폭 사진에는 병원 소품이 7종 들어갔다. 창구 표시판 · 번호표 기계 · 손소독제 받침 · 줄 기둥 · 서류장 · 모니터 · 종이다. 같은 장면을 360폭으로 찍으면 화면에 4종이 든다. 의사 캐릭터는 가운 · 청진기 · 명찰로 역할이 읽히고, 화면 높이에서 차지하는 키는 1280폭에서 약 36%, 360폭에서 약 28%였다. 폰 화면에서도 얼굴이 보이는 크기다.</p>
<p>즉 자료 길을 골라도 게임의 핵심 물건은 어차피 코드로 만들어야 했다. 그러면 18MB를 더 싣고 핵심은 코드로 짜는 섞인 길이 되고, 두 화풍이 한 화면에서 어긋난다.</p>
<p>그래서 11월 4일에 온콜의 그림 길을 「코드로 만든다」로 정했다. 지금 게임 번들은 gzip 152KB이고, 바깥 3D 모델 · 글꼴은 하나도 싣지 않는다. 글자는 기기 시스템 글꼴로 그린다.</p>
<h2>코드 길에서 실제로 겪은 결함</h2>
<p>코드로 짜면 자료의 품질 문제 대신 도형 계산의 결함을 직접 떠안는다. AI 세션이 시험장 사진을 1280 · 360 두 폭으로 찍어 보며 찾은 것들이다. 오류 메시지 없이 모양만 틀어지는 3D 결함은 사진으로 봐야 잡힌다.</p>
<ul><li>의사 가운 허리에 이음매가 보였다. 회전체(<code>lathe</code>)에 윤곽 점을 위에서 아래로 넘겨 면과 법선이 안쪽을 본 것이 원인이었다. three.js로 따로 시험해 확인했고, 본편 쪽 가운 코드는 아래에서 위로 넘기고 있어 이 문제가 없었다.</li><li>의사 팔이 굽지 않아 막대처럼 보였다. 팔꿈치를 더해 고쳤다.</li><li>나무 살 밑동에 검은 톱니가 보여 앞에 걸레받이를 대어 가렸다. 양끝의 작은 톱니는 아직 남아 있다.</li><li>창구 아크릴이 거의 보이지 않아 빗금 윤기와 밝은 모서리, 금속 받침을 더했다.</li><li>360폭 0.8m 거리에서 「2번 창구」 표시판 오른쪽이 잘려 창구 가운데로 옮겼다. 고친 뒤에는 「2번 창구」와 「접수 · 수납」이 둘 다 잘리지 않고 읽혔다.</li></ul>
<h2>아직 못 미치는 것</h2>
<p>고친 판에도 모자란 점이 분명히 남았다. 기록해 둔 것을 그대로 옮긴다.</p>
<ul><li>캐릭터 표정이 하나뿐이고, 몸이 토막으로 나뉘어 보인다.</li><li>사람이 쓰다 둔 흔적이 없고, 탁자 위 물건 줄맞춤이 지나치게 반듯하다.</li><li>진료 기록처럼 병원에서만 말이 되는 소품이 적다.</li><li>빛의 생기와 캐릭터의 매끈함은 잘 만든 상용 3D 게임보다 뚜렷이 못하다.</li></ul>
<p>코드 길은 가볍고 필요한 물건을 무엇이든 만들 수 있지만, 그만큼 자연스러움도 하나하나 코드로 채워야 한다. 받은 모델이 공짜로 주던 손때 묻은 느낌을 이쪽에서는 직접 짜 넣어야 한다.</p>
<h2>정리: 무료 3D 모델을 받기 전에 잴 것 둘</h2>
<p>저는 작은 팀이 three.js로 브라우저 3D 게임을 만든다면, 받은 자료의 겉모습보다 먼저 두 가지를 재 봐야 한다고 본다.</p>
<ol><li>첫 화면까지 몇 MB를 내려받게 하는가. 소품을 다 놓은 뒤의 크기로 잰다.</li><li>필요한 물건이 그 자료 안에 정말 있는가. 없으면 그 물건은 어차피 코드나 직접 모델링으로 만들어야 한다.</li></ol>
<p>온콜의 경우 그 두 질문만으로 답이 나왔다. 남은 숙제는 빛과 캐릭터를 코드로 더 다듬는 일이다.</p>]]></content:encoded></item>
<item><title>인스타 프로필 링크용 짧은 주소 만들기</title><link>https://kavotin.com/blog/short-url-worker</link><guid isPermaLink="true">https://kavotin.com/blog/short-url-worker</guid><pubDate>Fri, 20 Nov 2026 00:00:00 GMT</pubDate><category>웹 만들기</category><description>「인스타그램 소개칸에 어떤 주소를 적어야 클릭이 새지 않을까?」 302 이동과 꼬리표 보존, 한글 NFC 정규화까지 27줄로 시작해 36줄이 된 기록.</description><content:encoded><![CDATA[<p>소셜 미디어 프로필이나 인쇄물, 영상 설명란에 여러 웹 게임과 도구의 주소를 안내할 때 서브도메인과 유입 경로 꼬리표가 길게 붙은 주소를 그대로 적어 두면 어떻게 될까?</p>
<p>손님이 주소창에 직접 쳐서 들어오기는 불가능해지고, 나중에 제품의 도메인을 옮기거나 유입 분석용 쿼리 규칙을 바꿀 때마다 이미 올라간 게시물의 링크를 일일이 찾아 고쳐야 한다. 그렇다고 외부 유료 단축 URL 서비스를 쓰면 매달 구독료가 나가거나 우리 도메인 대신 낯선 단축 도메인이 노출된다.</p>
<p>카보틴 스튜디오 공식 홈(<a href="https://kavotin.com/" rel="noopener">kavotin.com</a>)은 이 문제를 해결하려고 별도의 데이터베이스나 외부 단축 서비스 없이 <code>worker/index.js</code> 한 파일로 자체 짧은 주소 라우터를 만들어 운영한다. 첫 판은 주석까지 27줄이었고, 8일 뒤 받는 파일의 누름을 세는 9줄이 붙어 2026년 11월 20일 지금은 36줄이다.</p>
<p>2026년 11월 11일 첫 배포(커밋 <code>1e67e21</code>)부터 적용한 302 리다이렉트 설계와 쿼리 꼬리표 보존 규칙, 한글 주소(<code>kavotin.com/온콜</code>)의 유니코드 정규화, Cloudflare 무료 한도를 아끼는 라우팅 설정, 그리고 나중에 붙인 누름 셈이 짧은 주소를 어떻게 건드리지 않게 했는지 정리한다.</p>
<h2>하나의 목록에서 뽑아내는 10개의 짧은 주소</h2>
<p>짧은 주소 매핑 표를 Worker 코드 안에 따로 하드코딩하면 새 제품이 추가되거나 주소가 바뀔 때 홈페이지 화면과 Worker 양쪽을 두 번 고쳐야 한다.</p>
<p>그래서 모든 제품의 정보와 별칭을 담고 있는 정본 파일(<code>src/content.mjs</code>)을 정적 HTML 빌드 스크립트(<code>build.mjs</code>)와 가장자리 서버 코드(<code>worker/index.js</code>)가 함께 읽도록 묶었다.</p>
<pre><code>import { products, extraLinks } from '../src/content.mjs';

const LINKS = new Map();
for (const p of products) for (const key of [p.id, ...(p.aliases ?? [])]) LINKS.set(key.toLowerCase(), { url: p.url, tag: true });
for (const [key, url] of Object.entries(extraLinks)) LINKS.set(key.toLowerCase(), { url, tag: false });</code></pre>
<p>Worker가 기동할 때 <code>products</code> 배열(4종)의 영문 식별자(<code>id</code>)와 별칭 배열(<code>aliases</code>), 그리고 제품이 아닌 외부 연결(<code>extraLinks</code>)을 순회하며 메모리 안의 <code>Map</code> 객체(<code>LINKS</code>)를 채운다.</p>
<p>이 코드로 만들어지는 10개의 짧은 주소와 도착지는 아래와 같다. 모두 302로 보내고, 제품 넷은 도착 주소 끝에 <code>?ref=kavotin</code>을 붙인다(<code>tag: true</code>).</p>
<ul><li>온콜: <code>/oncall</code> · <code>/온콜</code> → oncall.kavotin.com</li><li>클라우드라인: <code>/cloudline</code> · <code>/tram</code> · <code>/클라우드라인</code> → cloudline.kavotin.com</li><li>홍실: <code>/hongsil</code> · <code>/홍실</code> → hongsil.dotorium.com</li><li>카리온: <code>/karyon</code> · <code>/카리온</code> → karyon.dotorium.com</li><li>인스타그램: <code>/insta</code> → instagram.com/kavotinstudio (꼬리표 없음)</li></ul>
<p>제품 4종은 각각 영문 ID와 한글 이름을 모두 별칭으로 가지고 있고, 클라우드라인은 기억하기 쉬운 <code>/tram</code>까지 포함해 세 개의 진입 경로를 갖는다.</p>
<figure><img src="https://kavotin.com/img/b-short-url-flow-1200.1a90b28b.jpg" width="1200" height="750" alt="카보틴 스튜디오 홈의 짧은 주소 연결 흐름도"><figcaption>공식 홈 화면 가운데에 배치된 짧은 주소 흐름도(1280폭). 왼쪽의 짧은 주소 알약 단추 넷이 가운데 매듭 로고를 거쳐 오른쪽 각 제품으로 이어진다.</figcaption></figure>
<p>반면 공식 인스타그램 계정으로 보내는 <code>/insta</code>는 외부 플랫폼이므로 자체 유입 집계 꼬리표(<code>?ref=kavotin</code>)를 붙이지 않도록 <code>tag: false</code>로 구분했다.</p>
<p>11월 20일 <code>wrangler deploy --dry-run</code>으로 다시 잰 Worker 스크립트 전체 크기는 <code>src/content.mjs</code>의 제품 문구와 누름 셈 코드까지 합쳐 17.93KiB(gzip 6.31KiB)다. 같은 날 실제 배포에서 Wrangler가 찍은 기동 시간(Worker Startup Time)은 2ms였다.</p>
<h2>301 대신 302와 캐시 금지를 고른 이유</h2>
<p>웹에서 주소를 옮길 때 흔히 영구 이동을 뜻하는 <code>301 Moved Permanently</code>를 습관처럼 쓰곤 한다.</p>
<p>하지만 짧은 주소 라우터에 301을 쓰면 한 번이라도 그 주소를 눌렀던 손님의 브라우저가 리다이렉트 결과를 디스크 캐시에 영구히 박아 버린다.</p>
<p>나중에 제품의 서브도메인을 옮기거나 기본 꼬리표 규칙을 고쳐도, 이전에 방문했던 브라우저는 Worker에 요청조차 보내지 않고 예전 주소로 바로 이동한다.</p>
<pre><code>if (url.hostname === 'www.kavotin.com') {
  url.hostname = 'kavotin.com';
  return Response.redirect(url.toString(), 301);
}</code></pre>
<p>그래서 절대 바뀔 일이 없는 도메인 정규화(<code>www.kavotin.com</code> → <code>kavotin.com</code>)에만 <code>301</code>을 썼다.</p>
<p>반면 10개의 짧은 주소 이동에는 일시 이동인 <code>302 Found</code> 상태 코드와 함께 <code>Cache-Control: no-store</code> 헤더를 명시해 언제든 서버의 최신 매핑 표를 따르도록 강제했다.</p>
<h2>유입 꼬리표 보존과 기본 꼬리표 합성</h2>
<p>짧은 주소를 운영할 때 단순히 고정된 문자열로만 리다이렉트하면 마케팅 채널별 유입 경로가 모두 증발한다.</p>
<p>예를 들어 인스타그램 스토리 광고나 프로필 링크에 <code>kavotin.com/oncall?utm_source=ig&amp;ref=story</code>처럼 캠페인 꼬리표를 달아 두었는데, 라우터가 이를 무시하고 무조건 <code>https://oncall.kavotin.com/?ref=kavotin</code>으로 덮어쓰면 어느 채널에서 손님이 왔는지 알 수 없다.</p>
<p>반대로 아무 꼬리표 없이 <code>kavotin.com/oncall</code>만 치고 들어온 요청은 직접 주소창에 도착 도메인을 친 것과 구분되지 않는다.</p>
<pre><code>const hit = LINKS.get(key);
if (hit) {
  const to = new URL(hit.url);
  for (const [k, v] of url.searchParams) to.searchParams.set(k, v);
  if (hit.tag &amp;&amp; !to.searchParams.has('ref')) to.searchParams.set('ref', 'kavotin');
  return new Response(null, { status: 302, headers: { Location: to.toString(), 'Cache-Control': 'no-store' } });
}</code></pre>
<p>이 두 가지를 모두 만족시키려고 <code>worker/index.js</code>의 27~30번째 줄은 2단계로 쿼리 스트링을 조립한다.</p>
<ol><li>먼저 들어온 요청(<code>url.searchParams</code>)에 붙어 있던 모든 쿼리 항목을 도착지 URL(<code>to.searchParams</code>)로 그대로 복사한다.</li><li>그 뒤 도착지가 우리 제품(<code>hit.tag === true</code>)이면서 복사된 파라미터 중에 <code>ref</code>가 없을 때만 기본 꼬리표인 <code>ref=kavotin</code>을 추가한다.</li></ol>
<p>덕분에 외부에서 <code>?utm_source=ig&amp;ref=story</code>를 달고 들어오면 <code>https://oncall.kavotin.com/?utm_source=ig&amp;ref=story</code>로 온전히 넘어가고, 빈 주소로 들어오면 <code>?ref=kavotin</code>이 붙어 공식 홈 짧은 주소를 거쳤다는 흔적이 남는다.</p>
<p>이 꼬리표 규칙은 블로그 빌드 스크립트(<code>blog.mjs</code> 33~36번째 줄)에도 똑같이 들어 있어서, 블로그 글 본문 안에서 우리 제품 도메인으로 나가는 모든 링크에도 빌드 시점에 자동으로 <code>?ref=kavotin</code>이 붙는다.</p>
<h2>한글 주소의 NFC 정규화와 깨진 인코딩 방어</h2>
<p>음성이나 댓글로 주소를 안내할 때는 영문 철자(<code>/cloudline</code>)보다 한글 이름(<code>kavotin.com/클라우드라인</code>, <code>kavotin.com/온콜</code>)이 훨씬 전달하기 쉽다.</p>
<p>그런데 HTTP 요청 경로에서 한글 주소를 다룰 때는 눈에 보이지 않는 세 가지 함정이 있다.</p>
<pre><code>let key = '';
try { key = decodeURIComponent(url.pathname).normalize('NFC').toLowerCase().replace(/^\/+|\/+$/g, ''); } catch { /* 깨진 주소는 404 로 */ }</code></pre>
<p>첫째는 퍼센트 인코딩이다. 브라우저 주소창에 <code>kavotin.com/온콜</code>을 입력하면 실제 HTTP 요청의 <code>url.pathname</code>은 <code>/%EC%98%A8%EC%BD%9C</code>라는 ASCII 문자열로 들어온다. <code>decodeURIComponent()</code>로 먼저 바이트열을 풀어야 한글 문자열과 비교할 수 있다.</p>
<p>둘째는 운영체제마다 다른 유니코드 정규화 방식이다. Windows와 Android는 한글 한 글자를 완성형 코드 포인트 하나(NFC)로 다루므로 <code>'온콜'</code>이 2글자(<code>\uC628\uCF5C</code>)가 된다.</p>
<p>하지만 macOS나 iOS의 일부 입력기·파일 시스템에서 복사한 텍스트는 초성·중성·종성이 분리된 정준 분해(NFD) 상태여서 겉보기에는 똑같은 <code>'온콜'</code>이라도 내부적으로는 6글자(<code>\u110B\u1169\u11AB\u110F\u1169\u11AF</code>)가 된다.</p>
<p>코드 뒤에 <code>.normalize('NFC')</code>를 붙여 두지 않으면 맥이나 아이폰 사용자가 복사해 넣은 한글 주소만 <code>LINKS.get(key)</code>에서 <code>undefined</code>가 나와 404로 빠진다.</p>
<p>셋째는 잘못 잘린 퍼센트 인코딩이다. 외부 크롤러나 봇이 URL 끝을 잘못 잘라 <code>/%E0%A4%A</code>처럼 불완전한 UTF-8 시퀀스를 요청하면 <code>decodeURIComponent()</code>는 즉시 <code>URIError: URI malformed</code> 예외를 던진다.</p>
<p>이를 <code>try ... catch</code> 없이 실행하면 Worker 프로세스가 미처리 예외로 죽으면서 방문자에게 Cloudflare의 500 오류 화면(Error 1101)을 노출한다.</p>
<p>그래서 예외가 나면 조용히 잡아 <code>key</code>를 빈 문자열(<code>''</code>)로 두고 마지막 줄인 <code>env.ASSETS.fetch(request)</code>로 넘긴다. 그러면 정적 자산 처리기가 <code>not_found_handling: &quot;404-page&quot;</code> 설정에 따라 디자인된 404 안내 페이지(<code>없는 주소.</code>)를 정상 반환한다.</p>
<h2>무료 요청 10만 건을 아끼는 정적 자산 우회</h2>
<p>카보틴 스튜디오 홈은 유료 서버 없이 Cloudflare Workers 무료 구간(하루 요청 100,000건 한도) 안에서 돌아간다.</p>
<p>만약 홈페이지와 블로그의 이미지(<code>.webp</code>, <code>.jpg</code>, <code>.png</code>)나 서브셋 웹폰트(<code>.woff2</code>) 요청까지 전부 Worker 스크립트를 거치게 두면, 방문자 한 명이 글 하나를 열 때도 HTML 한 번에 글꼴 두 벌과 그림 몇 장이 따로따로 Worker 호출 횟수를 깎아 먹는다.</p>
<pre><code>{
  &quot;name&quot;: &quot;kavotin-home&quot;,
  &quot;main&quot;: &quot;worker/index.js&quot;,
  &quot;assets&quot;: {
    &quot;directory&quot;: &quot;./dist&quot;,
    &quot;binding&quot;: &quot;ASSETS&quot;,
    &quot;not_found_handling&quot;: &quot;404-page&quot;,
    &quot;run_worker_first&quot;: [&quot;/*&quot;, &quot;!/img/*&quot;, &quot;!/fonts/*&quot;]
  }
}</code></pre>
<p>이 낭비를 막으려고 <code>wrangler.jsonc</code> 7번째 줄의 <code>run_worker_first</code> 배열에 부정 패턴 두 개(<code>&quot;!/img/*&quot;</code>, <code>&quot;!/fonts/*&quot;</code>)를 넣었다.</p>
<p>기본적으로 정적 자산(<code>dist/</code>)과 Worker를 함께 배포하면 정적 파일이 있는 경로는 Worker를 건너뛰지만, 우리는 <code>www.</code> 서브도메인 301 이동과 짧은 주소 판별을 먼저 해야 하므로 <code>&quot;/*&quot;</code>에 대해 Worker 우선 실행을 켰다.</p>
<p>그 대신 이미지 폴더(<code>!/img/*</code>)와 글꼴 폴더(<code>!/fonts/*</code>)는 예외로 빼서, 가장자리 캐시 계층이 Worker를 깨우지 않고 정적 파일을 바로 내려주도록 분리했다. Cloudflare 정적 자산 문서(11월 20일 다시 확인)는 「Requests to static assets are free and unlimited」라고 적는다. 같은 문서는 반대쪽 위험도 적어 둔다. 무료 구간에서 하루 한도를 넘기면 <code>run_worker_first</code>에 걸린 경로는 정적 파일로 물러서지 않고 429(Too Many Requests)를 돌려준다. 그래서 그림과 글꼴처럼 수가 많은 요청을 Worker 바깥으로 빼 두는 일은 비용보다 먼저 화면이 깨지지 않게 하는 일이었다.</p>
<h2>8일 뒤 붙은 9줄: 누름 셈을 길 옆에 두기</h2>
<p>11월 19일에 무료로 받는 파일 쪽(<code>/free</code>)이 생기면서 「몇 명이 실제로 받았는가」를 세야 했다. 파일은 정적 자산이 내주므로 Worker가 파일을 직접 읽을 필요는 없다. 그런데 <code>/free/</code> 경로는 <code>run_worker_first</code>의 예외가 아니라서 어차피 Worker를 한 번 지난다. 그 길목에서 누름만 세고 파일은 그대로 넘기기로 했다.</p>
<pre><code>const FILES = new Map(gifts.flatMap((g) =&gt; [g, ...(g.more ?? [])].map((f) =&gt; [`free/${g.id}/${f.file}`.toLowerCase(), f.ev])));
...
const ev = FILES.get(key);
if (ev) { const job = count(env, request, ev); if (ctx) ctx.waitUntil(job); else await job; }
return env.ASSETS.fetch(request);</code></pre>
<p>받는 파일 목록도 짧은 주소와 같은 정본 <code>src/content.mjs</code>의 <code>gifts</code> 배열에서 뽑는다. 파일 주소 하나가 셈 이름 하나(<code>snow_zip</code> 같은 것)로 묶인다.</p>
<p>이때 지킨 순서가 하나 있다. 셈은 짧은 주소 판별(<code>LINKS.get</code>)보다 뒤, 정적 자산으로 넘기기 바로 앞에 둔다. 그래서 짧은 주소 302 응답은 셈 코드가 실패해도 영향을 받지 않는다.</p>
<p>셈 자체는 <code>ctx.waitUntil()</code>로 응답 뒤에 돌린다. 손님은 셈이 끝나기를 기다리지 않고 바로 파일을 받는다. 셈은 같은 계정의 다른 Worker에 서비스 바인딩(<code>env.TALLY</code>)으로 넘겨서 이 Worker 쪽 KV 쓰기는 0이다.</p>
<p>거르기는 <code>worker/tally.js</code>(32줄)가 맡는다. GET이 아닌 요청, 중간부터 이어 받는 요청(<code>Range</code>가 <code>bytes=0-</code>로 시작하지 않는 것), 브라우저의 미리 받기(<code>Sec-Purpose: prefetch</code>), 이름에 봇 · 크롤러 표시가 있는 사용자 에이전트, 데이터센터 망에서 온 요청은 세지 않는다. 시험 삼아 누른 것은 <code>?ref=test</code>를 달면 <code>test:</code> 이름으로 따로 쌓인다.</p>
<p><code>count()</code> 함수는 통째로 <code>try ... catch</code> 안에 있다. <code>test/check.mjs</code>는 셈 쪽 Worker가 죽은 상황(<code>fetch</code>가 예외를 던지는 가짜 <code>TALLY</code>)을 만들어 그때도 파일이 200으로 나가는지 본다. 앞에서 깨진 주소를 404로 돌린 것과 같은 생각이다. 덧붙인 기능이 원래 길을 막으면 안 된다.</p>
<h2>배포 전과 배포 후 두 번 도는 14개 시험</h2>
<p>코드가 27줄로 짧아도 정규식이나 인코딩 순서를 한 줄만 잘못 건드리면 모든 제품의 진입로가 끊긴다.</p>
<p>그래서 <code>test/check.mjs</code>는 배포 전 로컬 환경과 배포 후 실제 도메인 양쪽에서 짧은 주소를 자동으로 시험한다.</p>
<pre><code>const env = { ASSETS: { fetch: async () =&gt; new Response('asset', { status: 200 }) } };
const go = (u) =&gt; worker.fetch(new Request(u), env);
let r = await go(`https://kavotin.com/${p.id.toUpperCase()}/?utm_source=ig&amp;ref=story`);
ok(r.headers.get('Location') === `${p.url}?utm_source=ig&amp;ref=story`, '대문자 · 끝 빗금 · 꼬리표 넘기기');
r = await go('https://kavotin.com/%E0%A4%A');
ok(r.status === 200, '깨진 주소도 죽지 않는다');</code></pre>
<p>로컬 검사(<code>node test/check.mjs</code>)는 Cloudflare 서버를 띄우지 않고도 Node.js 안에서 가짜 <code>env.ASSETS</code> 객체를 넣어 <code>worker.fetch()</code>를 직접 호출한다.</p>
<p>여기서 10개 짧은 주소 전수 검사(10건), 대문자와 끝 슬래시 및 쿼리 파라미터 보존(<code>/ONCALL/?utm_source=ig&amp;ref=story</code> 1건), <code>www</code> 301 리다이렉트(1건), 첫 화면 정적 자산 폴백(1건), 깨진 인코딩(<code>/%E0%A4%A</code>) 예외 방어(1건)까지 총 14건을 확인한다. 지금 이 검사들은 <code>test/check.mjs</code> 129~147번째 줄에 있다.</p>
<p>이어서 배포가 끝나면 <code>node test/check.mjs --live https://kavotin.com</code> 명령이 실행되어 실제 프로덕션 주소에 <code>redirect: 'manual'</code> 옵션으로 HTTP 요청을 보내 10개 짧은 주소의 실제 <code>302</code> 상태 코드와 <code>location</code> 헤더, 없는 주소(<code>/no-such-page</code>)의 <code>404</code> 응답을 다시 대조한다.</p>
<p>저는 작은 스튜디오일수록 외부 SaaS 도구를 하나씩 늘리기보다 정적 데이터 파일 하나와 수십 줄짜리 가장자리 코드로 인프라를 단순하게 유지하는 편이 훨씬 단단하다고 본다.</p>
<p>36줄의 코드에 영문과 한글 짧은 주소, 유입 꼬리표, 예외 방어, 받기 누름 셈까지 모아 두니 새 게임이나 도구를 출시할 때도 <code>src/content.mjs</code>에 한 줄만 더하면 즉시 짧은 주소가 열린다.</p>]]></content:encoded></item>
<item><title>CSP 설정하는 법: 인라인 스크립트 해시가 깨질 때</title><link>https://kavotin.com/blog/csp-hash-crlf-rum</link><guid isPermaLink="true">https://kavotin.com/blog/csp-hash-crlf-rum</guid><pubDate>Fri, 20 Nov 2026 00:00:00 GMT</pubDate><category>웹 만들기</category><description>「인라인 스타일과 스크립트를 해시로 잠그면 왜 깨질까?」 Windows CRLF 줄바꿈과 Cloudflare 분석 스크립트 충돌 해결.</description><content:encoded><![CDATA[<p>정적 웹사이트에서 외부 CSS와 자바스크립트 요청을 없애려고 모든 코드를 HTML 안에 인라인으로 넣으면서, 동시에 <code>unsafe-inline</code> 없이 엄격한 CSP(Content-Security-Policy)를 유지하려면 어떻게 해야 할까?</p>
<p>가장 확실한 방법은 빌드 시점에 <code>&lt;style&gt;</code>과 <code>&lt;script&gt;</code> 태그 안의 텍스트를 SHA-256으로 해싱해 응답 헤더(<code>_headers</code>)에 <code>'sha256-...'</code> 목록으로 적어 주는 것이다.</p>
<p>카보틴 스튜디오 공식 홈(<a href="https://kavotin.com/" rel="noopener">kavotin.com</a>)은 첫 화면 표시 시간(FCP)을 줄이려고 홈 CSS(11월 20일 빌드 기준 18.0KB)와 블로그 추가 CSS(10.4KB), 카드 가로 넘김 스크립트(<code>src/main.js</code>), 구조화 데이터(<code>application/ld+json</code>)를 모두 HTML 안에 인라인으로 굽고 <code>default-src 'none'</code> 기반의 해시 CSP를 걸었다.</p>
<p>하지만 이 해시 CSP는 두 번 흔들렸다. 11월 11일에는 Cloudflare가 응답에 끼워 넣은 스크립트가 실제로 막혔고, 11월 15일에는 Windows 줄바꿈 문자(<code>CRLF</code>)가 원본 파일에 섞여 들어온 것을 굽기 전에 찾아냈다. 두 원인과 <code>build.mjs</code> · <code>test/check.mjs</code>에 넣은 대책을 기록한다.</p>
<h2>외부 요청을 없앤 인라인 구조와 해시</h2>
<p>홈페이지 첫 화면을 캐시 없이 열 때 브라우저가 별도의 <code>.css</code>나 <code>.js</code> 파일을 다시 요청하면 왕복 지연(RTT)이 한 번 더 든다.</p>
<p>그래서 <code>build.mjs</code>는 주석과 공백을 압축한 CSS 문자열과 스크립트 문자열을 모든 HTML 파일의 <code>&lt;head&gt;</code>와 <code>&lt;body&gt;</code> 끝에 바로 넣는다.</p>
<p>그 대신 인라인 코드가 임의로 실행되는 XSS(교차 사이트 스크립팅) 구멍을 막으려고 <code>unsafe-inline</code>을 열지 않고 Node.js의 <code>crypto</code> 모듈로 각 블록의 SHA-256 해시를 계산한다.</p>
<pre><code>const b64 = (s) =&gt; crypto.createHash('sha256').update(s).digest('base64');
const csp = (styles, scripts) =&gt;
  `default-src 'none'; img-src 'self' data:; font-src 'self'; ` +
  `style-src ${styles.map((s) =&gt; `'sha256-${b64(s)}'`).join(' ')}; ` +
  `script-src ${scripts.map((s) =&gt; `'sha256-${b64(s)}'`).join(' ')} https://static.cloudflareinsights.com; ` +
  `connect-src 'self' https://cloudflareinsights.com; base-uri 'none'; form-action 'none'; frame-ancestors 'none'`;</code></pre>
<p>블로그 페이지는 홈 기본 스타일(<code>css</code>, 18.0KB)에 블로그 전용 스타일(<code>blogCss</code>, 10.4KB)까지 <code>&lt;style&gt;</code> 태그 두 개를 쓰므로 <code>style-src</code>에 SHA-256 해시 두 개가 나란히 들어간다.</p>
<p>스크립트 쪽도 본문 동작 스크립트(<code>js</code>)와 첫 화면 조직 정보 JSON-LD(<code>jsonLd</code>) 두 개의 해시가 <code>script-src</code>에 들어간다.</p>
<h2>Windows CRLF 줄바꿈과 해시 불일치</h2>
<p>줄바꿈 이야기는 2026년 11월 15일, 블로그 틀을 만들려고 같은 저장소의 git worktree를 Windows에 새로 풀었을 때 시작됐다.</p>
<p>파일 내용은 그대로인데 <code>grep -c $'\r'</code>로 세어 보니 <code>build.mjs</code> · <code>src/styles.css</code> 같은 원본에 <code>CR</code> 문자가 섞여 있었다. git이 체크아웃하면서 줄 끝을 <code>CRLF</code>(<code>\r\n</code>, <code>0x0D 0x0A</code>)로 바꿔 놓은 것이다.</p>
<p>이대로 구우면 해시가 틀어진다. 이유는 빌드 도구와 HTML 파서가 같은 글자를 다르게 읽기 때문이다.</p>
<ol><li>Windows에서 편집하거나 체크아웃한 파일에 <code>\r\n</code>이 섞여 들어가면, 빌드 스크립트의 <code>crypto.createHash('sha256').update(s)</code>는 <code>\r</code>(<code>0x0D</code>) 바이트까지 그대로 포함해 해시를 계산한다.</li><li>반면 웹 브라우저의 HTML 파서는 WHATWG HTML 명세(Preprocessing the input stream)에 따라 네트워크로 받은 바이트 스트림에서 모든 <code>\r\n</code>과 단독 <code>\r</code>을 먼저 <code>\n</code>(<code>0x0A</code>, LF)으로 바꾼 뒤 DOM 트리를 만든다.</li><li>브라우저의 CSP 검사기는 그렇게 정규화가 끝난(<code>&lt;style&gt;</code> · <code>&lt;script&gt;</code> 안의 <code>\r</code>이 모두 제거된) 문자열을 기준으로 SHA-256 해시를 계산한다.</li></ol>
<p>결국 인라인 블록 안에 <code>CR</code>이 1바이트라도 남으면 빌드 도구가 계산한 해시(<code>\r\n</code> 기준)와 브라우저가 계산한 해시(<code>\n</code> 기준)가 달라져 스타일이나 스크립트가 통째로 막힌다. 화면이 깨진 채 배포되기 전에 찾았으니 운이 좋았던 편이다.</p>
<p>같은 일이 다시 생기지 않게 세 가지를 고정했다.</p>
<ul><li>저장소 루트에 <code>.gitattributes</code> 파일을 만들고 <code>* text=auto eol=lf</code>와 바이너리 확장자(<code>*.png</code>, <code>*.webp</code>, <code>*.jpg</code>, <code>*.ico</code>, <code>*.woff2</code>)를 지정해 Windows에서도 모든 텍스트 파일이 <code>LF</code>로만 체크아웃되도록 고정했다(커밋 <code>2c3acc0</code>). 그다음 파일을 지우고 <code>git checkout-index --all</code>로 다시 풀었다.</li><li><code>build.mjs</code>는 스크립트(<code>src/main.js</code>)의 주석 줄을 지우고 <code>\n</code> 뒤 공백까지 걷어 한 줄로 만든 뒤 해시를 낸다. CSS(<code>src/styles.css</code> · <code>src/blog.css</code>)도 <code>minCss()</code>로 줄인 문자열을 해싱한다.</li><li><code>test/check.mjs</code>에 <code>!h.includes(String.fromCharCode(13))</code> 검사를 넣었다(커밋 <code>ea26d20</code>, 지금은 29줄). 구운 HTML 파일(<code>dist/*.html</code>) 어디에든 <code>CR</code> 문자(<code>0x0D</code>, ASCII 13)가 단 1바이트라도 섞여 있으면 빌드가 즉시 실패한다.</li></ul>
<h2>Cloudflare 분석 스크립트 주입과 차단</h2>
<p>두 번째 문제는 2026년 11월 11일 첫 판(<code>ba41fb7d</code>)을 실제 도메인(<code>kavotin.com</code>)에 올린 직후에 일어났다.</p>
<p>로컬에서 구운 파일을 헤드리스 크롬으로 열었을 때는 390폭과 1440폭 모두 콘솔 오류가 0건이었다.</p>
<p>그런데 Cloudflare Workers에 배포한 뒤 실제 주소(<code>https://kavotin.com/</code>)를 열자 브라우저 콘솔에 CSP 차단 오류가 1건 찍혔고, 로컬 빌드본과 배포본이 일치하는지 확인하는 라이브 검사까지 실패했다.</p>
<p>실제 서버가 내려준 HTML 응답 본문을 뜯어보니, 우리가 구운 <code>&lt;/body&gt;</code> 바로 앞에 로컬에는 없던 <code>&lt;script&gt;</code> 태그 하나가 끼워져 있었다.</p>
<p>Cloudflare 대시보드의 Web Analytics(RUM, 실제 사용자 모니터링) 기능이 켜져 있으면, Cloudflare 프록시가 HTML 응답을 내보낼 때 자동으로 <code>https://static.cloudflareinsights.com/beacon.min.js</code> 스크립트 태그를 주입한다. 그리고 이 스크립트가 브라우저에서 돌면서 <code>/cdn-cgi/rum</code> 경로와 <code>https://cloudflareinsights.com</code>으로 방문 통계 비콘(<code>connect-src</code>)을 보낸다.</p>
<p>우리의 초기 CSP 헤더는 <code>default-src 'none'</code>에 우리가 구운 인라인 해시만 열어 두었기 때문에, Cloudflare가 스스로 끼워 넣은 외부 스크립트도 막히고 비콘 전송 요청도 막힌 것이다.</p>
<p>해결 방법은 두 단계였다.</p>
<p>표의 「스크립트」는 <code>script-src</code>, 「비콘 전송」은 <code>connect-src</code>, 「배포본 대조」는 <code>test/check.mjs</code>의 <code>--live</code> 검사다.</p>
<p>처음 검사는 <code>body === html</code>로 문자열을 그대로 비교했다.</p>
<div class="tbl"><table><thead><tr><th>무엇</th><th>처음</th><th>고친 뒤</th></tr></thead><tbody><tr><td>스크립트</td><td>해시만</td><td>해시 + 분석 스크립트 주소</td></tr><tr><td>비콘 전송</td><td>막힘</td><td><code>'self'</code> + 분석 주소</td></tr><tr><td>배포본 대조</td><td>그대로 비교</td><td>분석 태그 빼고 비교</td></tr></tbody></table></div>
<p>먼저 <code>build.mjs</code>의 <code>csp()</code> 함수에서 <code>script-src</code>에 <code>https://static.cloudflareinsights.com</code>을 더하고 <code>connect-src 'self' https://cloudflareinsights.com</code>을 열었다. 다시 배포하자 실제 주소의 콘솔 오류가 즉시 0건으로 내려갔다.</p>
<p>그다음 배포 검증 도구인 <code>test/check.mjs</code>의 <code>--live</code> 검사에서는 로컬 <code>dist/index.html</code>과 실서버 응답 본문을 비교할 때 Cloudflare가 끼워 넣은 분석 스크립트 줄만 정규식으로 걷어내고 비교하도록 <code>flat</code> 함수를 작성했다.</p>
<pre><code>const flat = (s) =&gt;
  s.replace(/&lt;script[^&gt;]*cloudflareinsights[^&gt;]*&gt;&lt;\/script&gt;|&lt;!--[\s\S]*?--&gt;/g, '')
   .replace(/\s+/g, ' ');
ok(flat(body) === flat(html), '올라간 첫 화면이 구운 것과 같다(Cloudflare 방문 셈 스크립트는 뺀다)');</code></pre>
<h2>빌드 뒤 자동 검사 734개 항목</h2>
<p>11월 20일 기준 <code>test/check.mjs</code>는 로컬 빌드 직후 734개 항목을 검사한다. <code>--live https://kavotin.com</code> 옵션을 주면 실서버 응답 검사가 그 뒤에 더 붙는다.</p>
<p>그중 CSP 및 바이트 무결성과 관련된 핵심 검사 항목은 다섯 가지다.</p>
<ol><li>구운 모든 HTML 파일에 <code>CR</code> 문자(<code>String.fromCharCode(13)</code>)가 0개인지 확인한다.</li><li>실서버 첫 화면 응답 헤더의 <code>content-security-policy</code>에 <code>default-src 'none'</code>이 포함되어 있는지 확인한다.</li><li>실서버가 내려준 첫 화면과 제품 소개 페이지 4곳(<code>/about/oncall</code>, <code>/about/cloudline</code>, <code>/about/hongsil</code>, <code>/about/karyon</code>) 등의 HTML이 Cloudflare 분석 스크립트를 제외하고 로컬 빌드본과 글자 하나까지 일치하는지 대조한다.</li><li>첫 화면 전체 무게(HTML + 글꼴 두 벌 + 첫 화면 그림)가 230KB 상한 아래(11월 20일 빌드 219.2KB)인지 확인한다. 인라인 CSS가 커질수록 여기에 먼저 걸린다.</li><li>헤드리스 크롬으로 실제 주소를 390폭과 1440폭으로 열었을 때 <code>console.error</code>와 <code>pageerror</code>가 0건인지 확인한다.</li></ol>
<p>저는 정적 사이트에 CSP를 걸면서 귀찮다는 이유로 <code>unsafe-inline</code>을 열어 두면 CSP를 쓰는 의미가 반감된다고 본다. 빌드 스크립트에서 SHA-256 해시를 자동으로 뽑아 <code>_headers</code>에 적고, Windows의 <code>CRLF</code> 줄바꿈과 호스팅 프록시가 주입하는 스크립트 두 가지만 테스트 코드로 고정해 두면 <code>unsafe-inline</code> 없이도 인라인 최적화와 보안을 둘 다 챙길 수 있다.</p>]]></content:encoded></item>
<item><title>AI 코딩 세션이 끊겨도 작업 이어받는 법</title><link>https://kavotin.com/blog/ai-session-handoff</link><guid isPermaLink="true">https://kavotin.com/blog/ai-session-handoff</guid><pubDate>Wed, 18 Nov 2026 00:00:00 GMT</pubDate><category>AI와 일하기</category><description>「대화창이 꺼지면 하던 코딩도 다 날아갈까?」 19분 만에 상한으로 끊긴 세션을 11분 뒤 이어받아 마친 기록.</description><content:encoded><![CDATA[<p>AI 에이전트에게 큰 기능을 맡겼는데 한창 파일을 고치던 도중에 비용 한도나 시간 상한에 걸려 세션이 뚝 끊기면 어떻게 될까?</p>
<p>보통 채팅창 안에서 대화를 주고받으며 코딩을 시키면 세션이 꺼지는 순간 이전 대화 맥락(Context window)이 함께 증발한다.</p>
<p>새로 열린 세션은 앞선 세션이 왜 그 파일들을 열어 두었는지, 어디까지 시험했고 무엇이 남았는지 알지 못해 처음부터 코드를 다시 짜거나 건드리지 말아야 할 파일을 덮어쓴다.</p>
<p>카보틴 스튜디오의 웹사이트와 게임은 이 문제를 막으려고 모든 작업 기억을 모델의 대화창 밖인 디스크 파일과 Git 상태에 남기는 규칙을 쓴다.</p>
<p>2026년 11월 15일 실제로 이 블로그 틀(<code>blog.mjs</code> · <code>src/blog.css</code>)을 만들면서 세 번 연속으로 비용 상한에 걸려 세션이 끊겼던 실행 기록과, 다음 세션이 11분 만에 현장을 복원해 작업을 끝낸 구조를 정리한다.</p>
<h2>19분 만에 끊긴 세션과 9개의 파일</h2>
<p>2026년 11월 15일 오후 2시 23분(한국 시각, 05:23:12 UTC), 공식 홈 저장소에 블로그와 안내 페이지 세 곳(소개 · 문의 · 개인정보처리방침)을 추가하는 첫 번째 세션(<code>#1446-0</code>)이 켜졌다.</p>
<p>이 세션은 Git 작업 트리(<code>site-blog</code>, 브랜치 <code>blog</code>)를 새로 가르고 마크다운 파서와 RSS 생성기, 이미지 리사이즈 파이프라인을 작성하기 시작했다.</p>
<p>그러나 오후 2시 42분 41초, 시작한 지 정확히 19분(57턴) 만에 누적 API 호출 비용이 $4.7175(약 $4.72)에 도달했다. 세션당 비용 상한($4.64)을 넘기면서 프로세스가 종료 코드 <code>1</code>로 강제 중단되었다.</p>
<p>세션이 끊긴 직후 디스크에 남아 있던 흔적은 아래와 같았다.</p>
<ul><li><code>work/site-blog</code> 폴더: 아직 커밋되지 않은 파일 9개(<code>.gitattributes</code>, <code>blog.mjs</code> 234줄, <code>build.mjs</code>, <code>src/blog.css</code> 99줄, <code>src/pages/about.md</code> 38줄, <code>src/pages/contact.md</code> 27줄, <code>src/pages/privacy.md</code> 56줄, <code>src/styles.css</code>, <code>tools/blog-images.py</code> 31줄, 총 +513줄 / -8줄)</li><li><code>work/o1446-hooks.py</code>: 기존 <code>build.mjs</code>와 <code>src/styles.css</code>에 블로그 빌드 호출을 끼워 넣으려고 작성한 46줄짜리 파이썬 패치 스크립트</li><li>진행 장부(<code>progress.md</code>)와 기억 노트(<code>notes.md</code>): 세션이 마지막 정리 단계에 들어가기 전에 잘렸기 때문에 새 기록 0줄</li></ul>
<p>만약 다음 세션이 아무 규칙 없이 빈 프롬프트로 켜졌다면 커밋되지 않은 파일 9개를 미완성 조각으로 여겨 <code>git checkout -- .</code>으로 날려 버렸거나, 이미 만들어진 <code>blog.mjs</code> 위에 또 다른 빌드 스크립트를 덧대었을 것이다.</p>
<p>하지만 11분 뒤인 오후 2시 53분 12초에 자동으로 켜진 두 번째 세션(<code>#1446-1</code>)은 단 3분 만에 앞 세션의 작업을 검증하고 오후 2시 56분 1초에 첫 커밋(<code>2c3acc0</code>)을 남겼다.</p>
<h2>기억을 프롬프트 밖 디스크로 빼는 법</h2>
<p>세션이 예고 없이 죽어도 다음 세션이 길을 잃지 않는 이유는 작업 공간마다 네 가지 파일 규칙을 강제하기 때문이다.</p>
<h3>조각 단위 커밋과 패치 스크립트</h3>
<p>가장 중요한 원칙은 작업 전체가 끝날 때까지 커밋을 미루지 않는 것이다.</p>
<p>기능 조각 하나가 빌드(<code>node build.mjs</code>)와 자동 검사(<code>node test/check.mjs</code>), 브라우저 콘솔 오류 0건 확인을 통과할 때마다 즉시 Git 커밋을 남긴다.</p>
<p>세션이 시작되면 어떤 파일도 고치기 전에 무조건 <code>git status</code>와 <code>git log -n 5</code>, 그리고 수정된 파일의 타임스탬프부터 확인한다.</p>
<p>1차 세션(<code>#1446-0</code>)은 비록 커밋 직전에 끊겼지만, 기존 파일을 손으로 어설프게 고치는 대신 <code>work/o1446-hooks.py</code>라는 멱등성 있는 패치 스크립트를 파일로 남겨 두었다.</p>
<pre><code>def rep(a, b, n=1):
    global s
    assert s.count(a) == n, (a, s.count(a))
    s = s.replace(a, b)</code></pre>
<p>이 스크립트는 치환할 대상 문자열(<code>a</code>)이 원본 파일에 정확히 <code>n</code>번 존재하는지 <code>assert</code>로 먼저 검사한다.</p>
<p>덕분에 이어받은 2차 세션(<code>#1446-1</code>)은 <code>o1446-hooks.py</code>와 <code>git diff</code>만 읽고도 앞 세션이 <code>build.mjs</code>의 어느 지점까지 연결했는지 1분 안에 파악했다.</p>
<h3>다음 할 일 한 줄과 종료 신호 파일</h3>
<p>대화 히스토리는 세션이 닫히면 사라지므로, 모든 상태는 두 개의 마크다운 파일에 나누어 적는다.</p>
<ol><li><code>notes.md</code> 맨 위 「다음에 할 것」: 다음 세션이 켜지자마자 첫 턴에 읽는 자리다. 추상적인 목표가 아니라 실제로 열어야 할 파일 경로, 줄 번호, 실행할 검사 명령을 적는다.</li><li><code>work/progress.md</code>: 각 단계가 끝날 때마다 통과한 검사 항목 수(예: <code>534/534</code>), 첫 화면 무게(예: <code>218.4KB</code>), 배포된 Worker 버전 ID, 화면 갈무리 저장 경로를 적는다.</li></ol>
<p>또한 외부 실행기는 세션의 토큰 사용량이나 시간이 상한에 가까워지면 작업 폴더에 <code>work/STOP-SOON</code>이라는 빈 파일을 만든다.</p>
<p>에이전트는 조각 하나를 마칠 때마다 이 파일이 있는지 확인하고, 파일이 보이면 새 일을 벌이지 않고 즉시 하던 조각을 커밋한 뒤 세션을 닫는다. 대화 턴 수가 80턴을 넘었을 때도 맥락이 흐려지는 것을 막기 위해 그 자리에서 정리하고 닫는다.</p>
<p>세션의 마지막 응답 맨 끝에는 반드시 기계가 파싱할 수 있는 고정 형식의 상태 줄(<code>상태: 끝 | 막힘 | 이어서</code>)을 적는다.</p>
<p>만약 비용 상한이나 오류로 프로세스가 중간에 죽어 이 상태 줄이 출력되지 않으면, 실행기는 해당 세션을 「끊김」으로 기록하고 다음 세션을 자동으로 대기열에 넣는다.</p>
<h3>본체 저장소와 작업 브랜치 분리</h3>
<p>카보틴 스튜디오 홈 본체 저장소(<code>work/site</code>, <code>master</code> 브랜치)에는 1시간마다 실험 장부를 확인해 통과한 도구를 자동으로 홈 목록에 올리고 배포하는 감시 스크립트(<code>watch.mjs</code>)가 돈다.</p>
<p>만약 감시 스크립트가 도는 순간에 <code>work/site</code> 폴더 안에 커밋되지 않은 수정 파일이 남아 있으면, 감시 스크립트는 다른 작업이 진행 중인 것으로 판단해 자동 배포를 건너뛴다. 반대로 긴 작업을 하다가 세션이 끊기면 본체 배포 파이프라인 전체가 멈추게 된다.</p>
<p>그래서 블로그처럼 시간이 걸리는 작업은 <code>git worktree</code>로 분리한 <code>work/site-blog</code>(<code>blog</code> 브랜치)에서만 진행한다.</p>
<p>세션이 중간에 끊겨 커밋 안 된 파일이 남더라도 본체 <code>work/site</code>는 항상 깨끗한 상태를 유지한다. <code>blog</code> 브랜치에서 모든 검사를 통과하고 커밋이 끝났을 때만 본체 폴더의 <code>git status --short</code>가 비어 있는지 확인한 뒤 <code>git merge --ff-only blog</code>로 합쳐 배포한다.</p>
<h2>네 번의 세션으로 완성한 블로그 틀</h2>
<p>2026년 11월 15일 실행 장부(<code>runs.jsonl</code>)에 기록된 블로그 틀 제작과 개편 과정의 네 세션 수치는 아래와 같다.</p>
<div class="tbl"><table><thead><tr><th>세션 기록</th><th>시작 시각 (KST)</th><th>실행 시간 · 턴</th><th>비용 (상한)</th><th>종료 상태와 남은 결과</th></tr></thead><tbody><tr><td>1차 (<code>#1446-0</code>)</td><td>14:23:12</td><td>19분 · 57턴</td><td>$4.72 ($4.64)</td><td>상한 초과로 끊김. <code>site-blog</code>에 미커밋 9파일(+513/-8줄)과 <code>o1446-hooks.py</code> 남김</td></tr><tr><td>2차 (<code>#1446-1</code>)</td><td>14:53:12</td><td>8분 · 36턴</td><td>$3.09 ($3.00)</td><td>앞 세션 파일 검증 후 커밋 <code>2c3acc0</code> 생성, 글꼴 5종 측정 및 <code>blog-plan.md</code> 작성 뒤 끊김</td></tr><tr><td>3차 (<code>#1447-0</code>)</td><td>15:33:12</td><td>21분 · 31턴</td><td>$2.71 ($2.69)</td><td>외부 블로그 스킨 8종 치수 측정(<code>blog-ref.mjs</code>), 설계서 12절 작성, CSS 개편 중 끊김</td></tr><tr><td>4차 (<code>#1447-1</code>)</td><td>16:13:11</td><td>6분 · 50턴</td><td>$1.83 (통과)</td><td>목록 · 옆칸 300px · 본문 720px · 차례 · 미리보기 완성, 커밋 <code>4b77965</code>, 검사 534/534 통과</td></tr></tbody></table></div>
<p>2차 세션은 1차 세션이 남긴 9개 파일을 이어받아 3분 만에 커밋 <code>2c3acc0</code>으로 고정했다.</p>
<p>그 뒤 첫 번째 글에 쓸 한글 웹폰트 서브셋 측정 스크립트(<code>font-measure.py</code>)를 돌려 수치를 뽑고 <code>work/blog-plan.md</code>에 기록해 둔 채 비용 상한($3.00)으로 끊겼다.</p>
<p>이어서 블로그 화면 배치를 다듬는 작업(<code>#1447</code>)에서도 첫 세션(<code>#1447-0</code>)이 <code>robots.txt</code> 허용 여부를 먼저 확인한 뒤 티스토리 스킨 3종(Odyssey · Book Club · Poster)과 Blogger 테마 4종(Contempo · Soho · Emporio · Notable), 브런치 1곳의 폭과 글자 크기를 헤드리스 크롬으로 측정했다.</p>
<p>이 치수를 설계서 12절에 적고 코드를 고치다가 21분 만에 상한($2.69)으로 다시 끊겼다.</p>
<p>하지만 19분 뒤에 켜진 4차 세션(<code>#1447-1</code>)이 이미 고쳐져 있던 한 줄 목록과 8편 쪽 넘김, 300px 옆칸 코드 위에 글 끝 차례와 미리보기 환경변수(<code>KV_BLOG</code>)를 마저 붙였다.</p>
<figure><img src="https://kavotin.com/img/b-blog-list-live-1200.63c83df7.jpg" width="1200" height="750" alt="네 번의 세션을 거쳐 완성된 카보틴 스튜디오 블로그 목록 화면"><figcaption>네 번의 AI 세션을 이어 달려서 완성한 블로그 목록 화면(1440폭). 왼쪽 720px 본문 칸에 한 줄 한 편 목록이 들어가고 오른쪽 300px 옆칸에 스튜디오 소개와 분류, 최근 글이 배치된다.</figcaption></figure>
<p>4차 세션은 테스트 과정에서 블로그 옆칸 클래스 이름(<code>.rail</code>)이 홈페이지 가로 카드 줄의 클래스 이름(<code>.rail</code>)과 겹쳐 레이아웃이 찌그러지는 결함까지 찾아내 <code>.b-rail</code>로 분리했다.</p>
<p>그렇게 16장의 화면 갈무리(가로 넘침 0 · 콘솔 오류 0)와 534개 자동 검사를 모두 통과하고 커밋 <code>4b77965</code>로 작업을 끝냈다.</p>
<p>세 번이나 중간에 프로세스가 잘렸지만, 네 세션이 쓴 총 시간은 54분(비용 합계 $12.35)이었고 단 한 줄의 코드도 중복해서 다시 짜지 않았다.</p>
<p>저는 AI 에이전트로 긴 개발 작업을 자동화할 때 한 번에 끝내는 거대한 프롬프트를 짜는 것보다 언제 끊겨도 다시 이어 달릴 수 있는 디스크 상태 규칙을 만드는 편이 훨씬 중요하다고 본다.</p>
<p>작업 트리를 분리하고, 작은 조각마다 검사 후 커밋하며, 다음 세션이 읽을 첫 줄을 파일 맨 위에 남겨 두면 세션 시간이나 비용 상한은 더 이상 장애물이 되지 않는다.</p>]]></content:encoded></item>
<item><title>Cloudflare 무료로 3D 멀티플레이 게임 서버 돌리기</title><link>https://kavotin.com/blog/oncall-free-tier</link><guid isPermaLink="true">https://kavotin.com/blog/oncall-free-tier</guid><pubDate>Tue, 17 Nov 2026 00:00:00 GMT</pubDate><category>게임 만들기</category><description>「서버비 0원으로 실시간 3D 로비가 돌아갈까?」 Durable Objects 한도 계산과 아이폰 5G 60프레임 실측.</description><content:encoded><![CDATA[<p>웹 브라우저에서 바로 열리는 3D 멀티플레이 게임을 만들 때 고정 서버비를 0원으로 맞출 수 있을까?</p>
<p>보통 실시간 멀티플레이 서버는 접속자가 없어도 24시간 내내 프로세스를 띄워 두어야 해서 매달 고정 인스턴스 비용이 나간다.</p>
<p>카보틴 스튜디오의 3D 웹 병원 게임 <a href="https://oncall.kavotin.com/?ref=kavotin" rel="noopener">온콜</a>은 이 고정비를 없애려고 Cloudflare Workers와 Durable Objects의 무료 등급(Free tier)만으로 실시간 서버를 구성했다.</p>
<p>브라우저가 내려받는 클라이언트 번들은 외부 3D 모델 파일 없이 코드만으로 병원과 캐릭터를 그려 초기 gzip 152KB(로비 소품 개편 뒤 183.3KB~186.0KB)에 담았고, 서버는 방에 움직임이 없으면 즉시 잠들도록 짰다.</p>
<p>2026년 11월 4일부터 11월 15일까지 공식 요금 문서와 서버 코드를 대조하며 계산한 무료 한도 수치, 초기 계산에서 놓쳤던 과금 비율 함정, 그리고 실제 아이폰 5G 환경에서 잰 프레임 수치를 정리한다.</p>
<h2>하루 10만 요청과 동시 접속 계산</h2>
<p>2026년 10월 18일 판 Cloudflare 공식 문서를 11월 15일에 다시 대조해 확인한 무료 등급의 일일 한도는 세 가지다. 매일 00:00 UTC(한국 시각 오전 9시)에 초기화된다.</p>
<ul><li>하루 요청(Requests): 100,000건(정적 자산 요청은 무료 무제한)</li><li>하루 지속 시간(Duration): 13,000 GB-s</li><li>하루 저장소 쓴 줄(SQLite rows written): 100,000줄</li></ul>
<p>실시간 위치 동기화에서 가장 먼저 바닥나는 자원은 요청 수다. 일반적인 액션 게임처럼 초당 20~60번씩 좌표를 보내면 한 사람이 몇 분만 걸어도 수천 건의 메시지가 발생한다.</p>
<p>온콜은 병원 로비와 병동을 걸어 다니며 말풍선과 몸짓을 나누는 공간이므로 위치 전송 빈도를 움직일 때만 초당 3번(3Hz), 멈춰 있을 때는 0번으로 정했다.</p>
<p>2026년 11월 4일 로컬 측정(<code>check-gpu.json</code>)에서 캐릭터가 약 2.7초 동안 걸을 때 서버로 보낸 위치 메시지는 10번이었고, 3초 동안 멈춰 서 있을 때는 0번이었다. 걷는 속도는 초당 4.2m여서 메시지 사이 간격은 약 1.4m지만, 다른 사람의 화면에서는 선형 보간으로 이어 그리고 멈춘 뒤 최종 위치 차이는 0.4m 안쪽으로 들어온다.</p>
<p>시점 전환 결함을 고친 뒤 다시 확인했을 때도 제자리에서 고개만 돌릴 때는 1인칭과 3인칭 모두 위치 전송이 0번이었고, 3초 동안 12.7m를 걸을 때만 9번 전송되었다.</p>
<p>공식 문서 각주에는 들어오는 WebSocket 메시지 20개를 요청 1건으로 계산한다(<code>&quot;For compute requests billing-only, a 20:1 ratio is applied to incoming WebSocket messages&quot;</code>)고 적혀 있고, 서버에서 나가는 메시지는 무료다.</p>
<p>접속자가 머무는 시간의 40% 동안 움직인다는 가정(실측이 아닌 설계 가정)으로 계산한 자원 소모량은 아래와 같다.</p>
<div class="tbl"><table><thead><tr><th>항목</th><th>산식과 기준</th><th>하루 무료 한도 대비</th></tr></thead><tbody><tr><td>1인 1시간 메시지</td><td>3Hz × 3,600초 × 0.4 = 4,320개 + 핑 72개 = 4,392개</td><td>20:1 적용 시 219.6 요청</td></tr><tr><td>1인 30분 체류</td><td>메시지 2,196개 + 첫 연결 1건</td><td>20:1 적용 시 약 111 요청</td></tr><tr><td>하루 수용 시간 (20:1 기준)</td><td>100,000 요청 ÷ 219.6 요청</td><td>하루 455 사람·시간 (30분씩 910명)</td></tr><tr><td>지속 시간 (Duration)</td><td>86,400초 × 0.128GB = 11,059 GB-s</td><td>방 1개 종일 깨어 있어도 한도의 85%</td></tr><tr><td>저장소 쓴 줄</td><td>1,000 메시지마다 1줄 + 입장·퇴장 기록</td><td>455 사람·시간(200만 메시지)에 약 2,000줄</td></tr></tbody></table></div>
<p>만약 전송 빈도를 5Hz로 올리면 같은 무료 한도로 감당하는 시간이 455 사람·시간에서 273 사람·시간으로 줄어든다.</p>
<p>반면 지속 시간(Duration)은 Durable Object 방 하나가 128MB(0.128GB) 메모리를 쓰므로, 24시간(86,400초) 내내 단 1초도 쉬지 않고 깨어 있어도 11,059 GB-s가 되어 하루 한도(13,000 GB-s)를 넘지 못한다. 전체 지속 시간 한도를 시간으로 환산하면 하루 28.2 방·시간이므로, 나중에 병동을 여러 개로 늘릴 때만 지속 시간이 병목이 된다.</p>
<h2>잠드는 웹소켓과 150ms 묶음 전송</h2>
<p>지속 시간과 요청 수를 아끼는 핵심은 Durable Objects의 Hibernation WebSocket API다.</p>
<p>서버 생성자(<code>constructor</code>)에서 <code>ctx.setWebSocketAutoResponse(new WebSocketRequestResponsePair('p', 'q'))</code>를 등록해 두면, 클라이언트가 연결 유지를 위해 50초마다 보내는 핑(<code>p</code>)에 대해 Cloudflare 가장자리 서버가 객체를 깨우지 않고 자동으로 <code>q</code>를 돌려준다.</p>
<p>방 안에 사람이 접속해 있어도 아무도 걷지 않으면 서버 타이머가 돌지 않으므로 방 객체는 메모리에서 잠들고 지속 시간 요금이 전혀 나가지 않는다.</p>
<p>누군가 걸음을 옮겨 위치 메시지(<code>[x, z, 각도]</code> 또는 앉은 자세를 포함한 4칸 정수 배열)가 들어오면 그때만 <code>webSocketMessage</code>가 깨어난다. 이때도 들어온 좌표를 즉시 모든 사람에게 뿌리지 않고 <code>this.dirty</code> 맵에 덮어써 둔 뒤 <code>TICK_MS = 150</code>ms 간격으로 한 번에 묶어서 내보낸다.</p>
<pre><code>const MAX_PEOPLE = 40;
const TICK_MS = 150;
const SAVE_IDLE_MS = 5_000;
const DEAD_MS = 180_000;
const MSGS_PER_REQUEST = 1;
const hzFor = (used) =&gt; (used &lt; 50_000 ? 3 : used &lt; 80_000 ? 2 : 1);
const REFUSE_AT = 95_000;</code></pre>
<p>150ms마다 실행되는 <code>flush()</code> 함수는 모인 좌표 목록에서 보낸 사람 본인의 좌표는 빼고 전송하며, 방에 혼자만 있을 때는 아예 패킷을 보내지 않는다.</p>
<p>모든 사람이 멈추면 <code>this.timer</code>를 다시 걸지 않아 방은 곧바로 휴면 상태로 돌아간다.</p>
<p>또한 브라우저 탭을 다른 곳으로 돌리거나 화면을 내려 둔 사람이 연결을 계속 붙잡고 있지 않도록 숨김 타이머를 두었다. 2026년 11월 5일 로컬 시험(<code>net-check.mjs hide</code>)에서 탭을 숨긴 뒤 4분 40초까지는 방에 남아 있다가 300.2초(5분)에 닫힘 코드 1000으로 연결을 끊었고, 탭으로 다시 돌아왔을 때는 82ms 만에 재연결되어 원래 좌표 <code>(3, 4)</code>와 인턴 직급을 그대로 복구했다. 10초 만에 돌아온 경우에는 연결을 끊지 않고 새 연결 0건으로 이어졌다.</p>
<p>네트워크가 비정상적으로 끊겨 닫힘 이벤트가 오지 않는 유령 연결은 마지막 자동 응답 시각(<code>getWebSocketAutoResponseTimestamp</code>)을 기준으로 180,000ms(3분)가 지나면 코드 <code>4002</code>로 정리한다.</p>
<h2>20 대 1 과금 비율의 함정과 감속</h2>
<p>처음 서버를 배포한 뒤 코드를 다시 점검하다가 치명적인 허점을 하나 발견했다.</p>
<p>공식 문서의 20:1 비율 각주는 <code>&quot;For compute requests billing-only&quot;</code>라고만 적혀 있다. 유료 요금제의 과금 계산에서 20개를 1건으로 쳐 준다는 뜻이지, 무료 등급의 일일 10만 한도 차단기에도 똑같이 20:1이 적용되는지는 문서만으로 확신할 수 없었다. 게다가 대시보드 분석 화면의 숫자는 20:1 할인 없이 실제 메시지 개수로 찍힌다.</p>
<p>초기 코드에서는 들어온 메시지 수를 20으로 나누어(<code>msgs / 20</code>) 하루 사용량을 추정하고, 그 추정치가 5만이면 2Hz, 8만이면 1Hz로 클라이언트의 전송 빈도를 늦추도록 짰다.</p>
<p>문제는 만약 무료 한도에 20:1이 적용되지 않을 경우다. 실제로는 들어온 메시지가 10만 개에 도달해 Cloudflare가 무료 한도 초과 오류를 내며 서버를 막아 버리는데도, 우리 코드가 계산한 추정치는 5,000(<code>100,000 ÷ 20</code>)에 불과해 2Hz 감속도, 1Hz 감속도, 9.5만 신규 연결 차단도 단 하나도 켜지지 않은 채 서버가 죽게 된다.</p>
<p>그래서 작업 <code>#187</code>에서 <code>MSGS_PER_REQUEST = 1</code>로 상수를 바꾸어 들어온 메시지를 1:1로 보수적으로 세도록 고쳤다.</p>
<ul><li>하루 누적 사용량(연결 수 + 들어온 메시지 수) 50,000 미만: 기본 3Hz 전송</li><li>누적 사용량 50,000 이상 ~ 80,000 미만: 방 전체에 <code>{ t: 'hz', hz: 2 }</code>를 방송해 2Hz로 감속</li><li>누적 사용량 80,000 이상 ~ 95,000 미만: <code>{ t: 'hz', hz: 1 }</code>을 방송해 1Hz로 감속</li><li>누적 사용량 95,000(<code>REFUSE_AT</code>) 이상 또는 방 정원 40명(<code>MAX_PEOPLE</code>) 도달: 새 접속자에게 <code>{ t: 'full' }</code>을 보내고 닫힘 코드 <code>4001</code>로 정중히 안내</li></ul>
<p>이렇게 1:1로 세면 만약 Cloudflare가 실제로는 20:1을 적용해 주고 있을 때 하루 무료 한도의 5%만 쓰고도 보호 장치가 일찍 켜지는 대가를 치른다. 40% 이동 가정으로 계산하면 3Hz 구간 11.4 사람·시간, 2Hz 구간 10.2 사람·시간, 1Hz 구간 9.9 사람·시간을 합쳐 하루 약 31.5 사람·시간에서 신규 입장을 멈추게 된다.</p>
<p>하지만 예고 없이 서버가 500 오류를 뱉으며 먹통이 되는 것보다, 한도 직전에 스스로 빈도를 줄이고 정원 안내 화면을 띄우는 쪽이 훨씬 안전하다. 실제 트래픽이 쌓인 날 대시보드 숫자와 한도 오류 여부를 대조해 20:1 적용이 확인되면 그때 상수를 <code>20</code>으로 올리면 된다.</p>
<h2>저장소 쓰기 절약과 악성 패킷 차단</h2>
<p>Durable Objects의 SQLite 저장소 쓰기 한도(하루 10만 줄)를 지키려고 실시간 좌표는 디스크에 한 줄도 쓰지 않는다. 각 접속자의 현재 좌표와 직급, 별명 번호는 WebSocket 객체에 붙이는 메모리 꼬리표(<code>serializeAttachment</code>)에만 담아 둔다.</p>
<p>디스크(<code>ctx.storage.kv</code>)에 쓰는 것은 하루 사용량과 익명 방문 통계를 합친 <code>use</code> 키 한 줄뿐이다. 이마저도 메시지가 올 때마다 쓰면 10만 줄 한도가 금방 닳기 때문에 두 가지 조건에서만 저장한다.</p>
<ol><li>마지막으로 저장한 시점부터 들어온 메시지가 1,000개(<code>this.use.msgs - this.saved &gt;= 1000</code>) 쌓였을 때 한 번 쓴다.</li><li>마지막 메시지 뒤 5,000ms(<code>SAVE_IDLE_MS</code>) 동안 추가 메시지가 없으면 타이머로 한 번 쓴다. 약 10초 뒤 방이 휴면 상태로 들어가 메모리가 비워지기 전에 마지막 숫자를 디스크에 남기기 위해서다.</li></ol>
<p>또한 무료 한도를 악의적으로 소모하는 연결을 막으려고 패킷 규격을 엄격하게 좁혔다.</p>
<p>온콜에는 자유 텍스트 채팅이 없다. 말풍선과 몸짓, 직급, 별명, 외모 조합은 모두 미리 정해진 번호표의 정수 ID만 주고받는다.</p>
<p><code>webSocketMessage</code>는 들어온 문자열이 40자를 넘거나 JSON 파싱 결과가 유한한 숫자 배열이 아니면 즉시 버린다(다만 버리는 메시지도 Cloudflare 요청 한도를 쓰므로 <code>this.use.msgs++</code> 카운트는 먼저 올린다). 한 연결에서 3,000ms 창 안에 30개(초당 10번, 정상 빈도 3Hz의 세 배 초과)가 넘는 메시지를 보내면 즉시 코드 <code>4003</code>(<code>too fast</code>)으로 연결을 끊는다.</p>
<h2>아이폰 5G 로비 22명 60프레임 실측</h2>
<p>서버가 무료 한도 안에서 최대 40명을 받아 주더라도, 정작 접속자의 스마트폰 브라우저가 여러 명의 3D 캐릭터를 그리느라 멈추면 소용이 없다.</p>
<p>모바일 GPU 부담을 줄이려고 실시간 조명과 그림자 맵 계산을 모두 빼고, 3D 모델을 만들 때 빛과 그늘을 정점 색(Vertex Color)에 미리 구웠다. 캐릭터 밑에는 둥근 그림자 판 하나만 놓는다.</p>
<p>사람 캐릭터는 몸·가운·팔·다리·그림자 판을 합쳐 <code>InstancedMesh</code> 5개(개편 전 7개)로 묶었다. 외모와 표정, 걷거나 손을 뻗을 때의 팔꿈치·무릎 각도는 정점 셰이더(<code>peopleMaterial</code>)에서 계산한다. 쓰지 않는 머리 모양이나 표정 정점은 원점으로 접어 넣기 때문에 화면에 사람이 스무 명으로 늘어나도 GPU 드로콜(그리기 횟수)은 사람 수에 비례해 늘어나지 않는다. 스마트폰 등급 기준 캐릭터 한 명의 삼각형 수는 실습 학생이 약 1,740개, 가운 입은 의사가 약 2,240개다.</p>
<p>개발 PC(Windows, Intel Arc GPU · 360×640 해상도 · CPU 4배 감속)의 헤드리스 크롬과 소프트웨어 렌더러(SwiftShader)만으로는 실제 스마트폰의 체감 속도를 알 수 없었다. SwiftShader는 아무것도 없는 빈 캔버스만 지워도 17.1프레임이 천장이었고, PC GPU는 CPU만 늦춘 상태라 구형 스마트폰보다 낙관적인 숫자가 나왔기 때문이다.</p>
<p>그래서 주소 뒤에 <code>?perf=1</code>을 붙이면 화면 왼쪽 위에 최근 10초 동안의 초당 그림 수(fps), 가장 긴 한 장의 시간(ms), 삼각형 개수, 첫 장 시간, 해상도 배율, 그리기 횟수가 1초마다 갱신되는 검은 측정 판을 만들었다.</p>
<figure class="tall"><img src="https://kavotin.com/img/b-oncall-perf-solo-640.c6518c2a.jpg" width="640" height="1082" alt="아이폰 5G 환경에서 혼자 접속했을 때의 온콜 1층 로비 성능 측정 화면"><figcaption>2026년 11월 6일 아이폰 5G 실측(혼자 있을 때). 해상도 배율 1.5, 삼각형 97,958개, 그리기 60회에서 초당 60.0프레임과 가장 긴 한 장 18ms를 기록했다.</figcaption></figure>
<p>2026년 11월 6일 21시 35분, 실제 아이폰으로 5G 이동통신망에서 <code>oncall.kavotin.com</code> 1층 로비에 접속해 <code>?perf=1</code>로 측정한 결과다.</p>
<p>혼자 서 있을 때는 해상도 배율 1.5에서 최근 10초 평균 초당 그림 <strong>60.0프레임</strong>, 가장 긴 한 장 <strong>18ms</strong>, 삼각형 <strong>97,958개</strong>, 그리기 횟수 <strong>60회</strong>(첫 장 237ms, 그 뒤 최고 91ms)가 나왔다.</p>
<figure class="tall"><img src="https://kavotin.com/img/b-oncall-perf-crowd21-640.c6c330a3.jpg" width="640" height="1082" alt="아이폰 5G 환경에서 가상 캐릭터 21명을 함께 띄웠을 때의 성능 측정 화면"><figcaption>같은 아이폰 5G 환경에서 가운 입은 가상 캐릭터 21명을 함께 띄운 화면(총 22명). 삼각형이 146,797개로 늘었으나 그리기 횟수는 67회에 머물고 초당 60.0프레임(가장 긴 한 장 20ms)을 유지했다.</figcaption></figure>
<p>이어서 로비 한가운데에 가운을 입은 가상 캐릭터 21명(<code>crowd=21</code>, 내 캐릭터를 합쳐 총 22명)을 한꺼번에 띄워 같은 자리에서 다시 쟀다.</p>
<p>화면에 잡힌 삼각형 수는 97,958개에서 <strong>146,797개</strong>로 48,839개(49.9%) 늘어났다. 하지만 인스턴싱 덕분에 그리기 횟수(드로콜)는 60회에서 <strong>67회</strong>로 단 7회만 늘었고, 최근 10초 초당 그림 수는 <strong>60.0프레임</strong>, 가장 긴 한 장은 <strong>20ms</strong>(첫 장 42ms, 그 뒤 최고 33ms)로 혼자 있을 때와 다름없이 유지되었다.</p>
<p>저는 1인 개발자가 멀티플레이 웹 게임을 실험할 때 처음부터 유료 클라우드 서버와 무거운 3D 엔진을 빌릴 필요가 없다고 생각한다. 움직일 때만 3Hz로 보내는 위치 동기화, 150ms 묶음 전송, 잠드는 웹소켓, 그리고 단계별 빈도 감속 장치만 갖추면 서버비 0원으로도 스마트폰 60프레임의 3D 멀티플레이 공간을 충분히 운영할 수 있다.</p>]]></content:encoded></item>
<item><title>한글 웹폰트 용량 줄이는 법: 6.7MB를 26KB로</title><link>https://kavotin.com/blog/hangul-webfont-subset</link><guid isPermaLink="true">https://kavotin.com/blog/hangul-webfont-subset</guid><pubDate>Mon, 16 Nov 2026 00:00:00 GMT</pubDate><category>웹 만들기</category><description>「페이지에 쓴 글자만 잘라 굽기」 Pretendard 다섯 방식 측정 수치와 두 벌 분리 구조.</description><content:encoded><![CDATA[<p>글자 몇 줄과 그림 몇 장만 있는 소개 페이지인데 첫 화면이 왜 2MB를 넘을까?</p>
<p>원인은 대개 그림이 아니라 한글 글꼴 파일이다.</p>
<p>영문 알파벳은 대소문자와 숫자, 문장부호를 다 합쳐도 100자가 안 되지만 한글 완성형 음절(가–힣)은 11,172자다. 글꼴 파일 하나에 만 개가 넘는 글리프 외곽선이 들어간다.</p>
<p>카보틴 스튜디오 공식 홈(<a href="https://kavotin.com/" rel="noopener">kavotin.com</a>)을 만들면서 세운 첫 화면 무게 상한은 230KB였다. HTML과 CSS, 자바스크립트, 첫 화면에 뜨는 제품 그림 여섯 장, 그리고 웹폰트 두 벌을 모두 합친 크기다.</p>
<p>글꼴을 그대로 실으면 첫 화면 예산의 열 배가 글꼴 하나에 다 쓰인다.</p>
<p>이 문제를 풀려고 빌드할 때마다 페이지에 실제로 쓰인 글자만 뽑아 웹폰트를 다시 굽는 파이프라인을 만들었다. 2026년 11월 15일 Windows PC에서 Python <code>fontTools</code>로 직접 잰 수치와 세 번의 개편 동안 겪은 시행착오를 기록한다.</p>
<h2>1. 다섯 방식의 크기와 시간</h2>
<p>본문 글꼴로 고른 것은 오픈소스 글꼴인 Pretendard Variable(<code>PretendardVariable.ttf</code>, OFL)이다.</p>
<p>원본 TTF 파일 크기는 6,739,336바이트(약 6.74MB)이고, 전체 글리프는 14,757개, 한글 완성형 음절은 11,172자가 들어 있다.</p>
<p>2026년 11월 15일 같은 PC에서 <code>fontTools</code>(<code>ttLib</code> · <code>subset</code> · <code>varLib.instancer</code>)로 다섯 가지 방식의 <code>woff2</code> 파일 크기와 굽는 시간을 측정했다.</p>
<div class="tbl"><table><thead><tr><th>굽는 방식</th><th>글자 범위</th><th class="r">woff2 크기</th><th class="r">원본 대비</th><th class="r">굽는 시간</th></tr></thead><tbody><tr><td>가변 글꼴 통째 압축</td><td>14,757글리프 전체</td><td class="r">2,059,396B (2,011.1KB)</td><td class="r">30.6%</td><td class="r">26.6초</td></tr><tr><td>굵기 400 고정 후 통째 압축</td><td>14,757글리프 전체</td><td class="r">751,340B (733.7KB)</td><td class="r">11.1%</td><td class="r">28.3초</td></tr><tr><td>KS X 1001 + ASCII (굵기 400)</td><td>한글 2,350자 + 영문·기호 95자</td><td class="r">160,572B (156.8KB)</td><td class="r">2.38%</td><td class="r">5.9초</td></tr><tr><td>홈·제품 소개에 나온 글자만 (굵기 400)</td><td>357자</td><td class="r">26,156B (25.5KB)</td><td class="r">0.39%</td><td class="r">2.0초</td></tr><tr><td>블로그·안내 추가 글자만 (글 0편 기준)</td><td>98자</td><td class="r">9,228B (9.0KB)</td><td class="r">0.14%</td><td class="r">1.1초</td></tr></tbody></table></div>
<p>가변 글꼴(Variable Font)을 그대로 <code>woff2</code>로 바꾸면 2,059,396바이트(약 2.06MB)다. 여기서 가변 축(<code>wght</code>)을 400 하나로 고정(<code>instantiateVariableFont</code>)하기만 해도 751,340바이트로 63.5%가 줄어든다.</p>
<p>굵기를 두세 개만 쓰는 사이트에서 가변 글꼴을 통째로 내려받게 하는 것은 1.3MB를 그냥 버리는 셈이다.</p>
<p>실무에서 흔히 쓰는 방식은 한글 완성형 가운데 자주 쓰는 KS X 1001 2,350자만 남기는 것이다. 이렇게 자르면 160,572바이트(약 156.8KB)까지 내려간다.</p>
<p>하지만 정적 웹사이트의 첫 화면과 제품 소개 페이지 다섯 곳(<code>index.html</code>, <code>/about/oncall</code>, <code>/about/cloudline</code>, <code>/about/hongsil</code>, <code>/about/karyon</code>, <code>404.html</code>)에 실제로 쓰인 글자를 모두 모아 중복을 빼 보니 357자뿐이었다.</p>
<p>기본 영문 대소문자와 숫자, 문장부호 98자를 미리 합친 숫자가 그만큼이다.</p>
<p>이 357자만 남기고 굵기 400으로 구운 파일은 26,156바이트(25.5KB)다.</p>
<p>가변 <code>woff2</code> 통째 파일과 견주면 78분의 1 크기이고, KS X 1001 서브셋과 견주어도 6분의 1이다.</p>
<h2>2. 홈 개편 세 판과 첫 화면 무게</h2>
<p>홈페이지는 2026년 11월 11일 첫 판을 올린 뒤 11월 15일까지 세 번 판을 바꿨다.</p>
<p>판마다 첫 화면 무게와 실제 주소에서 캐시 없이 잰 첫 화면 표시 시간(FCP, First Contentful Paint)을 기록했다.</p>
<figure><img src="https://kavotin.com/img/b-home-v1-dorok-1200.a8d41822.jpg" width="1200" height="750" alt="11월 11일 첫 판 전시 도록 화면"><figcaption>11월 11일 첫 판(전시 도록 형태). 제목 Noto Serif KR과 본문 Pretendard 두 벌을 페이지 글자만 잘라 실어 첫 화면 전체 무게를 104.7KB로 맞췄다.</figcaption></figure>
<p>11월 11일 첫 판은 종이 질감 바탕에 제목을 명조체인 Noto Serif KR(<code>NotoSerifKR-wght.ttf</code>)로, 본문을 Pretendard로 조판한 전시 도록 형태였다.</p>
<p>Noto Serif KR 원본 TTF 파일은 23,795,420바이트(약 23.8MB)다. Pretendard 원본(6.74MB)과 합치면 글꼴 원본만 30.5MB가 넘는다.</p>
<p>이 두 글꼴도 페이지에 나온 글자만 잘라 구운 덕분에 첫 판의 첫 화면 전체 무게(HTML + 글꼴 + 첫 그림)는 104.7KB에 들어왔다.</p>
<p>당시 실제 주소에서 캐시 없이 7번 측정한 FCP 중앙값은 모바일(390폭) 432ms(가장 느린 첫 번째 972ms), 데스크톱(1440폭) 428ms, 느린 4G 환경 592ms였다.</p>
<p>같은 날 저녁에 올린 2판에서는 명조체를 빼고 Pretendard 400과 600 두 굵기만 남겼다. 대신 제품 네 개를 실제로 열어 찍은 화면 갈무리 17장을 넣으면서 첫 화면 무게가 136.5KB(색상 조정 후 136.7KB)가 되었다.</p>
<p>모바일 FCP 중앙값은 344ms(색상 조정 후 164ms, 느린 4G 376ms)로 줄어들었다.</p>
<p>11월 12일 크몽 외주 의뢰 영역을 더한 뒤에는 첫 화면 무게 140.2KB, 데스크톱 FCP 중앙값 220ms를 기록했다.</p>
<figure><img src="https://kavotin.com/img/b-home-v3-store-1200.d787d8eb.jpg" width="1200" height="750" alt="11월 15일 3판 스토어 형태 홈 화면"><figcaption>11월 15일 3판 홈 화면. 첫 화면에 제품 아이콘 줄과 카드 그림이 함께 올라가면서 전체 무게가 218.4KB가 되었으나, 글꼴 두 벌은 합쳐서 52.7KB에 머문다.</figcaption></figure>
<p>11월 15일 개편한 3판에서는 첫 화면에 제품 아이콘 줄(그림 4개)과 제품 카드 2개가 한꺼번에 보이도록 배치를 바꿨다. 모바일(390폭, 배율 3배) 브라우저가 첫 화면에서 받아야 하는 그림이 여섯 장으로 늘면서 첫 화면 무게가 218.4KB까지 올라갔다.</p>
<p>현재 홈의 HTML은 47.0KB(인라인 CSS 16.0KB 포함)이고, 357자를 담은 글꼴 두 벌은 400 굵기 25.6KB(26,156B)와 600 굵기 27.1KB(27,732B)를 합쳐 52.7KB다.</p>
<p>만약 KS X 1001 서브셋(굵기당 약 160KB, 두 벌 320KB)을 그대로 썼다면 그림 한 장을 올리기도 전에 품질 기준인 230KB를 넘겼을 것이다.</p>
<h2>3. 겪은 실패와 고친 방법</h2>
<p>글자를 잘라 굽는 스크립트는 28줄짜리 <code>tools/fonts.py</code>와 빌드 도구 <code>build.mjs</code> · <code>blog.mjs</code>로 돌아간다.</p>
<p>처음 만든 방식에서 세 번 문제를 겪고 구조를 고쳤다.</p>
<h3>자르는 순서와 캐시</h3>
<p>처음에는 원본 가변 글꼴에서 <code>instancer.instantiateVariableFont</code>로 굵기 400을 먼저 고정한 뒤 글자를 잘랐다. 이렇게 하면 14,757개 글리프 전체의 가변 좌표를 먼저 계산하느라 한 벌을 굽는 데 28초 넘게 걸렸다.</p>
<p>순서를 뒤집어 <code>Subsetter</code>로 필요한 357자만 먼저 남긴 다음 <code>instancer</code>를 돌리자 시간이 2.0초로 줄었다.</p>
<p>글자 조합과 <code>tools/fonts.py</code> 내용의 SHA-1 해시를 파일 이름(<code>.cache/sans-400-&lt;해시&gt;.woff2</code>)으로 캐시해 두어, 문구가 바뀌지 않은 빌드에서는 파이썬을 아예 부르지 않고 0초에 넘어간다.</p>
<pre><code>font = TTFont(src)
sub = Subsetter(opts)
sub.populate(text=text)
sub.subset(font)
if 'fvar' in font:
    font = instancer.instantiateVariableFont(font, {'wght': wght}, inplace=False)
font.flavor = 'woff2'
font.save(out)</code></pre>
<p>글꼴을 자를 때 레이아웃 기능(<code>kern</code>, <code>liga</code>, <code>calt</code>, <code>ccmp</code>, <code>locl</code>, <code>mark</code>, <code>mkmk</code>, <code>tnum</code>, <code>pnum</code>)은 살려 두어 숫자 고정폭 정렬과 자간 조정이 깨지지 않게 했다.</p>
<p>또한 오픈소스 글꼴 라이선스(OFL) 조건을 지키려고 <code>name_IDs</code>에 <code>1, 2, 4, 6, 13, 14</code>(글꼴 이름과 저작권·라이선스 항목)를 명시해 메타데이터가 다 지워지지 않도록 고정했다. 원본 글꼴에 없는 특수기호가 본문에 들어오면 빌드 로그에 빠진 글자를 바로 찍어 눈으로 확인하게 했다.</p>
<h3>홈과 블로그 글꼴 분리</h3>
<p>블로그를 붙이면서 가장 먼저 부딪힌 문제는 홈 첫 화면 예산이었다.</p>
<p>홈과 블로그의 모든 HTML에서 글자를 합쳐 한 벌로 구우면, 블로그에 2,000자 넘는 글을 올릴 때마다 홈에서는 쓰지도 않는 한자어와 전문 용어 글리프가 기본 글꼴(<code>Kv Sans</code>)에 추가된다. 글이 스무 편만 쌓여도 홈 첫 화면 무게가 230KB 상한을 넘어선다.</p>
<p>그래서 빌드 단계를 둘로 갈랐다.</p>
<ol><li>먼저 홈(<code>index.html</code>), 제품 소개 4곳(<code>/about/*</code>), <code>404.html</code>에서만 글자를 모아 기본 글꼴 <code>Kv Sans</code>(400 · 600)를 굽는다. 블로그에 글이 몇 편 올라오든 홈의 글자 수는 357자, 글꼴 크기는 25.6KB와 27.1KB로 고정된다.</li><li>그다음 블로그와 안내 페이지(<code>about</code> · <code>contact</code> · <code>privacy</code>) 전체 HTML에서 글자를 뽑되, 이미 <code>Kv Sans</code>에 들어 있는 357자를 뺀 차집합(<code>!base.has(c)</code>)만 골라 보조 글꼴 <code>Kv Sans B</code>로 따로 굽는다.</li><li>블로그 CSS에서 <code>font-family: &quot;Kv Sans&quot;, &quot;Kv Sans B&quot;, -apple-system, ...</code> 순서로 지정한다.</li></ol>
<p>이렇게 나누면 홈에 들어온 방문자는 <code>Kv Sans</code>만 내려받고, 블로그 글을 읽는 방문자만 <code>Kv Sans</code>에 없는 글자가 담긴 작은 <code>Kv Sans B</code> 파일을 추가로 받는다.</p>
<h3>굵은 글씨 태그만 따로 굽기</h3>
<p>보조 글꼴 <code>Kv Sans B</code>를 처음 구웠을 때는 400 굵기와 600 굵기에 똑같은 글자 목록을 넣었다. 그러자 본문 문단에 한 번 나온 글자까지 600 굵기 파일에 다 들어가 파일이 두 배로 커졌다.</p>
<p>블로그 스타일시트(<code>src/blog.css</code>)를 점검해 보니 실제로 굵기 600을 쓰는 자리는 제목(<code>h1</code>–<code>h4</code>), 강조(<code>b</code>, <code>strong</code>), 표 머리(<code>th</code>), 정의 목록 제목(<code>dt</code>) 여덟 가지 태그뿐이었다.</p>
<p>그래서 <code>blog.mjs</code>가 구운 HTML에서 정규식으로 저 여덟 태그 안에 들어 있는 글자만 따로 추려내어 600 굵기 보조 글꼴에 넣도록 고쳤다. 안내 페이지 세 곳만 있던 상태(글 0편)에서는 블로그 쪽 추가 글자가 400 굵기 98자(9.0KB, 9,228B), 600 굵기는 9자(1.7KB)뿐이었다.</p>
<h2>4. 첫 글을 더한 뒤의 크기</h2>
<p>지금 읽고 있는 이 첫 번째 글을 넣고 <code>node build.mjs</code>를 다시 돌린 결과는 아래와 같다.</p>
<ul><li>홈 기본 글꼴(<code>Kv Sans</code>): 글자 수 357자 그대로, 400 굵기 25.6KB · 600 굵기 27.1KB, 홈 첫 화면 무게 218.4KB(변동 0B).</li><li>블로그 보조 글꼴(<code>Kv Sans B</code>): 이 글에서 새로 쓰인 한글과 기호가 더해져 400 굵기는 218자 18.8KB, 제목·표 머리에만 쓰인 600 굵기는 28자 3.2KB로 구워졌다.</li></ul>
<p>외부 글꼴 서버(Google Fonts나 CDN)를 부르지 않고 도메인 안에서 바로 내려주기 때문에 추가 DNS 조회나 TLS 연결 시간도 들지 않는다.</p>
<p>빌드된 <code>/fonts/*</code> 파일 이름에는 내용 해시 8자리가 붙고 <code>Cache-Control: public, max-age=31536000, immutable</code> 헤더가 내려가므로, 글이 바뀌지 않는 한 재방문 브라우저는 글꼴을 다시 받지 않는다.</p>
<p>저는 정적 사이트나 1인 개발 제품 소개 페이지라면 KS X 1001 2,350자 서브셋보다 빌드 시점 동적 서브셋이 훨씬 낫다고 본다. 파이썬 스크립트 서른 줄이면 6.74MB짜리 한글 글꼴을 26KB로 줄이고 첫 화면을 0.2초에서 0.4초 안에 띄울 수 있다.</p>]]></content:encoded></item>
</channel></rss>
