정적 사이트 게시
목표
완성된 정적 웹사이트를 게시하거나 배포를 준비합니다.
이 스킬은 site/, dist/, out/, public/ 또는 docs/와 같은 배포 가능한 HTML/CSS/JS 출력물을 위한 것입니다. 또한 프레임워크 프로젝트가 정적 출력 폴더를 생성한 후에 게시할 수 있지만, 단순 정적 사이트를 배포하기 위해 프레임워크 프로젝트로 전환해서는 안 됩니다.
기본 자세:
- 프레임워크별 배포보다는 단순한 정적 호스팅을 선호합니다.
- 사용자가 계속 편집할 사이트의 경우 Git 기반 배포를 선호합니다.
- 빠른 일회성 게시에만 직접 업로드를 선호합니다.
- 사용자가 명시적으로 요청하지 않는 한 원격 저장소를 생성하거나, 코드를 푸시하거나, DNS를 변경하거나, 도메인을 추가하거나, 유료 계정에 배포하지 않습니다.
계약
입력:
site/,dist/,out/,public/,docs/또는 저장소 루트와 같은 정적 배포 루트.- 선호하는 플랫폼 또는 대상: GitHub Pages, Cloudflare Pages, Netlify, Vercel, 사용자 정의 도메인, 안내 전용 또는 실시간 배포.
- 현재 Git/저장소 상태, 플랫폼 계정 액세스, CLI/브라우저 로그인 및 배포 제약 조건.
출력:
- 구체적인 배포 설정: 플랫폼, 브랜치, 빌드 명령, 기본 디렉터리, 게시/출력 디렉터리 및 필요한 경우 설정 파일.
- GitHub Pages 워크플로,
netlify.toml,vercel.json,.nojekyll또는CNAME과 같은 선택적 플랫폼별 설정. - 배포가 실제로 수행될 때의 라이브 URL 및 배포 후 확인.
- 자격 증명 또는 계정 액세스 권한이 없을 때의 수동 대시보드 단계.
경계:
- 사이트를 빌드하거나 재설계하지 않으며, 결함은 적절한 하위 스킬로 라우팅합니다.
- 명시적으로 승인되지 않는 한 푸시, 저장소/프로젝트 생성, 업로드, 도메인 바인딩, DNS 변경 또는 유료 리소스를 사용하지 않습니다.
- 사용자가 명시적으로 서버 루트 전용 동작을 수락하지 않는 한, 손상된 로컬/정적 경로 호환성의 해결 방법으로 배포를 사용하지 않습니다.
성공 게이트:
review-static-site가 통과되었거나 해결되지 않은 위험이 명시적이어야 합니다.- 배포 루트에
index.html이 포함되어 있고 플랫폼이 올바른 폴더를 게시해야 합니다. - 배포 후 온라인 URL이 홈페이지, 에셋, 내비게이션 및 대표적인 하위 페이지를 로드해야 합니다.
게이트 실패 시:
- 배포 전에 경로, 에셋, 인코딩 또는 페이지 유형 차단 문제를 해결합니다.
- 콘텐츠/디자인/가져오기 문제를
personalize-site,edit-site-part,add-blog-posts,make-personal-site또는copy-website-style로 라우팅합니다. review-static-site를 다시 실행한 다음 배포 설정을 재시도하거나 업데이트합니다.
참고 자료
선택한 플랫폼 또는 문제에 필요한 참고 자료만 로드합니다.
- 경로 전략 및 직접 열기 호환성:
references/path-strategy.md. - Cloudflare Pages Git 통합 및 직접 업로드:
references/cloudflare-pages.md. - GitHub Pages 브랜치 소스 및 Actions 워크플로:
references/github-pages.md. - Netlify 대시보드 및
netlify.toml:references/netlify.md. - Vercel 대시보드 및
vercel.json:references/vercel.md.
공식 문서:
- GitHub Pages 게시 소스: https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site
- GitHub Pages 사용자 정의 워크플로: https://docs.github.com/en/pages/getting-started-with-github-pages/using-custom-workflows-with-github-pages
- Cloudflare Pages 정적 HTML: https://developers.cloudflare.com/pages/framework-guides/deploy-anything/
- Cloudflare Pages Git 통합: https://developers.cloudflare.com/pages/get-started/git-integration/
- Cloudflare Pages 직접 업로드: https://developers.cloudflare.com/pages/get-started/direct-upload/
- Netlify 배포 생성: https://docs.netlify.com/deploy/create-deploys/
- Netlify 빌드 구성: https://docs.netlify.com/build/configure-builds/overview/
- Vercel 배포: https://vercel.com/docs/deployments
- Vercel 프로젝트 구성: https://vercel.com/docs/project-configuration
배포 모드
먼저 사용자가 실제로 원하는 것이 무엇인지 확인합니다.
- 안내 전용: 플랫폼 선택과 정확한 설정을 설명합니다. 유용한 경우에만 파일을 편집합니다.
- 저장소 준비: 필요한 설정 파일을 추가하고 사용자에게 호스팅 대시보드에서 클릭해야 할 내용을 알려줍니다.
- 지금 배포: 사용자가 명시적으로 요청하고 필요한 CLI/인증/세션이 있는 경우에만 원격 작업을 수행합니다.
- 라이브 URL 확인: 배포된 URL을 브라우저에서 열고 로컬 사이트와 비교합니다.
자격 증명, 계정 액세스, 브라우저 로그인 또는 CLI 인증이 누락된 경우 해결 방법을 고안하는 대신 정확한 대시보드 단계를 제공합니다.
워크플로
- 정적 출력 폴더와 사용자의 선호 플랫폼(있는 경우)을 식별합니다.
- 게시 전에
review-static-site를 호출하거나 사용을 제안합니다. - 배포 루트에
index.html이 포함되어 있는지 확인합니다. - 에셋 경로를 검사하고 게시하기 전에 실수로 루트 절대 경로인 사이트 로컬 경로를 변환합니다. 경로 동작이 명확하지 않은 경우
references/path-strategy.md를 로드합니다. - 가장 간단한 일치 플랫폼과 배포 모드를 선택합니다.
- 선택한 플랫폼 참고 자료를 로드하고 해당 플랫폼에 필요한 설정 파일만 추가합니다.
- Git을 통해 배포하는 경우 Git 상태를 확인하고 관련 없거나 비공개 파일을 포함하지 않도록 합니다.
- 사용자가 원격 작업을 승인한 경우 합의된 대로 정확히 푸시하거나 배포합니다.
- 게시 후 라이브 URL을 열고 브라우저에서 배포된 사이트를 확인합니다.
사전 점검 목록
배포 설정을 작성하거나 사용자에게 설정을 알리기 전에 이러한 검사를 실행합니다.
- 배포 루트:
index.html을 직접 포함하는 폴더를 선택합니다. - 진입 페이지:
index.html이 배포 루트 최상위에 있어야 합니다. - 직접 열기 미리보기: 사용자가 명시적으로 서버 전용 동작을 수락하지 않는 한, 루트
index.html은 파일 시스템에서 직접 열 때 CSS, JS, 이미지 및 내비게이션을 유지해야 합니다. - 로컬 HTTP:
python -m http.server로 배포 루트를 제공하고http://127.0.0.1:<port>/에서 작동하는지 확인합니다. - 정적 감사: 링크, UTF-8 가독성, 플레이스홀더 잔재, 브라우저 렌더링, 개인정보 잔재 및 모바일 레이아웃에 대해
review-static-site를 실행하거나 권장합니다. - 에셋 경로:
href,src,srcset, CSSurl(...), 글꼴, 파비콘, 커버 이미지, RSS, 사이트맵 및 매니페스트 링크를 검사합니다. - 개인 데이터: 토큰, 로컬 파일 시스템 경로, 초안 노트, 소스 사이트 ID 및 개인 비밀이 게시되지 않는지 확인합니다.
- 출력 완전성: 하위 페이지, 게시물, 이미지, 공급업체 글꼴, KaTeX/수학 에셋 및 복사된 미디어가 배포 루트 내에 있는지 확인합니다.
다음을 차단 요소로 처리합니다.
- 배포 루트에
index.html이 없습니다. - 로컬 CSS, JS, 이미지, 글꼴, RSS, 사이트맵 또는 공급업체 에셋 경로가 손상되었습니다.
- 소스 파일에 모지바케(mojibake) 또는 읽을 수 없는 인코딩이 포함되어 있습니다.
- 생성된 개인 사이트에 교체되어야 할 복사된 소스 ID가 여전히 포함되어 있습니다.
- 생성된 일반 정적 사이트에
/assets/...,/posts/...,/data/...또는/images/...와 같은 실수로 루트 절대 경로인 사이트 로컬 경로가 남아 있습니다. - 루트 절대 경로가
127.0.0.1에서 제공되기 때문에 사이트가 로컬 HTTP를 통해서만 작동하지만, 직접 파일 열기 또는 하위 경로 배포는 CSS/JS/이미지를 잃게 됩니다. - 개인정보 관련 파일이나 비밀이 배포됩니다.
- 플랫폼이 잘못된 폴더를 배포합니다.
플랫폼 선택
일반 정적 개인 사이트에 대해 이 기본 순위를 사용합니다.
- Cloudflare Pages Git 통합: 생성된
site/폴더 및 향후 업데이트에 가장 적합한 기본값입니다. - GitHub Actions가 포함된 GitHub Pages: 사용자가 모든 것을 GitHub 내에서 원할 때 가장 좋습니다.
- Netlify: 친숙한 미리보기 및 대시보드 설정이 있는 간단한 정적 호스팅입니다.
- Vercel: 사용자가 이미 Vercel을 사용하거나 나중에 Next.js로 전환할 수 있을 때 좋지만, 일반 HTML의 기본값은 아닙니다.
결정 규칙:
- 사용자가 최소한의 마찰을 원하고 GitHub 저장소가 있는 경우: Cloudflare Pages Git 통합.
references/cloudflare-pages.md를 로드합니다. - 사용자가 GitHub 전용 호스팅을 원하는 경우: GitHub Pages.
references/github-pages.md를 로드합니다. - 배포 파일이 저장소 루트 또는
/docs에 있는 경우: GitHub Pages 브랜치 소스가 허용됩니다. - 배포 파일이
site/,dist/,out/또는 다른 사용자 정의 폴더에 있는 경우: GitHub Pages에 GitHub Actions를 선호합니다. - 사용자가 오늘 수동 업로드를 원하는 경우: Cloudflare 직접 업로드 또는 Netlify 수동 배포.
- 사용자에게 이미 Vercel 계정/프로젝트가 있는 경우: 명시적 출력 디렉터리 설정과 함께 Vercel을 사용합니다.
프레임워크 정적 출력
사이트가 일반 HTML/CSS/JS가 아닌 경우:
package.json, 프레임워크 설정 및 기존 스크립트를 검사합니다.- 프로젝트의 기존 빌드 명령을 사용합니다. npm 워크플로를 새로 만들지 마십시오.
- 소스 폴더가 아닌 최종 정적 출력 폴더를 게시합니다.
- 일반적인 출력에는 프레임워크에 따라
dist,out,build,.output/public및public이 포함됩니다. - Next.js 정적 내보내기의 경우
out/을 최종 출력으로 처리하기 전에 프로젝트가 실제로 정적 내보내기용으로 구성되었는지 확인합니다. - Vue/Vite/Astro 스타일 프로젝트의 경우 성공적인 빌드 후 구성된 출력 디렉터리를 게시합니다.
사용자가 일반 정적 게시를 요청했고 프레임워크 파일이 존재하지 않는 경우 npm을 도입하지 마십시오.
설정 파일 정책
선택한 플랫폼과 일치하는 설정 파일만 추가합니다.
- GitHub Pages Actions:
.github/workflows/pages.yml. - GitHub Pages 사용자 정의 도메인: 배포된 루트의
CNAME, 사용자가 도메인을 제공한 경우에만. - GitHub Pages Jekyll 우회: 유용한 경우 배포된 루트의
.nojekyll. - Netlify: 대시보드 설정으로 충분하지 않거나 사용자가 Git에 설정을 원하는 경우에만
netlify.toml. - Vercel: Vercel에 명시적 출력 설정이 필요한 경우에만
vercel.json. - Cloudflare Pages: 일반적으로 대시보드 설정으로 일반 정적 사이트에 충분합니다.
모든 플랫폼에 대한 배포 설정을 한 번에 추가하지 마십시오.
Git 및 원격 안전
원격 작업을 수행하기 전에 어떤 일이 발생할지 명시하고 사용자가 이를 요청했는지 확인합니다.
- GitHub 저장소 생성.
- 원격 추가.
- 파일 스테이징 또는 커밋.
- 원격 브랜치로 커밋 푸시.
- GitHub Pages 활성화.
- Cloudflare, Netlify 또는 Vercel 프로젝트 생성.
- 호스팅 제공업체에 파일 업로드.
- 환경 변수 추가.
- 사용자 정의 도메인 추가 또는 DNS 레코드 변경.
스테이징 또는 푸시 전:
git status --short를 실행합니다.- 생성된 사이트 파일과 관련 없는 사용자 변경 사항을 식별합니다.
- 관련 없는 변경 사항을 스테이징하지 마십시오.
- 개인 메모, 자격 증명, 로컬 경로, 비밀이 있는 스크린샷 또는 임시 파일을 게시하지 마십시오.
절대로 비밀, 토큰, 개인 메모 또는 로컬 파일 시스템 경로를 정적 사이트나 배포 설정에 넣지 마십시오.
배포 후 확인
플랫폼이 라이브 URL을 보고한 후:
- 실제로 사용 가능한 대화형 브라우저 도구로 배포된 URL을 엽니다.