지난 편에서 배포가 뭔지 큰 그림을 그렸으니, 이번엔 그중 가장 단순하고 흔한 형태인 정적 사이트 배포를 파고들어 볼게요. 저는 배포를 처음 배우는 분들한테 늘 정적 배포부터 손에 익히라고 권해요. 서버 배포보다 위험이 훨씬 적어서, 배포라는 흐름 자체를 겁 없이 연습하기에 딱 좋거든요. 개인 블로그든 회사 소개 페이지든, 요즘 웹의 상당수는 사실 이 정적 배포로 굴러가요.
이번 편에서는 정적 사이트가 뭔지, 왜 정적 배포가 단순한지, 어디에 어떻게 올리는지, 그리고 단순해 보여도 은근히 실수하기 쉬운 지점들을 짚어 볼게요. 제가 정적 배포를 하면서 겪은 사소하지만 뼈아팠던 일들도 곁들일게요. 단순하다고 방심하면 딱 그만큼 발등을 찍히는 게 배포더라고요.
정적 사이트가 왜 배포가 쉬워요?
정적 사이트는 사용자가 요청할 때마다 서버가 새로 뭔가를 계산하지 않고, 미리 만들어 둔 화면 파일을 그대로 내어 주는 사이트예요. 화면 문서, 모양을 입히는 파일, 동작을 넣는 파일, 그림 같은 자원들이 이미 완성된 채로 놓여 있고, 서버는 그저 있는 파일을 건네주기만 하면 되죠. 계산도 데이터베이스 조회도 없으니, 서버가 할 일이 아주 가벼워요.
바로 이 점이 정적 배포를 단순하게 만들어요. 배포라는 게 결국 완성된 파일 묶음을 어딘가에 올리는 일로 끝나거든요. 실행 중인 프로세스를 갈아 끼울 필요도, 서버가 준비됐는지 눈치 볼 필요도 없어요. 파일을 덮어쓰면 그다음 요청부터 새 파일이 나가고, 뭔가 잘못됐으면 옛 파일로 다시 덮으면 그만이에요. 되돌리기가 이렇게 쉬운 배포도 드물어요.
또 하나 좋은 점은 어마어마하게 잘 퍼진다는 거예요. 정적 파일은 계산이 필요 없으니, 세계 곳곳에 파일 사본을 복사해 흩뿌려 두고 사용자랑 가까운 곳에서 건네줄 수 있어요. 이 흩뿌리는 그물을 배포망이라 부르는데, 덕분에 어느 나라에서 접속해도 화면이 빠르게 떠요. 서버 한 대에 사람이 몰려 느려지는 걱정도 훨씬 적죠.
저는 이 단순함 때문에 웬만하면 정적으로 만들 수 있는지부터 따져요. 화면이 사람마다 크게 다르지 않고, 실시간으로 바뀔 게 별로 없다면 정적으로 충분한 경우가 많거든요. 요즘은 글이나 상품 목록처럼 가끔 바뀌는 것도, 바뀔 때만 미리 새로 만들어 두는 방식으로 정적의 이점을 누려요. 무겁게 서버를 돌리기 전에, 정적으로 될 일인가를 먼저 묻는 습관이 참 든든해요.
물론 정적이라고 영영 안 바뀌는 건 아니에요. 사람마다 다르게 보여야 하는 부분은 화면이 다 그려진 뒤에 브라우저 쪽에서 데이터를 불러와 채우면 되거든요. 뼈대는 정적으로 미리 만들어 두고, 로그인한 사람 이름이나 실시간 숫자 같은 움직이는 조각만 나중에 끼워 넣는 식이죠. 저는 이렇게 정적의 단순함이랑 동적인 개인화를 섞어 쓰는 방식을 참 좋아해요. 뼈대가 가벼우니 첫 화면이 빨리 뜨고, 필요한 데이터만 살짝 얹으니 서버 부담도 적거든요.
정적 사이트는 어디에 올려요?
정적 사이트를 올릴 곳은 정적 호스팅이라 불리는 서비스들이에요. 완성된 파일 폴더를 통째로 올리면, 알아서 배포망에 얹어 전 세계에 뿌려 주죠. 예전엔 직접 서버를 빌려 웹 서버 프로그램을 깔고 설정하느라 고생했는데, 요즘은 폴더만 넘기면 나머지는 서비스가 다 해 줘서 참 편해졌어요. 명령 한 줄이나 저장소 연결만으로 끝나는 경우가 대부분이에요.
올리는 방식은 크게 두 갈래예요. 하나는 내 컴퓨터에서 명령으로 직접 올리는 방식이에요. 예를 들어 npm run build로 산출물을 만든 다음, wrangler pages deploy dist 같은 명령으로 그 dist 폴더를 올리는 거죠. 손이 많이 안 가고 직관적이라, 작은 사이트나 빠른 확인엔 이만한 게 없어요.
다른 하나는 저장소랑 연결해 자동으로 올리는 방식이에요. 코드 저장소에 변경을 밀어 넣으면, 호스팅이 그걸 감지해 알아서 빌드하고 배포까지 해 줘요. 사람이 매번 명령을 칠 필요가 없으니 실수도 줄고 기록도 남죠. 저는 혼자 하는 작은 실험은 직접 올리기로, 팀이 함께 쓰는 서비스는 저장소 연동으로 두는 걸 좋아해요.
어느 방식이든 핵심은 올릴 폴더를 정확히 가리키는 거예요. 산출물이 dist에 생기는데 엉뚱하게 build 폴더를 올리라고 설정해 두면, 빈 사이트가 배포되거나 옛날 파일이 올라가요. 저도 이 폴더 지정을 헷갈려 한참 헤맨 적이 있어요. 빌드가 어느 폴더에 결과를 두는지 먼저 확인하고, 배포 설정이 그 폴더를 가리키는지를 꼭 맞춰 두세요.
연결해 두면 딸려 오는 고마운 점이 하나 더 있어요. 바로 주소 연결이랑 보안 자물쇠를 자동으로 챙겨 준다는 거예요. 예전엔 내 도메인을 붙이고 통신을 암호화하는 자물쇠를 다는 게 꽤 번거로운 일이었는데, 요즘 정적 호스팅은 도메인만 입력하면 자물쇠를 알아서 발급하고 갱신해 줘요. 사용자가 안심하고 접속하는 데 꼭 필요한 이 부분을, 손 하나 안 대고 얻는 셈이죠. 저는 이런 부분에서 요즘 배포 환경이 참 초보한테 친절해졌다고 느껴요.
파일 하나 올리는데 왜 캐시가 문제예요?
정적 배포에서 가장 자주 사람을 골탕 먹이는 게 캐시예요. 파일을 새로 올렸는데도 사용자 화면엔 옛날 그대로 뜨는 일, 정적 배포를 좀 해 보면 누구나 한 번쯤 만나요. 이게 왜 생기냐면, 브라우저랑 배포망이 한 번 받은 파일을 아껴 두고 다시 안 받으려 하기 때문이에요. 매번 새로 받으면 느리니까, 성능을 위해 붙잡아 두는 거죠.
문제는 우리가 파일을 바꿨는데도, 브라우저는 이름이 같으니 예전 거랑 같겠지 하고 안 받아 온다는 거예요. 그래서 새 화면을 배포해도 사용자는 왜 안 바뀌지 하며 옛 화면을 계속 보게 돼요. 저도 급하게 고친 걸 배포하고 다 됐다 했는데, 정작 사용자 쪽에선 옛날 게 떠서 진땀 뺀 적이 여러 번이에요.
이걸 푸는 정석은 파일 이름에 지문을 새기는 거예요. 파일 내용이 바뀌면 이름도 같이 바뀌게 만드는 건데, 예를 들어 app.js가 아니라 app.9f3a1c.js처럼 내용에서 뽑아낸 표식을 이름에 붙이는 거죠. 내용이 바뀌면 표식도 바뀌니 이름이 달라지고, 이름이 다르면 브라우저는 새 파일로 알고 받아 와요. 요즘 빌드 도구들은 이걸 알아서 해 줘서, 우리는 켜 두기만 하면 돼요.
다만 화면 문서인 index.html만은 예외로 둬요. 이 문서는 어떤 지문 파일을 부를지를 담고 있으니, 이것까지 오래 붙잡히면 새 지문 파일을 영영 못 부르거든요. 그래서 지문 붙은 파일은 오래 아껴 두되, 화면 문서는 아끼지 말라고 설정해요. 이 이야기는 뒤에 캐시 버스터 편에서 더 깊이 다룰 거예요. 지금은 이름이 같으면 안 바뀐 줄 안다는 원리만 확실히 붙잡아 두세요.
이 원리를 뒤집으면 오히려 캐시가 고마운 친구가 돼요. 지문이 붙은 파일은 내용이 바뀌면 이름도 바뀌니까, 안심하고 아주 오래 붙잡아 둬도 되거든요. 사용자가 두 번째 방문할 땐 그 무거운 파일을 다시 안 받고 곧장 화면이 떠서 훨씬 빨라요. 그러니까 캐시는 무조건 나쁜 게 아니라, 바뀌는 걸 안 바뀐 줄 착각할 때만 문제인 거예요. 지문이라는 장치가 그 착각을 없애 주니, 우리는 캐시의 속도는 누리면서 낡은 화면 문제만 피할 수 있어요.
미리보기 배포는 뭐예요?
요즘 정적 호스팅의 참 고마운 기능이 미리보기 배포예요. 운영에 올리기 전에, 그 변경만 담은 임시 주소를 따로 만들어 주는 거죠. 코드 저장소에서 새 가지를 만들어 작업하면, 그 가지 전용 미리보기 주소가 생겨서 실제로 배포된 모습을 운영에 영향 없이 확인할 수 있어요. 저는 이 기능을 알고 나서 배포가 훨씬 덜 무서워졌어요.
왜 좋냐면, 내 컴퓨터에서만 되는 게 아니라 진짜 배포망에 올라간 상태로 볼 수 있기 때문이에요. 내 컴퓨터에선 멀쩡했는데 실제 배포하면 깨지는 일이 종종 있잖아요. 미리보기는 그 실제 환경을 미리 보여 주니, 운영에 올리기 전에 문제를 잡을 수 있어요. 팀원한테 이 주소 한번 봐 줘 하고 링크만 던지면 되니, 검토받기도 편하죠.
저는 이 미리보기를 검토의 기본 절차로 삼아요. 변경을 올리면 자동으로 미리보기 주소가 생기고, 팀원이 그걸 직접 눌러 보며 화면이 제대로 뜨는지 확인한 뒤에야 운영으로 합쳐요. 말로만 다 됐어요 하는 것보다, 실제로 눈으로 본 주소가 있으니 훨씬 믿음이 가거든요. 디자인이 틀어졌거나 링크가 깨진 것도 이 단계에서 많이 걸러져요.
한 가지 주의할 건, 미리보기 주소가 바깥에 새어 나가지 않게 조심하는 거예요. 아직 공개 안 한 기능이 미리보기에 올라가 있는데 주소가 퍼지면, 의도치 않게 먼저 공개되는 셈이 되거든요. 검색에 잡히지 않게 막아 두거나, 민감한 미리보기는 접근에 가벼운 잠금을 걸어 두는 게 좋아요. 편한 기능일수록 새는 구멍도 같이 챙기는 습관이 필요해요.
저는 미리보기가 생긴 뒤로 팀의 대화 방식도 바뀌었어요. 예전엔 화면을 두고 말로 옥신각신했는데, 이제는 미리보기 주소를 열어 놓고 같은 화면을 보며 이야기하니 오해가 확 줄었거든요. 이 버튼 위치가 어색하다는 지적도, 직접 그 화면을 누르면서 하니까 훨씬 또렷해요. 만드는 사람이랑 검토하는 사람이 같은 걸 보는 것만으로도 협업의 질이 올라가더라고요. 저는 이게 미리보기의 숨은 값어치라고 생각해요.
정적 배포에서 뭘 조심해야 해요?
정적 배포가 단순하다고 했지만, 그래도 몇 가지 단골 함정이 있어요. 첫째는 앞서 말한 캐시예요. 배포했는데 안 바뀐다는 문제의 십중팔구는 캐시라, 저는 배포 후 화면이 옛날 그대로면 가장 먼저 강제 새로고침으로 캐시를 무시하고 확인해요. 그래도 옛날 거면 배포 자체가 안 된 거고, 강제 새로고침에선 새 거면 캐시 설정을 손봐야 하는 거죠.
둘째는 주소를 새로고침하면 화면을 못 찾는 문제예요. 화면 안에서 이리저리 옮겨 다니는 사이트를 만들면, 사용자가 깊은 주소에서 새로고침했을 때 그 파일이 실제론 없어서 오류가 나요. 이건 없는 주소는 전부 화면 문서로 돌려보내라고 설정해 풀어요. 정적 호스팅마다 이 설정 방법이 있으니, 여러 화면을 오가는 사이트라면 꼭 챙겨 두세요. 저도 이걸 몰라서 첫 화면은 되는데 새로고침하면 오류가 나는 문제로 반나절을 날린 적이 있어요.
셋째는 올릴 폴더를 착각하는 거예요. 빈 폴더나 소스 폴더를 올려서 텅 빈 사이트가 배포되는 실수, 생각보다 흔해요. 저는 배포 직전에 산출물 폴더 안에 화면 문서랑 자원이 제대로 들었는지 눈으로 한 번 확인해요. 이 몇 초가 텅 빈 사이트를 세상에 내보내는 참사를 막아 줘요. 특히 빌드가 조용히 실패했는데도 옛 산출물이 폴더에 남아 있으면, 겉보기엔 배포가 된 것 같지만 실제론 옛날 화면이 올라가는 함정도 있어요. 그래서 저는 빌드가 진짜 성공했는지부터 확인하고 나서 폴더를 올려요.
넷째는 모바일에서 안 열어 보는 거예요. 저는 배포 확인을 늘 큰 화면에서만 하다가, 정작 사용자 대부분이 쓰는 작은 화면에서 글자가 깨지거나 버튼이 겹치는 걸 뒤늦게 발견한 적이 많아요. 정적 사이트일수록 다양한 기기에서 열리니, 배포 뒤엔 휴대폰으로도 한 번 들어가 보는 게 좋아요. 이 작은 습관이 사용자 항의를 미리 막아 줘요.
다섯째는 배포됐다고 방심하는 거예요. 정적 배포는 쉬우니까 올리고 나면 다 됐다 싶은데, 실제 사용자 주소로 들어가 핵심 화면이 뜨는지 눈으로 봐야 진짜 끝이에요. 배포망에 파일이 퍼지는 데 잠깐 시차가 있을 수도 있고, 설정 하나가 틀어져 특정 화면만 안 뜰 수도 있거든요. 아무리 단순한 배포라도 마지막엔 실제로 열어 본다는 규율만은 지켜 주세요. 다음 편에서는 정적보다 훨씬 조심스러운 서버 배포의 세계로 넘어가 볼게요.