인스타 프로필 링크용 짧은 주소 만들기
「인스타그램 소개칸에 어떤 주소를 적어야 클릭이 새지 않을까?」 302 이동과 꼬리표 보존, 한글 NFC 정규화까지 27줄로 시작해 36줄이 된 기록.

소셜 미디어 프로필이나 인쇄물, 영상 설명란에 여러 웹 게임과 도구의 주소를 안내할 때 서브도메인과 유입 경로 꼬리표가 길게 붙은 주소를 그대로 적어 두면 어떻게 될까?
손님이 주소창에 직접 쳐서 들어오기는 불가능해지고, 나중에 제품의 도메인을 옮기거나 유입 분석용 쿼리 규칙을 바꿀 때마다 이미 올라간 게시물의 링크를 일일이 찾아 고쳐야 한다. 그렇다고 외부 유료 단축 URL 서비스를 쓰면 매달 구독료가 나가거나 우리 도메인 대신 낯선 단축 도메인이 노출된다.
카보틴 스튜디오 공식 홈(kavotin.com)은 이 문제를 해결하려고 별도의 데이터베이스나 외부 단축 서비스 없이 worker/index.js 한 파일로 자체 짧은 주소 라우터를 만들어 운영한다. 첫 판은 주석까지 27줄이었고, 8일 뒤 받는 파일의 누름을 세는 9줄이 붙어 2026년 11월 20일 지금은 36줄이다.
2026년 11월 11일 첫 배포(커밋 1e67e21)부터 적용한 302 리다이렉트 설계와 쿼리 꼬리표 보존 규칙, 한글 주소(kavotin.com/온콜)의 유니코드 정규화, Cloudflare 무료 한도를 아끼는 라우팅 설정, 그리고 나중에 붙인 누름 셈이 짧은 주소를 어떻게 건드리지 않게 했는지 정리한다.
하나의 목록에서 뽑아내는 10개의 짧은 주소
짧은 주소 매핑 표를 Worker 코드 안에 따로 하드코딩하면 새 제품이 추가되거나 주소가 바뀔 때 홈페이지 화면과 Worker 양쪽을 두 번 고쳐야 한다.
그래서 모든 제품의 정보와 별칭을 담고 있는 정본 파일(src/content.mjs)을 정적 HTML 빌드 스크립트(build.mjs)와 가장자리 서버 코드(worker/index.js)가 함께 읽도록 묶었다.
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 });
Worker가 기동할 때 products 배열(4종)의 영문 식별자(id)와 별칭 배열(aliases), 그리고 제품이 아닌 외부 연결(extraLinks)을 순회하며 메모리 안의 Map 객체(LINKS)를 채운다.
이 코드로 만들어지는 10개의 짧은 주소와 도착지는 아래와 같다. 모두 302로 보내고, 제품 넷은 도착 주소 끝에 ?ref=kavotin을 붙인다(tag: true).
- 온콜:
/oncall·/온콜→ oncall.kavotin.com - 클라우드라인:
/cloudline·/tram·/클라우드라인→ cloudline.kavotin.com - 홍실:
/hongsil·/홍실→ hongsil.dotorium.com - 카리온:
/karyon·/카리온→ karyon.dotorium.com - 인스타그램:
/insta→ instagram.com/kavotinstudio (꼬리표 없음)
제품 4종은 각각 영문 ID와 한글 이름을 모두 별칭으로 가지고 있고, 클라우드라인은 기억하기 쉬운 /tram까지 포함해 세 개의 진입 경로를 갖는다.

반면 공식 인스타그램 계정으로 보내는 /insta는 외부 플랫폼이므로 자체 유입 집계 꼬리표(?ref=kavotin)를 붙이지 않도록 tag: false로 구분했다.
11월 20일 wrangler deploy --dry-run으로 다시 잰 Worker 스크립트 전체 크기는 src/content.mjs의 제품 문구와 누름 셈 코드까지 합쳐 17.93KiB(gzip 6.31KiB)다. 같은 날 실제 배포에서 Wrangler가 찍은 기동 시간(Worker Startup Time)은 2ms였다.
301 대신 302와 캐시 금지를 고른 이유
웹에서 주소를 옮길 때 흔히 영구 이동을 뜻하는 301 Moved Permanently를 습관처럼 쓰곤 한다.
하지만 짧은 주소 라우터에 301을 쓰면 한 번이라도 그 주소를 눌렀던 손님의 브라우저가 리다이렉트 결과를 디스크 캐시에 영구히 박아 버린다.
나중에 제품의 서브도메인을 옮기거나 기본 꼬리표 규칙을 고쳐도, 이전에 방문했던 브라우저는 Worker에 요청조차 보내지 않고 예전 주소로 바로 이동한다.
if (url.hostname === 'www.kavotin.com') {
url.hostname = 'kavotin.com';
return Response.redirect(url.toString(), 301);
}
그래서 절대 바뀔 일이 없는 도메인 정규화(www.kavotin.com → kavotin.com)에만 301을 썼다.
반면 10개의 짧은 주소 이동에는 일시 이동인 302 Found 상태 코드와 함께 Cache-Control: no-store 헤더를 명시해 언제든 서버의 최신 매핑 표를 따르도록 강제했다.
유입 꼬리표 보존과 기본 꼬리표 합성
짧은 주소를 운영할 때 단순히 고정된 문자열로만 리다이렉트하면 마케팅 채널별 유입 경로가 모두 증발한다.
예를 들어 인스타그램 스토리 광고나 프로필 링크에 kavotin.com/oncall?utm_source=ig&ref=story처럼 캠페인 꼬리표를 달아 두었는데, 라우터가 이를 무시하고 무조건 https://oncall.kavotin.com/?ref=kavotin으로 덮어쓰면 어느 채널에서 손님이 왔는지 알 수 없다.
반대로 아무 꼬리표 없이 kavotin.com/oncall만 치고 들어온 요청은 직접 주소창에 도착 도메인을 친 것과 구분되지 않는다.
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 && !to.searchParams.has('ref')) to.searchParams.set('ref', 'kavotin');
return new Response(null, { status: 302, headers: { Location: to.toString(), 'Cache-Control': 'no-store' } });
}
이 두 가지를 모두 만족시키려고 worker/index.js의 27~30번째 줄은 2단계로 쿼리 스트링을 조립한다.
- 먼저 들어온 요청(
url.searchParams)에 붙어 있던 모든 쿼리 항목을 도착지 URL(to.searchParams)로 그대로 복사한다. - 그 뒤 도착지가 우리 제품(
hit.tag === true)이면서 복사된 파라미터 중에ref가 없을 때만 기본 꼬리표인ref=kavotin을 추가한다.
덕분에 외부에서 ?utm_source=ig&ref=story를 달고 들어오면 https://oncall.kavotin.com/?utm_source=ig&ref=story로 온전히 넘어가고, 빈 주소로 들어오면 ?ref=kavotin이 붙어 공식 홈 짧은 주소를 거쳤다는 흔적이 남는다.
이 꼬리표 규칙은 블로그 빌드 스크립트(blog.mjs 33~36번째 줄)에도 똑같이 들어 있어서, 블로그 글 본문 안에서 우리 제품 도메인으로 나가는 모든 링크에도 빌드 시점에 자동으로 ?ref=kavotin이 붙는다.
한글 주소의 NFC 정규화와 깨진 인코딩 방어
음성이나 댓글로 주소를 안내할 때는 영문 철자(/cloudline)보다 한글 이름(kavotin.com/클라우드라인, kavotin.com/온콜)이 훨씬 전달하기 쉽다.
그런데 HTTP 요청 경로에서 한글 주소를 다룰 때는 눈에 보이지 않는 세 가지 함정이 있다.
let key = '';
try { key = decodeURIComponent(url.pathname).normalize('NFC').toLowerCase().replace(/^\/+|\/+$/g, ''); } catch { /* 깨진 주소는 404 로 */ }
첫째는 퍼센트 인코딩이다. 브라우저 주소창에 kavotin.com/온콜을 입력하면 실제 HTTP 요청의 url.pathname은 /%EC%98%A8%EC%BD%9C라는 ASCII 문자열로 들어온다. decodeURIComponent()로 먼저 바이트열을 풀어야 한글 문자열과 비교할 수 있다.
둘째는 운영체제마다 다른 유니코드 정규화 방식이다. Windows와 Android는 한글 한 글자를 완성형 코드 포인트 하나(NFC)로 다루므로 '온콜'이 2글자(\uC628\uCF5C)가 된다.
하지만 macOS나 iOS의 일부 입력기·파일 시스템에서 복사한 텍스트는 초성·중성·종성이 분리된 정준 분해(NFD) 상태여서 겉보기에는 똑같은 '온콜'이라도 내부적으로는 6글자(\u110B\u1169\u11AB\u110F\u1169\u11AF)가 된다.
코드 뒤에 .normalize('NFC')를 붙여 두지 않으면 맥이나 아이폰 사용자가 복사해 넣은 한글 주소만 LINKS.get(key)에서 undefined가 나와 404로 빠진다.
셋째는 잘못 잘린 퍼센트 인코딩이다. 외부 크롤러나 봇이 URL 끝을 잘못 잘라 /%E0%A4%A처럼 불완전한 UTF-8 시퀀스를 요청하면 decodeURIComponent()는 즉시 URIError: URI malformed 예외를 던진다.
이를 try ... catch 없이 실행하면 Worker 프로세스가 미처리 예외로 죽으면서 방문자에게 Cloudflare의 500 오류 화면(Error 1101)을 노출한다.
그래서 예외가 나면 조용히 잡아 key를 빈 문자열('')로 두고 마지막 줄인 env.ASSETS.fetch(request)로 넘긴다. 그러면 정적 자산 처리기가 not_found_handling: "404-page" 설정에 따라 디자인된 404 안내 페이지(없는 주소.)를 정상 반환한다.
무료 요청 10만 건을 아끼는 정적 자산 우회
카보틴 스튜디오 홈은 유료 서버 없이 Cloudflare Workers 무료 구간(하루 요청 100,000건 한도) 안에서 돌아간다.
만약 홈페이지와 블로그의 이미지(.webp, .jpg, .png)나 서브셋 웹폰트(.woff2) 요청까지 전부 Worker 스크립트를 거치게 두면, 방문자 한 명이 글 하나를 열 때도 HTML 한 번에 글꼴 두 벌과 그림 몇 장이 따로따로 Worker 호출 횟수를 깎아 먹는다.
{
"name": "kavotin-home",
"main": "worker/index.js",
"assets": {
"directory": "./dist",
"binding": "ASSETS",
"not_found_handling": "404-page",
"run_worker_first": ["/*", "!/img/*", "!/fonts/*"]
}
}
이 낭비를 막으려고 wrangler.jsonc 7번째 줄의 run_worker_first 배열에 부정 패턴 두 개("!/img/*", "!/fonts/*")를 넣었다.
기본적으로 정적 자산(dist/)과 Worker를 함께 배포하면 정적 파일이 있는 경로는 Worker를 건너뛰지만, 우리는 www. 서브도메인 301 이동과 짧은 주소 판별을 먼저 해야 하므로 "/*"에 대해 Worker 우선 실행을 켰다.
그 대신 이미지 폴더(!/img/*)와 글꼴 폴더(!/fonts/*)는 예외로 빼서, 가장자리 캐시 계층이 Worker를 깨우지 않고 정적 파일을 바로 내려주도록 분리했다. Cloudflare 정적 자산 문서(11월 20일 다시 확인)는 「Requests to static assets are free and unlimited」라고 적는다. 같은 문서는 반대쪽 위험도 적어 둔다. 무료 구간에서 하루 한도를 넘기면 run_worker_first에 걸린 경로는 정적 파일로 물러서지 않고 429(Too Many Requests)를 돌려준다. 그래서 그림과 글꼴처럼 수가 많은 요청을 Worker 바깥으로 빼 두는 일은 비용보다 먼저 화면이 깨지지 않게 하는 일이었다.
8일 뒤 붙은 9줄: 누름 셈을 길 옆에 두기
11월 19일에 무료로 받는 파일 쪽(/free)이 생기면서 「몇 명이 실제로 받았는가」를 세야 했다. 파일은 정적 자산이 내주므로 Worker가 파일을 직접 읽을 필요는 없다. 그런데 /free/ 경로는 run_worker_first의 예외가 아니라서 어차피 Worker를 한 번 지난다. 그 길목에서 누름만 세고 파일은 그대로 넘기기로 했다.
const FILES = new Map(gifts.flatMap((g) => [g, ...(g.more ?? [])].map((f) => [`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);
받는 파일 목록도 짧은 주소와 같은 정본 src/content.mjs의 gifts 배열에서 뽑는다. 파일 주소 하나가 셈 이름 하나(snow_zip 같은 것)로 묶인다.
이때 지킨 순서가 하나 있다. 셈은 짧은 주소 판별(LINKS.get)보다 뒤, 정적 자산으로 넘기기 바로 앞에 둔다. 그래서 짧은 주소 302 응답은 셈 코드가 실패해도 영향을 받지 않는다.
셈 자체는 ctx.waitUntil()로 응답 뒤에 돌린다. 손님은 셈이 끝나기를 기다리지 않고 바로 파일을 받는다. 셈은 같은 계정의 다른 Worker에 서비스 바인딩(env.TALLY)으로 넘겨서 이 Worker 쪽 KV 쓰기는 0이다.
거르기는 worker/tally.js(32줄)가 맡는다. GET이 아닌 요청, 중간부터 이어 받는 요청(Range가 bytes=0-로 시작하지 않는 것), 브라우저의 미리 받기(Sec-Purpose: prefetch), 이름에 봇 · 크롤러 표시가 있는 사용자 에이전트, 데이터센터 망에서 온 요청은 세지 않는다. 시험 삼아 누른 것은 ?ref=test를 달면 test: 이름으로 따로 쌓인다.
count() 함수는 통째로 try ... catch 안에 있다. test/check.mjs는 셈 쪽 Worker가 죽은 상황(fetch가 예외를 던지는 가짜 TALLY)을 만들어 그때도 파일이 200으로 나가는지 본다. 앞에서 깨진 주소를 404로 돌린 것과 같은 생각이다. 덧붙인 기능이 원래 길을 막으면 안 된다.
배포 전과 배포 후 두 번 도는 14개 시험
코드가 27줄로 짧아도 정규식이나 인코딩 순서를 한 줄만 잘못 건드리면 모든 제품의 진입로가 끊긴다.
그래서 test/check.mjs는 배포 전 로컬 환경과 배포 후 실제 도메인 양쪽에서 짧은 주소를 자동으로 시험한다.
const env = { ASSETS: { fetch: async () => new Response('asset', { status: 200 }) } };
const go = (u) => worker.fetch(new Request(u), env);
let r = await go(`https://kavotin.com/${p.id.toUpperCase()}/?utm_source=ig&ref=story`);
ok(r.headers.get('Location') === `${p.url}?utm_source=ig&ref=story`, '대문자 · 끝 빗금 · 꼬리표 넘기기');
r = await go('https://kavotin.com/%E0%A4%A');
ok(r.status === 200, '깨진 주소도 죽지 않는다');
로컬 검사(node test/check.mjs)는 Cloudflare 서버를 띄우지 않고도 Node.js 안에서 가짜 env.ASSETS 객체를 넣어 worker.fetch()를 직접 호출한다.
여기서 10개 짧은 주소 전수 검사(10건), 대문자와 끝 슬래시 및 쿼리 파라미터 보존(/ONCALL/?utm_source=ig&ref=story 1건), www 301 리다이렉트(1건), 첫 화면 정적 자산 폴백(1건), 깨진 인코딩(/%E0%A4%A) 예외 방어(1건)까지 총 14건을 확인한다. 지금 이 검사들은 test/check.mjs 129~147번째 줄에 있다.
이어서 배포가 끝나면 node test/check.mjs --live https://kavotin.com 명령이 실행되어 실제 프로덕션 주소에 redirect: 'manual' 옵션으로 HTTP 요청을 보내 10개 짧은 주소의 실제 302 상태 코드와 location 헤더, 없는 주소(/no-such-page)의 404 응답을 다시 대조한다.
저는 작은 스튜디오일수록 외부 SaaS 도구를 하나씩 늘리기보다 정적 데이터 파일 하나와 수십 줄짜리 가장자리 코드로 인프라를 단순하게 유지하는 편이 훨씬 단단하다고 본다.
36줄의 코드에 영문과 한글 짧은 주소, 유입 꼬리표, 예외 방어, 받기 누름 셈까지 모아 두니 새 게임이나 도구를 출시할 때도 src/content.mjs에 한 줄만 더하면 즉시 짧은 주소가 열린다.
글 · Kavotin Studio. 숫자는 직접 잰 것만 기록. 문의