이 글은 이런 분께
- “빌드 성공했으니까 괜찮겠지” 하고 안심했다가 뒤통수 맞아본 분
- 화면엔 멀쩡해 보이는데 버튼만 안 눌리는 버그를 겪어본 분
- 한글로 코드를 쓰다가 이상한 곳에서 자꾸 에러가 나는 분
Before — 겉으론 멀쩡한데 안 눌리는 버튼
4주차 완성 기준을 점검하던 중이었다. 위키 글을 자동으로 책 한 권으로 묶어주는 /ebook 페이지는 진작에 만들어뒀고, “전자책 내려받기” 버튼도 있었다. 화면은 완벽했다. 근데 눌러도 아무 일이 안 일어났다.
npm run build는 문제없이 통과했다. 빌드가 성공했으니 코드는 문제없다고 생각하기 쉬운데, 이번엔 그게 함정이었다.
어떻게 — 브라우저 콘솔이 진짜 원인을 보여줬다
빌드 성공 여부와 별개로, 코드를 고쳤으면 실제 브라우저로 열어서 확인하는 게 기본이다. 콘솔을 열어보니 이런 에러가 있었다.
Uncaught SyntaxError: Unexpected token '='
원인을 찾으려고 실제로 브라우저에 로드된 스크립트 코드를 직접 뽑아봤다.
const bookTitle = "내 학습허브";
const = "2026-08-11"; // ← 변수 이름이 통째로 사라짐
원래 코드는 이거였다.
<script define:vars={{ bookTitle: site.이름, 오늘 }}>
Astro의 define:vars(서버에서 만든 값을 브라우저 스크립트로 넘겨주는 문법)에 한글 변수 이름(오늘)을 그대로 넘겼더니, 컴파일 과정에서 변수 이름 자체가 사라지고 const = ...라는 문법 에러만 남았다. 이 한 줄 때문에 스크립트 전체가 실행을 멈췄고, 다운로드 버튼도 인쇄 버튼도 둘 다 죽어있었던 거다.
고치는 건 간단했다. 한글 변수 이름을 영문으로 바꾸면 된다.
-<script define:vars={{ bookTitle: site.이름, 오늘 }}>
+<script define:vars={{ bookTitle: site.이름, todayStr: 오늘 }}>
-a.download = `${bookTitle}-학습전자책-${오늘}.html`;
+a.download = `${bookTitle}-학습전자책-${todayStr}.html`;
After — 버튼이 살아났다
다시 열어보니 콘솔 에러가 사라졌고, 버튼을 누르면 내 학습허브-학습전자책-2026-08-12.html 파일이 정상적으로 만들어졌다. npm run build도 다시 통과하는 걸 확인하고 커밋·푸시까지 끝냈다.
배운 것 / 재사용 자산
빌드 성공은 “문법이 파일 단위로는 틀리지 않았다”는 뜻이지, “브라우저에서 정상 작동한다”는 뜻이 아니다. 이번 버그는 빌드 단계에서는 안 걸리고, 실제로 페이지를 열어 콘솔을 봐야만 보였다. 화면 겉모습만 보고 “괜찮네” 하고 넘어갔으면 몇 주 동안 죽은 버튼을 방치할 뻔했다.
Astro의 define:vars처럼 값을 코드로 그대로 넘기는 문법에는 변수 이름을 영문으로 쓰기. 한글 변수 이름 자체가 문제가 아니라(다른 곳에선 잘 동작), 이런 특정 문법 안에서는 깨질 수 있다는 걸 겪어보고 알았다.
재사용 체크리스트 — 코드 고친 뒤
1. npm run build가 통과해도 안심하지 않기
2. 실제 브라우저로 열어서 콘솔(개발자 도구)에 빨간 에러가 있는지 확인
3. 버튼·링크처럼 클릭하는 요소는 직접 눌러서 결과까지 확인