정적 사이트 배포

정적 사이트는 서버 없이 HTML·JS·CSS·이미지 파일만으로 동작하는 사이트입니다. 파일을 그대로 엣지(방문자와 가까운 서버)에서 서빙하므로 빠르고, 설정할 것이 거의 없습니다. 관리형 프리셋으로 프레임워크 소스를 배포하거나 이미 빌드한 폴더를 올릴 수 있습니다.

배포하기제목 링크 복사

curl -fsSL https://nitroship.co/install.sh | bash
ntro login

관리형 프리셋으로 소스를 빌드합니다제목 링크 복사

출력 폴더가 아니라 프로젝트 루트를 배포하세요. 나이트로쉽이 의존성을 설치하고 프레임워크를 빌드한 뒤 정적 파일을 게시합니다.

ntro apps create my-static-site
ntro deploy . --prod

static(Node 도구로 빌드하거나 일반 파일을 게시)과 container-static(도구 이미지에서 빌드된 사이트만 추출)은 모두 컴퓨트 런타임 없이 CDN에 파일을 게시합니다. 서버를 출력하는 프레임워크는 관리형 Node 번들이나 컨테이너를 사용합니다. 클라이언트 에셋이 있다고 해서 정적 배포가 되는 것은 아닙니다.

감지할 때는 nitroship.json의 build.framework가 루트 Dockerfile보다도 우선합니다. build.dockerfile과 함께 설정할 수는 없습니다. 프레임워크를 명시하지 않으면 지정한 Dockerfile 또는 루트의 Dockerfile.nitroship/Dockerfile → 전용 Next.js 어댑터 → 관리형 프레임워크 레지스트리 → 일반 정적 파일 순으로 확인합니다.

일반 정적 빌드에는 빌드 명령과 출력 폴더를 설정하세요.

{
  "build": {
    "framework": "static",
    "command": "npm run build",
    "outputDirectory": "dist"
  }
}

프리셋이 빌드와 출력 설정을 고르게 하려면 static 대신 프레임워크 슬러그를 쓰세요. 빌드 요구 사항은 위에 연결한 프레임워크 안내를 따르세요.

--local은 정적 빌드와 관리형 Node 빌드를 지원합니다. Hugo·Jekyll·MkDocs 같은 container-static 생성기는 원격 빌더가 도구 이미지를 실행할 수 있도록 --local을 빼세요.

이미 빌드된 파일을 올립니다제목 링크 복사

직접 빌드한다면 빌드 결과 폴더를 지정해 배포합니다.

ntro apps create my-static-site
ntro deploy ./dist --app my-static-site --prod

./dist 같은 하위 폴더는 앱 연결이 없으므로 --app을 붙입니다. 배포한 파일은 바뀌지 않습니다. 파일을 고치려면 새로 배포하세요.

주소 규칙 설정제목 링크 복사

배포하는 폴더(배포 루트)에 nitroship.json을 두면 주소 규칙을 정할 수 있습니다. Vercel에서 쓰던 vercel.json도 같은 형식으로 읽습니다. 두 파일이 다 있으면 nitroship.json만 읽고 vercel.json은 무시합니다.

예시: 주소 정리 + 리디렉트 + 사용자 지정 404제목 링크 복사

{
  "cleanUrls": true,
  "redirects": [
    {"source": "/old/:slug", "destination": "/docs/:slug", "permanent": true}
  ],
  "headers": [
    {
      "source": "/assets/(.*)",
      "headers": [{"key": "Cache-Control", "value": "public, max-age=31536000, immutable"}]
    }
  ],
  "routes": [
    {"handle": "filesystem"},
    {"src": "^/.*$", "dest": "/404", "status": 404}
  ]
}

• /about.html 파일은 /about으로 열립니다.
• /old/hello로 들어오면 /docs/hello로 영구 리디렉트합니다. :slug는 그 자리의 값을 받아 옮겨 줍니다.
• /assets/ 아래 파일은 브라우저가 1년 동안 캐시합니다. 파일 이름에 해시가 들어가 내용이 바뀌면 이름도 바뀌는 파일에만 쓰세요.
• {"handle": "filesystem"}은 "여기까지 왔는데 실제 파일이 있으면 그 파일을 보여 준다"는 뜻입니다. 그 뒤의 규칙은 맞는 파일이 없을 때만 적용되므로, 없는 주소는 404.html을 404 상태로 보여 줍니다.

저장소의 examples/hello-static에 index.html, 404.html, 깨끗한 주소, 응답 헤더, 해시 파일 캐시 예시가 모두 들어 있습니다.

업로드되지 않는 파일제목 링크 복사

비밀 정보가 실수로 올라가지 않도록, 다음 파일은 기본으로 빠집니다: .env로 시작하는 파일(.env.example은 올라감), .git, .npmrc.

그 밖에 뺄 파일은 배포 방식에 따라 다른 파일에 적습니다.

심볼릭 링크는 정적 사이트 파일로 서빙되지 않습니다.