NotionNext 문서

Appearance

NotionNext 버전 업데이트 가이드 ​

이 가이드는 개인화된 설정을 보존하면서 블로그를 업스트림 최신 버전으로 안전하게 업데이트하는 방법을 설명합니다.

아래 흐름을 따르면 다음을 할 수 있습니다.

  • NotionNext의 최신 기능과 수정 사항을 가져오기
  • 개인 설정(아바타, 제목, 도메인 등) 보존하기
  • 발생 가능한 코드 충돌을 안전하게 처리하기

이 가이드는 Vercel 배포 시나리오를 기준으로 합니다. 다른 플랫폼은 테스트하지 않았습니다.

브랜치 관리 전략 ​

이 전략은 NotionNext 공식 업그레이드 가이드의 권장 사항을 참고하며, 두 브랜치를 사용하는 관리 방식을 전제로 합니다.

브랜치 설명 ​

브랜치용도업데이트 전략배포 상태
main업스트림 원본 코드 동기화fast-forward 병합배포하지 않음
deploy프로덕션 환경 코드main 병합 + 개인화 보존Vercel 자동 배포
feature/*기능 개발deploy 기준으로 생성배포하지 않음

구조 예시 ​

text
GitHub Fork Repository
├── main (tangly1024/NotionNext 동기화)
├── deploy (프로덕션 브랜치 -> Vercel)
└── feature/* (개발 브랜치)

사전 준비 ​

1. Vercel 프로덕션 브랜치 설정(중요) ​

Vercel에서 프로덕션 브랜치를 deploy로 설정합니다.

  1. Vercel Dashboard에 로그인합니다.
  2. NotionNext 프로젝트로 들어갑니다.
  3. Settings → Git을 클릭합니다.
  4. Production Branch 설정을 찾습니다.
  5. 기본 main을 deploy로 바꿉니다.
  6. 설정을 저장합니다.

이렇게 설정하면 deploy 브랜치 업데이트만 프로덕션 배포를 트리거하고, main 브랜치는 업스트림 동기화 용도로만 사용됩니다.

2. 업스트림 저장소 설정(최초 1회) ​

bash
# 업스트림 저장소 추가
git remote add upstream https://github.com/tangly1024/NotionNext.git

# 설정 확인
git remote -v

예상 출력:

text
origin    https://github.com/[your-username]/NotionNext.git (fetch)
origin    https://github.com/[your-username]/NotionNext.git (push)
upstream  https://github.com/tangly1024/NotionNext.git (fetch)
upstream  https://github.com/tangly1024/NotionNext.git (push)

upstream 행이 보이지 않으면 업스트림 저장소가 제대로 추가되지 않은 것입니다.

3. 개인화 파일 파악 ​

업데이트 전에 개인화한 변경을 확인합니다.

bash
# 개인화 변경 파일 목록 확인
git diff --name-only main..deploy

자주 개인화되는 파일:

  • blog.config.js - 블로그 설정
  • public/avatar.png - 아바타
  • public/favicon.ico - 사이트 아이콘
  • pages/_app.js - 전역 스크립트
  • .env.local - 환경 변수

표준 업데이트 흐름 ​

단계 1: main 브랜치 동기화 ​

bash
# 1.1 main 브랜치로 전환
git checkout main

# 1.2 로컬 최신 상태 가져오기(여러 장비 간 불일치 방지)
git pull origin main

# 1.3 업스트림 업데이트 가져오기
git fetch upstream

# 1.4 업스트림 코드 병합
git merge upstream/main

# 1.5 내 저장소로 푸시
git push origin main

단계 2: deploy 브랜치 업데이트 ​

bash
# 2.1 deploy 브랜치로 전환
git checkout deploy

# 2.2 중요: 원격 deploy 브랜치 동기화
git pull origin deploy

# 2.3 main 브랜치 업데이트 병합
git merge main

단계 3: 충돌 처리 ​

충돌이 발생하면 파일 유형에 따라 처리합니다.

파일 유형처리 전략Git 명령
yarn.lock업스트림 버전 수락git checkout --theirs yarn.lock
blog.config.js수동 병합개인 설정을 보존하고 새 설정 항목 추가
public/avatar.png로컬 버전 보존git checkout --ours public/avatar.png
public/favicon.*로컬 버전 보존git checkout --ours public/favicon.*

처리가 끝나면:

bash
# 해결된 파일 추가
git add .

# 병합 커밋
git commit -m "merge: sync upstream updates

- keep custom configuration
- resolve conflict files: [file list]"

단계 4: 의존성 업데이트와 테스트 ​

bash
# 4.1 정리 후 의존성 재설치
rm -rf node_modules
yarn install

# 4.2 로컬 테스트
yarn dev
# http://localhost:3000 접속 후 정상 동작 확인

# 4.3 빌드 테스트
yarn build

# 4.4 원격으로 푸시
git push origin deploy

자동화 스크립트 ​

프로젝트는 자동화 업데이트 스크립트 scripts/update.sh를 제공합니다. 기능은 다음과 같습니다.

  • 사전 조건 검사
  • 설정 파일 자동 백업
  • 브랜치 동기화와 병합
  • 안전한 충돌 처리
  • 의존성 업데이트

사용 방법 ​

bash
# 실행 권한 부여(최초 1회)
chmod +x scripts/update.sh

# 업데이트 실행
./scripts/update.sh

스크립트는 전체 업데이트 흐름을 안내하고, 수동 처리가 필요한 상황에서는 명확한 안내를 제공합니다.

롤백 ​

방법 1: Git 롤백 ​

bash
# 커밋 히스토리 확인
git log --oneline -10

# 지정 버전으로 롤백
git reset --hard [commit-hash]

# 강제 푸시(주의해서 사용)
git push origin deploy --force-with-lease

방법 2: Vercel에서 복구 ​

실수로 코드가 덮어써졌다면 Vercel 배포 히스토리에서 복구할 수 있습니다.

  1. Vercel Dashboard에 로그인합니다.
  2. 프로젝트 → Deployments로 들어갑니다.
  3. 정상 동작했던 과거 배포를 찾고 오른쪽 점 세 개를 클릭합니다.
  4. "View Source"를 선택해 당시 소스 코드를 확인합니다.
  5. 오른쪽 위 링크를 눌러 GitHub의 해당 버전으로 이동할 수 있습니다.

문제 해결 ​

Vercel 배포 실패 ​

문제: 푸시 후 Vercel 빌드가 실패합니다.

해결 방법:

  1. Vercel 빌드 로그를 확인해 구체적인 오류를 찾습니다.
  2. 의존성 문제라면:
    bash
    rm -rf node_modules yarn.lock
yarn install
git add yarn.lock
git commit -m "fix: regenerate yarn.lock"
git push
  3. 환경 변수 문제라면 Vercel Dashboard → Settings → Environment Variables를 확인합니다.

많은 파일 충돌 ​

문제: 병합 중 많은 충돌이 발생해 처리하기 어렵습니다.

해결 방법:

bash
# 현재 병합 중단
git merge --abort

# 업스트림 최근 커밋 확인
git log upstream/main --oneline -20

# 단계별 병합(더 이른 커밋부터 병합)
git merge [earlier-commit]
# 충돌 해결 후 다음 커밋 병합 계속

로컬과 원격 불일치 ​

문제: 푸시할 때 rejected가 표시됩니다.

해결 방법:

bash
# 먼저 원격 업데이트 가져오기
git pull origin deploy --rebase

# 가능한 충돌을 해결한 뒤 푸시
git push origin deploy

주의 사항 ​

  1. 업데이트 주기: 1-2주마다 업데이트를 확인하는 것을 권장하며, 중요한 보안 업데이트는 즉시 처리해야 합니다.
  2. 중요 파일 백업: 업데이트 전 blog.config.js와 기타 개인화 설정을 백업합니다.
  3. 테스트 검증: 업데이트 후 반드시 로컬에서 테스트하고, 정상 동작을 확인한 뒤 배포합니다.
  4. 수정 기록: 이후 업데이트를 쉽게 하려면 개인화 수정 목록을 유지하는 것이 좋습니다.

관련 자료 ​

문서 버전: 0.1.0 | 마지막 업데이트: 2025-08-19