NotionNext 문서

Appearance

Cloudflare Pages 정적 배포 ​

이전 문서: Cloudflare Pages 정적 배포 게시일: 2023-3-13 마지막 수정: 2026-5-10 원래 분류: 🚀 설치 및 배포 태그: NotionNext, 배포 방식, Cloudflare 요약: Cloudflare는 정적 내보내기 방식의 NotionNext 배포를 지원합니다. 호환성이 완벽하지는 않지만 선택지 중 하나로 사용할 수 있습니다.

머리말 ​

💡

Cloudflare 방식은 사이트 방문량은 많지만 글 업데이트 빈도는 낮은 사용자에게 적합합니다.

현재 작성자가 개인적으로 사용 중인 방식이기도 합니다.

haixin의 글 NotionNext 사이트 구축 - cloudflare 버전을 참고하되, 여기서는 일부 내용을 최적화했습니다.

배포 결과 예시:

Notion Blog | NotionNext로 만든 블로그

NotionNext로 만든 블로그

❓

Cloudflare 버전은 정적으로 내보낸 사이트이므로 글이 실시간으로 갱신되지 않습니다. Notion 콘텐츠를 변경할 때마다 사이트를 수동으로 다시 배포해야 합니다. 실시간 동적 갱신이 필요하다면 Vercel, Netlify, Zeabur, VPS 배포 방식을 사용하세요.

💡

Cloudflare 배포 방식과 그 밖의 정적 내보내기 방식은 기본적으로 NotionNext 내장 검색 기능을 지원하지 않습니다. 전체 문서 검색이 필요하다면 Algolia 플러그인을 연동해야 합니다.

자세한 내용은 Algolia 전체 텍스트 검색 플러그인 문서를 참고하세요. Algolia 검색 엔진 | NotionNext 도움말

NotionNext에서 Algolia를 설정하는 방법

시작하기 ​

Cloudflare Pages에 접속합니다.

Cloudflare Pages

Cloudflare Pages로 Next 애플리케이션을 빌드합니다.

프로젝트 생성 ​

Untitled

⚠️

주의: 2026년 새 Cloudflare 화면은 기본적으로 Workers 배포로 안내하지만, 현재 NotionNext 코드는 Workers 동적 배포를 지원하지 않습니다. 우선 Pages 정적 배포를 선택하세요.

배포 페이지 하단의 작은 Pages 항목

  1. Git에 직접 연결합니다. Untitled

  2. 프로젝트를 가져옵니다. Untitled

  3. 브랜치를 선택합니다. 브랜치는 deploy/cloudflare-support를 선택합니다. 4.0.9 이후 버전에서는 별도 브랜치 전환 없이 main 브랜치로 바로 배포할 수 있습니다. Untitled

매개변수 설정 ​

페이지 하단의 빌드 설정으로 이동합니다.

  • 빌드 명령:
Bash
yarn export
  • 출력 루트 디렉터리: out

Untitled

환경 변수 ​

설정 예시는 다음과 같습니다.

image.png

설정 설명: 최신 NotionNext에서는 NODE_VERSION을 20 버전으로 설정해야 합니다.

마지막으로 저장하고 배포를 클릭하면 됩니다.

배포 완료 ​

페이지 중앙에 접속 가능한 도메인이 표시됩니다.

Untitled

FAQ ​

배포에 실패했고 빌드 로그에 다음 메시지가 나타난다면:

JSON
YN0070: Migrating from Yarn 1; automatically enabling the compatibility node-modules linker 👍

Cloudflare의 빌드 환경 업그레이드로 인한 호환성 문제일 수 있습니다. 해결 방법은 이전 빌드 환경으로 낮춘 뒤 다시 시도하는 것입니다.

Untitled

Untitled

도움이 필요하다면 ​

배포가 비정상적으로 끝났거나 초록색 체크 표시가 나타나지 않았다면, 보통 코드 수정 오류나 설정 오류가 원인입니다. 오른쪽의 상세 보기를 클릭해 자세한 배포 로그를 확인하세요.

image.png

빌드 로그 영역에서 자세한 오류 정보를 확인할 수 있습니다. 오류 로그를 기준으로 문제를 점검하고, 직접 해결하기 어렵다면 로그를 복사하거나 화면을 캡처해 다른 사람에게 도움을 요청하세요.

image.png

Cloudflare Pages에서 커스텀 도메인을 연결하는 방법 ​

프로젝트 홈에서 Custom domains를 찾은 뒤, 아래쪽의 커스텀 도메인 설정으로 이동합니다.

Untitled

도메인을 입력하고 계속 진행합니다.

Untitled

요구 사항에 따라 도메인 서비스 제공자의 DNS 관리 화면에서 CNAME 레코드를 설정합니다.

Untitled

  • CNAME 레코드 예시 Untitled

  • 아래의 활성화 버튼을 클릭합니다. 작성자는 도메인 제공자도 Cloudflare를 사용하고 있어 이 단계의 검증이 몇 초 만에 완료됩니다. Untitled

Hooks로 배포 트리거하기 ​

Cloudflare는 Vercel과 비슷한 Hooks 기능을 지원합니다. 관리자 화면에서 호출 주소를 생성해 사이트 재배포를 트리거할 수 있으며, 파일과 설정을 갱신할 때 사용할 수 있습니다.

프로젝트 설정 페이지의 빌드 섹션에서 배포 Hook을 찾습니다. 더하기 버튼을 클릭해 Hook을 하나 추가합니다.

image.png

Hook을 만들 때 배포할 GitHub 코드 브랜치를 지정하고, Hook 이름을 자유롭게 입력합니다.

image.pngimage.png

생성 후 webhook 링크가 만들어집니다. 링크를 복사해 저장해 둡니다.

주의할 점은 Cloudflare의 Hook이 Vercel과 다르다는 것입니다.

  • Vercel webhook: GET 요청도 가능하므로 브라우저 주소창에 Webhook URL을 입력하는 것만으로 간단히 트리거할 수 있습니다.

  • Cloudflare Deploy Hook: POST 요청만 허용합니다. 이 방식이 더 안전합니다. 브라우저에서 접속하면 method_not_allowed가 표시됩니다. image.png

브라우저에서 URL을 한 번 클릭하는 것만으로 배포가 실행되는 일을 방지하기 위한 방식입니다.

Windows, Mac, Linux에서는 터미널에서 다음 명령으로 트리거할 수 있습니다.

Bash
curl -X POST https://your-hook-url

페이지에 다음과 같은 내용이 표시되면 재배포가 정상적으로 트리거된 것입니다.

image.png

Bash
{
  "result": {
    "id": "64b89b29-663d-4483-bde9-281cbf8e93d9"
  },
  "success": true,
  "errors": [],
  "messages": []
}

원문 링크 ​

https://docs.tangly1024.com/article/notion-next-cloud-flare