정적 홈페이지를 Cloudflare에 배포하고 도메인을 연결한 기록

HTML 파일과 이미지 몇 장으로 된 홈페이지는 서버가 필요 없습니다. 파일을 그대로 내려 주기만 하면 됩니다. 저희는 이 사이트를 Cloudflare에 올렸고, 로그인부터 도메인 연결까지 명령줄에서 진행했습니다. 그 과정에서 네 번 막혔습니다. 순서대로 적습니다.

전체 순서

1. 명령줄 도구로 Cloudflare 계정에 로그인
2. 프로젝트 생성과 첫 배포
3. 도메인 연결
4. 공개되면 안 되는 파일 제외
5. 배포 결과 확인

도메인은 미리 Cloudflare에서 구매해 두었습니다. 다른 곳에서 산 도메인이라면 네임서버를 Cloudflare로 옮기는 단계가 먼저 필요합니다.

막힌 지점 1: 로그인 승인에 제한 시간이 있다

npx wrangler login

이 명령을 실행하면 브라우저에 권한 승인 화면이 열립니다. 저희는 화면에 나온 권한 목록을 확인하느라 시간을 썼고, 그 사이에 명령이 이렇게 끝났습니다.

Timed out waiting for authorization code, please try again.

기록을 보니 명령을 실행하고 정확히 2분 뒤였습니다. 이미 열려 있던 승인 화면은 그 뒤에 눌러도 소용이 없습니다. 명령을 다시 실행해 새로 열린 화면에서 승인해야 합니다.

승인 화면이 진짜인지는 세 가지로 확인했습니다. 주소가 dash.cloudflare.com으로 시작하는지, "Cloudflare가 소유하고 관리하는 애플리케이션"이라는 표시가 있는지, 표시된 계정이 내 계정인지입니다.

막힌 지점 2: Pages 프로젝트를 만들었는데 Workers로 만들어졌다

정적 사이트를 올리는 서비스 이름이 Pages라고 알고 있어서 이렇게 실행했습니다.

npx wrangler pages project create axxolab --production-branch main
npx wrangler pages deploy ./dist --project-name axxolab

첫 명령은 성공했다고 나왔는데, 두 번째 명령은 실패했습니다.

The Pages project "axxolab" does not exist.

첫 명령의 출력을 다시 읽어 보니, 프로젝트는 Pages가 아니라 Workers의 정적 자산 방식으로 만들어져 이미 배포까지 끝나 있었습니다. 도구가 새 방식으로 안내하도록 바뀐 것입니다. 이 방식에서는 배포 명령이 다릅니다.

npx wrangler deploy

방문자가 보는 결과는 같습니다. 파일을 그대로 내려 주고, 무료 범위에서 쓸 수 있습니다. 다만 인터넷의 설명 글 대부분이 예전 방식 기준이어서, 따라 하다가 같은 지점에서 막힐 수 있습니다.

설정 파일

프로젝트 폴더에 설정 파일을 하나 두었습니다. 이 파일이 있으면 다음부터는 npx wrangler deploy 한 줄로 배포됩니다.

{
  "name": "axxolab",
  "compatibility_date": "2026-10-06",
  "observability": { "enabled": true },
  "assets": {
    "directory": "./axxolab-site",
    "not_found_handling": "404-page"
  },
  "routes": [
    { "pattern": "axxolab.com", "custom_domain": true },
    { "pattern": "www.axxolab.com", "custom_domain": true }
  ]
}

• assets.directory: 공개할 파일이 들어 있는 폴더입니다.
• not_found_handling: 없는 주소로 들어오면 폴더의 404.html을 보여 줍니다.
• routes의 custom_domain: 도메인을 연결합니다. 필요한 DNS 레코드와 인증서는 자동으로 만들어집니다.

도메인을 연결해 배포하자 이런 경고가 나왔습니다. 처음 받았던 임시 주소(workers.dev로 끝나는 주소)는 설정 파일에 따로 켜 두지 않으면 꺼진다는 내용입니다. 같은 사이트가 두 주소로 열리지 않으므로 그대로 두었습니다.

막힌 지점 3: 원본 파일까지 공개될 뻔했다

공개 폴더 안에는 웹용으로 줄인 이미지와 함께, 장당 2MB 가까운 원본 이미지가 들어 있었습니다. 폴더를 통째로 올리면 원본도 공개됩니다. 공개 폴더에 제외 목록 파일을 두어 막았습니다.

# axxolab-site/.assetsignore
assets/src
assets/insights/src
.assetsignore

배포한 뒤에는 제외한 주소로 직접 접속해 보았습니다. 원본 이미지, 제외 목록 파일, 설정 파일 주소가 모두 404로 응답하는 것을 확인했습니다. 제외 설정은 적용됐다고 믿지 말고 주소로 확인해야 합니다.

막힌 지점 4: 배포 직후에는 응답이 섞여 나온다

첫 배포 직후 주소에 접속하니 이런 일이 생겼습니다.

배포가 실패한 것이 아닙니다. 새 내용이 전 세계의 서버로 퍼지는 동안, 접속할 때마다 다른 서버가 응답해서 생기는 현상입니다. 그 뒤에 내용을 고쳐 다시 배포했을 때도 같았습니다. 첫 확인에서는 고치기 전의 화면이 나왔고, 잠시 뒤에 새 화면이 나왔습니다.

그래서 배포 뒤의 확인은 "모든 주소가 연속으로 정상 응답할 때까지 반복"으로 정했습니다. 한 번 정상이 나왔다고 끝내면 다음 방문자는 옛 화면을 볼 수 있습니다.

www 주소에서는 다른 일이 있었습니다. 저희 컴퓨터에서만 "주소를 찾을 수 없음"이 계속 나왔습니다. 외부의 공개 DNS 서버에 직접 물어보니 정상으로 조회됐습니다. 레코드가 생기기 전에 조회한 결과를 컴퓨터가 기억하고 있었던 것입니다. 내 컴퓨터에서 안 열린다고 배포가 잘못된 것은 아닙니다.

배포 뒤에 확인한 것

따로 켜야 하는 것

도메인을 연결하면 암호화된 주소(https)는 바로 동작합니다. 하지만 암호화되지 않은 주소(http)로 들어온 방문자를 https로 자동으로 넘기는 설정은 기본으로 켜져 있지 않았습니다. 저희가 확인했을 때 http 주소가 넘어가지 않고 그대로 열렸습니다. 이 설정은 Cloudflare 대시보드의 SSL/TLS 메뉴에 있는 "Always Use HTTPS"입니다. 명령줄 로그인으로 받은 권한에는 이 설정을 바꾸는 권한이 없어서 대시보드에서 켜야 합니다.

정리

• 로그인 승인은 2분 안에 누릅니다.
• 정적 사이트는 이제 Workers의 정적 자산 방식으로 올라가고, 배포 명령은 wrangler deploy입니다.
• 공개 폴더에 원본이나 작업 파일이 있으면 제외 목록에 넣고, 주소로 접속해 막혔는지 확인합니다.
• 배포 직후의 404와 옛 화면은 퍼지는 중이라는 뜻입니다. 연속으로 정상이 나올 때까지 다시 확인합니다.
• http에서 https로 넘기는 설정은 따로 켭니다.

같은 계정에서 도메인 메일을 받는 방법은 도메인 메일을 Gmail로 받는 설정에, 도메인을 고른 과정은 .ai와 .com 가격 비교에 적었습니다.