NotionNext 업그레이드 튜토리얼

이전 원문: NotionNext 업그레이드 튜토리얼 게시일: 2022-6-2 마지막 편집: 2025-1-21 원래 분류: ✨ 업데이트 로그 태그: NotionNext, 업그레이드 튜토리얼 요약: NotionNext 새 버전이 출시된 뒤 내 프로젝트를 업데이트하는 방법입니다.

💡

4.8 버전에는 새로운 기능과 설정이 추가되었고 설정 파일도 많이 조정되었습니다. 업데이트 시 blog.config.js 파일에서 많은 충돌이 발생할 수 있으니 주의하세요. 권장 방식은 기존 파일을 모두 백업하거나, 다운로드해 보관하거나 다른 브랜치로 백업한 뒤, NOTION_CONFIG 같은 방식으로 설정을 이전하는 것입니다. 업데이트할 때 기존 코드를 포기해 코드 일관성을 먼저 확보하고, 버전을 맞춘 뒤 백업 파일을 참고해 다시 설정하는 편이 안전합니다.

들어가기 전에

이 문서를 통해 NotionNext를 최신 버전으로 업그레이드하는 방법을 배울 수 있습니다. 이 문서를 참고하면 전체 프로젝트 업그레이드를 완료할 수 있습니다.

혼자 진행하기 어렵다면 문서 끝의 도움 요청 방법을 참고하세요.

버전 번호 설명

필요에 따라 버전을 업데이트하세요. 각 버전은 세 자리 숫자로 구성됩니다. 예를 들어 4.7.13의 의미는 다음과 같습니다.

첫 번째 숫자 4: 메이저 버전입니다. 아키텍처 조정 시 증가하며, 현재는 4세대를 의미합니다. 전체 리팩터링은 코드 업데이트 영향이 크므로 백업과 작업에 주의해야 합니다.

두 번째 숫자 7: 새 기능이나 새 특성 조정 시 변경됩니다. 현재는 7번째 기능 추가를 의미합니다. 새 기능을 추가하면 blog.config.js 또는 테마의 config.js 파일이 바뀔 수 있어 충돌이 생길 수 있으므로 역시 주의해서 백업하고 업데이트해야 합니다.

세 번째 숫자 13: 작은 기능 조정과 버그 수정 패치입니다. 13은 패치가 13번 적용되었다는 뜻입니다.

버전 기록

이 프로젝트는 장기 유지보수 과정에서 버그를 수정하고 새 기능을 추가합니다. 새 버전은 페이지 스타일과 로딩 속도도 많이 최적화하므로 최신 버전으로 업데이트하는 것을 권장합니다.

NotionNext GitHub 저장소 오른쪽 위에서 Star를 눌러 프로젝트 동향을 팔로우할 수 있습니다. 새 버전 출시 소식을 빠르게 받을 수 있습니다.

버전 업데이트 기록은 아래 문서에서 확인할 수 있습니다.

NotionNext 문서

NotionNext 튜토리얼

코드 백업에 대하여

코드를 많이 사용자 지정했다면 나중에 실수로 코드를 덮어쓰거나 삭제하지 않도록 백업하는 것을 권장합니다. 단순한 스타일 미세 조정처럼 모든 스타일과 설정을 NotionConfig에서 처리하고 소스 코드를 수정하지 않았다면 이 부분은 신경 쓰지 않아도 됩니다.

가장 간단한 방법은 전체 백업을 다운로드해 보관하는 것입니다.

업데이트 과정에서 실수로 자신의 코드가 덮어써졌다면 Vercel에서 복원할 수도 있습니다. Vercel은 매번 업데이트 시 코드 버전을 가져와 그 버전으로 컴파일, 패키징, 배포하며, 각 배포에는 완전한 코드 백업이 남습니다.

다음 위치에서 찾을 수 있습니다.

프로젝트 열기 -> Deployments 클릭

적절한 이전 배포 기록을 찾고, 오른쪽 점 세 개를 클릭한 뒤 viewsource를 클릭합니다. 아래 예시는 이틀 전 배포 기록을 선택한 것입니다.

여기에 당시 컴파일된 소스 코드가 있으므로 하나씩 찾아볼 수 있습니다.

물론 오른쪽 위를 클릭하면 이 버전의 GitHub snapshot으로 바로 이동할 수도 있습니다.

이동 후 표시되는 내용은 당시 패키징된 코드 백업입니다. 여기의 4400400이 당시 snapshot 버전 번호입니다.

간단한 업데이트 방법

내 코드 버전이 NotionNext 최신 버전보다 뒤처져 있으면 프로젝트 오른쪽 위에 업데이트 버튼이 나타납니다. 이 버튼은 보통 세 가지 상황 중 하나입니다.

1. Fetch upstream 버튼이 표시됩니다. 클릭한 뒤 Fetch and merge를 선택하면 최신 코드로 업데이트할 수 있습니다.

2. Sync fork 버튼이 표시됩니다. 클릭한 뒤 Update branch 버튼을 선택하면 자동으로 업데이트됩니다.

3. 위 두 버튼이 보이지 않습니다. 이 경우 같은 부분의 코드를 서로 수정해 충돌이 생겼을 가능성이 큽니다. 수동 확인 후 병합해야 하므로 아래 내용을 참고하세요.

충돌이 발생한 경우

내 코드와 upstream 코드가 충돌하면, 즉 conflicts가 발생하면, 예를 들어 내가 blog.config.js를 수정했고 upstream도 같은 파일을 수정했다면, 업데이트 시 Git이 최종 코드 버전에서 어떤 내용을 보존할지 사람의 확인을 요구합니다.

팝업 버튼의 구체적인 내용은 여러 형태가 있을 수 있습니다. 그중 하나는 Discard xx commits 또는 open pull request.로 표시됩니다.

• Discard xx commits는 수정한 코드를 포기한다는 뜻입니다. 이렇게 하면 내 코드와 upstream 코드의 충돌을 없애고 update를 클릭해 업데이트할 수 있습니다. 이 옵션을 누르기 전에 코드에서 수정한 설정을 반드시 백업하세요.

• Open Pull Request는 비전문 사용자는 누르지 않는 것을 권장합니다. 이는 내가 수정한 기능이나 버그 수정을 NotionNext 중앙 저장소에 제출하겠다는 뜻이며, 줄여서 **PR, 코드 기여**라고 부릅니다. 제출 내용은 검토 후 통과하면 새 버전에 포함됩니다.

충돌이 있는 업데이트

현재는 다음 방식으로 업데이트할 수 있습니다.

• 백업 후 완전히 덮어쓰기

  1. 자신이 수정한 설정 파일을 백업합니다. 예: blog.config.js, 테마의 /themes/xx/config.js.
  2. Discard 21 commits처럼 xx개 commit 포기 버튼을 클릭해 자신의 수정을 포기합니다.

3. 이후 정상적으로 업데이트할 수 있습니다. Update branch를 클릭하면 페이지 상단에 파란 안내 배너가 나타나 업데이트 성공을 알려 줍니다.
4. 업데이트 후 이전에 백업해 둔 설정 파일을 참고해 다시 설정합니다.

• 처음부터 다시 시작하기

Git 작업에 익숙하지 않다면 blog.config.js 같은 설정 파일을 백업한 뒤 프로젝트를 다시 fork하고, 새 버전의 설정 항목을 기준으로 다시 설정하는 방식을 권장합니다. 모든 글 데이터는 Notion 노트에 있으므로 이 방식으로 다시 배포해도 속도는 빠르고 설정도 많지 않습니다.

• 도움 요청하기

⚠️

이 작업은 무료가 아닙니다. 무료로 모두 처리하기에는 시간이 부족합니다.

최신 코드를 대신 병합하고, 업데이트된 버전을 푸시 방식으로 사용자의 저장소에 보내 주는 방식입니다. 푸시를 받은 뒤에는 아래 단계에 따라 버튼 3개만 클릭하면 업그레이드가 완료됩니다.

1. 전달받은 페이지 링크를 클릭한 뒤 하단의 Merge pull request 버튼을 찾습니다.

2. 팝업 선택 상자에서 첫 번째 항목인 Create a merge commit을 선택합니다.

3. 다시 Confirm Merge를 클릭해 병합을 확정합니다.

이때 사이트는 자동 업그레이드를 시작합니다. 잠시 기다리거나 Vercel 백엔드에서 배포 기록을 확인하면 됩니다.

⚠️

이용 방법: 보조 담당자에게 "코드 유료 업그레이드"라고 연락합니다. 가격은 1회 9.9위안입니다.

• 더 많은 수동 방안. 공유해 준 사용자들에게 감사드립니다.

NotionNext 업데이트 충돌 수동 해결 방안 | Lingyun LinYun

NotionNext 업데이트 충돌을 해결하는 방법입니다. 온라인 튜토리얼에서 말하는 VS Code와 Git이 꼭 필요하지 않아도 바로 충돌을 해결할 수 있습니다.

047 NotionNext 버전을 업데이트하는 간단한 방법 | Dongdong's Blog

NotionNext 버전을 업데이트하는 간단한 방법입니다.

수동 NotionNext 버전 업데이트 튜토리얼 | D_SUPER BLOG

tangly1024가 NotionNext 내용을 다시 업데이트했습니다. 이전 업데이트는 blog.config.js, 블로그 설정에서 유일하게 수정해야 하는 파일, 를 건드리지 않아 Fetch upstream -> Fetch and merge로 버전을 따라갈 수 있었습니다. 하지만 이번에는 blog.config.js 수정이 포함되어 새 코드와 기존 코드가 충돌했고, GitHub에서 수동 업데이트가 필요해졌습니다. 며칠 전부터 업데이트가 필요하다는 것을 봤지만, 오늘에서야 시간을 내 이 작업을 완료했습니다. 필요한 준비물은 브라우저, 이미 fork한 NotionNext GitHub 프로젝트, GitHub Desktop 클라이언트, Visual Studio Code입니다.

최적화 권장사항

가능한 한 코드를 직접 수정하지 않기

Notion_Config나 환경 변수 같은 방식으로 사이트 설정을 조정할 수 있습니다. 이렇게 하면 코드 충돌을 최대한 줄일 수 있습니다.

전용 배포 브랜치 만들기

Git 저장소에 자신만의 브랜치를 만들 수 있습니다. 예를 들어 deploy/tangly1024.com 브랜치를 만들고 Vercel에서 이 브랜치를 가져와 배포 브랜치로 선택합니다. main 브랜치는 최신 코드 버전을 업데이트하는 데 사용합니다.

이렇게 하면 앞으로 자신의 브랜치에서 코드만 수정하면 됩니다. NotionNext 버전 업데이트는 main 브랜치에서만 진행하고, 자신의 저장소에서 main을 배포 브랜치로 병합하면 됩니다.

배포 업데이트 실패 해결 방법

❓ 업데이트 후 웹 페이지를 열었는데 버전 번호가 여전히 이전 버전인가요?

Vercel 배포 로그를 확인하세요. 로그 확인 방법은 다음과 같습니다.

Deployment 모듈

Vercel 백엔드의 Deployment 탭을 엽니다. 여기서 모든 배포 기록을 볼 수 있습니다.

배포 상태가 초록색 Ready이면 성공이고, 빨간색 Error이면 실패입니다.

오류 로그 보기

이번 배포 기록의 제목을 클릭해 상세 페이지를 엽니다.

상세 페이지 아래에는 패키징/컴파일 로그가 있습니다. Error 그룹에는 오류 원인과 해당 코드 줄 번호가 표시됩니다. 안내에 따라 GitHub의 코드를 수정하면 다시 배포할 수 있습니다.

도움 요청

• 댓글로 도움 요청

문의하기 | NotionNext 문서

글쓰기를 연습하기 시작한 초보자라면 무엇을 쓰는지, 어떻게 쓰는지, 얼마나 잘 쓰는지보다 꾸준히 쓰는 일이 더 중요하다고 생각합니다.

• 커뮤니티 토론

/user-guide/help/community

• 직접 도움 요청

문의하기 | NotionNext 문서

글쓰기를 연습하기 시작한 초보자라면 무엇을 쓰는지, 어떻게 쓰는지, 얼마나 잘 쓰는지보다 꾸준히 쓰는 일이 더 중요하다고 생각합니다.

원문 링크

https://docs.tangly1024.com/article/how-to-update-notionnext