git을 이번에 처음 설치했습니다.

블로그를 만들고 싶다는 생각은 오래 했습니다. 다만 네이버 같은 남의 플랫폼에 세 들어 사는 것 말고, 도메인부터 화면 색깔까지 전부 내가 정하는 공간을 갖고 싶었습니다. 그래서 Astro로 만들어 Cloudflare에 올렸습니다. 지금 이 글이 올라와 있는 곳입니다.

만드는 것 자체는 싱거울 만큼 쉬웠습니다. 템플릿을 하나 받아서 npm run dev를 치면 블로그가 뜹니다. 진짜 일은 그다음부터였습니다. 배포하고, 도메인을 붙이고, 글 쓰는 화면을 얹는 과정에서 크게 다섯 번 막혔는데 대부분 공식 문서를 아무리 읽어도 안 나오는 것들이었습니다.

같은 길을 갈 사람이 있을 것 같아 적어둡니다.

1. Cloudflare Pages 메뉴가 없다

가이드 글들은 하나같이 “Cloudflare Pages로 들어가서”로 시작합니다. 그런데 제 대시보드에는 Pages가 없었습니다.

Cloudflare가 Pages를 Workers 쪽으로 합치는 중이라 그렇습니다. 지금은 Workers & Pages → Create application → Import a repository 순서로 들어가면 됩니다. 하는 일은 같습니다. 들어가는 문만 바뀌었습니다.

이걸 모르고 “Cloudflare Pages 사라짐” 같은 검색어로 한참을 헤맸습니다. 클라우드 서비스 관련 글은 작성일을 꼭 보시기 바랍니다. 반년만 지나도 메뉴 이름이 달라져 있습니다. 저는 이 사실을 이날 배웠습니다.

2. wrangler가 엉뚱한 설정 파일을 읽는다

글쓰기 화면을 붙이려고 인증용 워커를 하나 더 배포해야 했습니다. 시키는 대로 저장소를 클론하고 npx wrangler deploy를 쳤더니 이렇게 나왔습니다.

✘ [ERROR] Missing assets directory
  assets.directory does not exist: c:\dev\my-blog\dist

분명히 다른 프로젝트를 배포하는 중인데 왜 블로그 폴더의 dist를 찾는 걸까요.

원인은 제가 그 저장소를 블로그 프로젝트 안에 클론했다는 것이었습니다. C:\dev\my-blog\sveltia-cms-auth 이런 식으로요. wrangler는 실행한 위치에서 위로 올라가며 가장 가까운 package.json을 찾아 프로젝트의 기준점을 잡습니다. 그러다 보니 제 의도와 달리 부모 폴더인 블로그 쪽 설정을 읽고 있었습니다.

폴더를 옆으로 옮기니 한 번에 됐습니다.

C:\dev\
  ├─ my-blog\
  └─ sveltia-cms-auth\   ← 안이 아니라 옆

한 줄로 끝날 이야기지만 한 시간 넘게 봤습니다.

3. 환경변수를 넣었는데 적용이 안 된다

글쓰기 화면으로는 Sveltia CMS라는 걸 붙였습니다. GitHub 계정으로 로그인하면 브라우저에서 글을 쓰고, 저장하면 GitHub에 바로 커밋되는 방식입니다.

로그인을 눌렀더니 이렇게 나왔습니다.

OAuth 앱 클라이언트 ID 또는 시크릿이 설정되지 않았습니다

Cloudflare 워커 설정의 Variables에 값을 분명히 다 넣었는데 말입니다. 오타를 의심하고 세 번을 다시 넣었습니다.

문제는 값이 아니라 입력한 뒤 아래쪽 Deploy 버튼을 눌러야 한다는 것이었습니다. Variables 화면에서 값을 넣고 저장해도 실제로 돌아가는 워커에는 반영되지 않습니다. Deploy를 눌러 새 버전을 내보내야 그때 적용됩니다. 화면 어디에도 “아직 반영 안 됨”이라고 알려주지 않아서 알아채기가 어렵습니다.

하는 김에 하나 더. 이런 값은 타입을 Text가 아니라 Secret으로 넣으세요. Text로 넣으면 대시보드에서 값이 그대로 보입니다. 저는 처음에 Text로 넣었다가 나중에 시크릿을 새로 발급받았습니다.

4. 브랜치 이름이 master였다

로그인은 됐는데 이번엔 이겁니다.

‘ryuma-space’ 저장소에 ‘main’ 브랜치가 없습니다

CMS 설정 파일에 branch: main이라고 적어둔 게 문제였습니다. 제 저장소의 기본 브랜치는 master였거든요.

로컬에서 git init으로 만든 저장소는 설정에 따라 기본 브랜치가 master가 됩니다. 반면 요즘 도구들은 대체로 main을 가정하고요. 저처럼 내 PC에서 먼저 만들고 나중에 GitHub에 올린 경우에 어긋나기 쉽습니다.

git branch -m main으로 브랜치 이름을 바꿀 수도 있었지만, 이미 배포가 잘 돌아가는 중이라 건드리기가 싫었습니다. 그래서 설정 파일 쪽을 master로 맞췄습니다. 어느 쪽이든 상관없습니다. 양쪽이 같기만 하면 됩니다.

5. 빈 문자열 하나가 빌드를 통째로 세운다

이건 좀 허무했습니다. 잘 돌아가던 블로그가 갑자기 로컬에서 안 떴습니다.

[InvalidContentEntryDataError] blog → first-post data does not match collection schema.
updatedDate: Expected type "date", received "object"

글 파일을 열어보니 이랬습니다.

---
title: RyuMa Space를 시작하며
pubDate: Aug 30 2026
updatedDate: ''
heroImage: ''
---

updatedDate: ''. 빈 문자열입니다.

CMS 화면에서 글을 저장할 때, 제가 건드리지도 않은 선택 항목이 빈 문자열로 적혀 들어간 겁니다. Astro 쪽 스키마는 이 칸을 “날짜이거나, 아예 없거나”로 정의해두었습니다. 빈 문자열은 둘 중 어느 쪽도 아닙니다. 날짜로 바꾸려다 실패한 이상한 값이 되고, 빌드가 거기서 멈춥니다.

그 줄을 지우면 바로 해결됩니다. 다만 CMS로 글을 쓰는 한 계속 생길 문제라 스키마 쪽에서 막았습니다.

updatedDate: z.preprocess(
  (val) => (val === '' ? undefined : val),
  z.coerce.date().optional(),
),

빈 문자열이 들어오면 “값 없음”으로 바꿔서 넘깁니다. 그 뒤로는 날짜 칸을 비운 채 저장해도 조용합니다.

덤. git이 자꾸 push를 거부한 이유

위의 다섯 개를 다 넘기고 나서도 한동안 저를 괴롭힌 게 있습니다. 커밋하고 git push를 하면 자꾸 거부당했습니다.

! [rejected] master -> master (fetch first)
hint: Updates were rejected because the remote contains work
hint: that you do not have locally.

원격에 제가 모르는 작업이 있다는 뜻인데, 이 저장소는 저 혼자 씁니다. 협업하는 사람도 없습니다.

범인은 글쓰기 화면이었습니다.

CMS로 쓴 글은 제 PC를 거치지 않습니다. 브라우저에서 저장을 누르는 순간 GitHub에 곧장 커밋이 올라갑니다. 저는 그것도 모르고 로컬에서 코드를 고치고 있었으니, 제 PC와 GitHub가 각자 다른 방향으로 한 발씩 나가 있었던 겁니다.

해결은 git pull로 원격 것을 받아와 합치고, 충돌이 나면 정리한 뒤 다시 push하는 것입니다. 더 나은 방법은 애초에 만나지 않는 것이고요. 로컬에서 작업을 시작하기 전에 git pull 한 번. 이 습관 하나로 대부분 안 겪습니다.

마지막으로, 한글 블로그라면 이 두 가지

배포와는 상관없지만 만들면서 알게 된 것 중 한글로 글 쓰는 사람에게 제일 쓸모 있을 것 같은 두 가지입니다.

첫째, word-break: keep-all. 이게 없으면 브라우저가 한글을 글자 단위로 끊습니다. “블로그”가 줄 끝에서 “블로 / 그”로 쪼개집니다. 저는 제 블로그 카드 제목이 그렇게 잘린 걸 보고서야 알았습니다.

body {
  word-break: keep-all;      /* 어절 단위로 줄바꿈 */
  overflow-wrap: break-word; /* 긴 URL 같은 건 그래도 잘라줌 */
}

둘째, 고정폭 글꼴에는 한글이 없습니다. 날짜나 태그를 monospace로 지정해두면 숫자와 영문은 예쁘게 나오는데 한글만 시스템 기본 글꼴로 떨어지면서 자간이 이상하게 벌어집니다. 글꼴 스택 뒤에 한글 글꼴을 하나 붙여두면 해결됩니다.

--mono: ui-monospace, SFMono-Regular, Menlo, Consolas,
        'Pretendard Variable', sans-serif;

글자마다 앞에서부터 찾아 내려가기 때문에, 숫자와 영문은 고정폭에서 가져오고 한글만 Pretendard에서 가져옵니다.

정리

다섯 개 중 네 개가 “문서에 안 적혀 있는 사실 하나를 몰라서” 생긴 문제였습니다. 코드가 어려워서 막힌 적은 한 번도 없었습니다.

그래서 이런 걸 적어두는 게 의미가 있겠다 싶었습니다. 같은 데서 막힌 분이 검색으로 여기까지 왔다면, 오늘 한 시간쯤은 아끼셨기를 바랍니다.

다음에 뭘 쓸지는 아직 안 정했습니다.