🔢 SemVer 완전 정복 — 버전 기호의 진짜 의미와 함정

📋 목차

• 📌 이 문서를 읽기 전에
• 🤔 왜 알아야 하는가
• 🏗️ SemVer 의 구조
• 🔣 범위 기호 총정리
• 🧮 복합 범위 표현식
• 🏷️ 프리릴리즈 & dist-tag
• 🔥 실무에서 터지는 SemVer 함정 5가지
• 🛠️ 버전 관련 유용한 명령어
• 🏁 이번에 배운 내용 총정리
• 📝 마무리 퀴즈
• 🐣 영철이의 퇴근 일기
• 🔗 더 알아보기

📌 이 문서를 읽기 전에

⏱️ 예상 읽기 시간: 18분(전체) / 핵심 파트만: 8분 (범위 기호 + 함정)

🗺️ 이 문서의 흐름
SemVer 구조 이해 → 범위 기호 완전 정복 → 복합 범위 → 프리릴리즈 → 실무 함정 5가지 → 유용한 명령어

🎯 이 문서를 다 읽으면 할 수 있는 것

• ^, ~, *, exact, >=, || 의 허용 범위를 즉시 말할 수 있다
• ^0.x.x 가 ^1.x.x 와 다르게 동작하는 이유를 설명할 수 있다
• npm dist-tag 가 무엇인지, 왜 쓰는지 이해한다
• npm version patch 명령어로 버전을 올리고 git 태그를 생성할 수 있다
• SemVer 를 지키지 않는 라이브러리로 인해 생기는 사고를 예측하고 대비할 수 있다

🗺️ 이 문서의 배경 세계관: '영수네 커뮤니티'

• 🐣 영철 ( 신입 ): "리드 님, 어제 무서운 일이 있었어요. react-beautiful-dnd 업데이트했는데 갑자기 드래그 앤 드롭이 완전히 망가졌어요. package.json 에 ^14.0.0 이라고 써있었는데 어느 순간 14.3.0 이 설치되어있더라고요. 그게 문제였던 거 맞죠? ^ 붙이면 그냥 자동으로 업데이트되는 건가요? 그리고 pnpm 쓰는 팀에서는 ~ 를 쓴다고 하던데 차이가 뭔가요?"
• 🦁 영호 ( 리드 ): "영철 님, 범인은 두 가지예요. 첫째, ^14.0.0 이 14.x.x 전체를 허용한다는 걸 몰랐던 것. 둘째, package-lock.json 이 없었거나 무시됐던 것. 그 라이브러리가 14.3.0 에서 Breaking Change 를 MINOR 버전에 넣은 거예요 — SemVer 위반이죠. 이런 경우를 대비하는 방법까지 같이 알아야 해요."

🤔 왜 알아야 하는가

영수네 커뮤니티 팀이 라이브 서비스를 배포한 다음 날 아침. 영철이가 출근하자마자 슬랙 알림이 쏟아졌다. "스터디 목록 드래그 앤 드롭이 안 돼요!"

GitHub Actions 에서 npm install 이 실행될 때마다 react-beautiful-dnd@14.3.0 이 새로 설치되고 있었다. ^14.0.0 범위 안에 있으니까. 그런데 14.3.0 버전에서 내부 동작이 바뀌어 기존 코드가 깨진 것이다.

결론: 버전 기호의 정확한 의미를 모르면, 내 코드를 건드리지 않아도 어느 날 갑자기 서비스가 망가진다.

🏗️ SemVer 의 구조 — MAJOR.MINOR.PATCH

MAJOR  .  MINOR  .  PATCH  [-prerelease]  [+buildmetadata]
  14   .    3    .    0    -rc.1           +sha.20240101

🦁 영호의 핵심 인사이트: "SemVer 는 '약속'이에요. MAJOR 를 올리지 않는 한 기존 코드가 깨져선 안 된다는 커뮤니티의 계약이죠. 하지만 이 약속을 지키지 않는 라이브러리들이 있고, 그게 실무 사고의 주요 원인이에요."

0.x.x 버전은 특수하다

0.MINOR.PATCH — 초기 개발 단계 (Unstable)

0.x.x 일 때는 MINOR 가 Breaking Change 를 포함할 수 있다. 즉 ^0.3.0 은 0.3.x 범위만 허용하지, 0.4.0 을 허용하지 않는다. 이 규칙이 다음 섹션의 ^ 기호 동작에서 핵심이다.

🔣 범위 기호 총정리 — ^, ~, *, exact

^ (Caret) — 가장 흔하게 쓰이는 기호

규칙: 첫 번째 0이 아닌 숫자를 고정하고, 나머지 허용

^1.2.3  ≡  >=1.2.3 <2.0.0   (MAJOR 고정)
^0.2.3  ≡  >=0.2.3 <0.3.0   (MINOR 고정 — 0.x.x 특수규칙!)
^0.0.3  ≡  >=0.0.3 <0.0.4   (PATCH 고정 — 0.0.x 특수규칙!)
^1.2.x  ≡  >=1.2.0 <2.0.0
^1.x    ≡  >=1.0.0 <2.0.0

🔥 ^0.x.x 함정: 많은 신입이 ^0.3.0 을 "0 이상 모든 버전" 으로 오해한다. 실제로는 0.3.x 만 허용한다.

~ (Tilde) — 보수적인 업데이트

규칙: MINOR 가 명시되면 PATCH 만 허용, MINOR 가 없으면 MINOR 까지 허용

~1.2.3  ≡  >=1.2.3 <1.3.0   (PATCH 만 허용)
~1.2    ≡  >=1.2.0 <1.3.0   (PATCH 만 허용)
~1      ≡  >=1.0.0 <2.0.0   (MINOR 까지 허용)
~0.2.3  ≡  >=0.2.3 <0.3.0

💡 ^ vs ~ 선택 가이드:

• ^ — 기능 업데이트도 자동으로 받고 싶을 때 (대부분의 경우)
• ~ — 패치(버그 수정)만 자동으로 받고 싶을 때 (더 보수적인 팀)

* (Wildcard) — 절대 쓰면 안 되는 기호

*  ≡  >=0.0.0   (모든 버전)

❌ 사용 금지: * 는 어떤 버전이든 허용한다. MAJOR 버전 업그레이드, Breaking Change 전부 허용하는 것이다. 실제 코드에서 이 기호가 보이면 즉시 제거해라.

exact (정확한 버전) — 최대한 보수적

{
  "dependencies": {
    // 🦁 앞에 ^ 나 ~ 기호가 전혀 없죠? 이건 "무슨 일이 있어도 딱 14.1.4 버전만 쓰겠다"는 선언입니다.
    // 다른 팀원이 npm install을 쳐도 절대 14.1.5로 올라가지 않습니다.
    "next": "14.1.4"
  }
}

정확히 이 버전만 허용. 자동 업데이트 없음.

🐣 영철: "그럼 exact 로 다 고정하면 안전한 거 아닌가요?"

🦁 영호: "보안 패치도 안 받는다는 단점이 있어요. 취약점이 발견됐을 때 버전을 하나하나 올려줘야 하고, 간접 의존성은 어차피 lock 파일이 관리해줘요. package.json 에는 ^ 로 범위를 선언하고 package-lock.json 이 정확한 버전을 고정하는 방식이 실무 표준이에요."

>=, <=, >, < — 명시적 범위

>=18.17.0          18.17.0 이상 모두
>=18.17.0 <19.0.0  18.17.0 이상, 19.0.0 미만

주로 engines 필드나 peerDependencies 에서 쓴다:

{
  "peerDependencies": {
    "react": ">=16.8.0 <19.0.0"
  }
}

🧮 복합 범위 표현식

|| — 여러 범위 중 하나

^16.0.0 || ^17.0.0 || ^18.0.0

"React 16, 17, 18 중 하나면 됨." 주로 peerDependencies 에서 여러 메이저 버전을 동시에 지원할 때 사용한다.

{
  "peerDependencies": {
    "react": "^16.8.6 || ^17.0.0 || ^18.0.0",
    "react-dom": "^16.8.6 || ^17.0.0 || ^18.0.0"
  }
}

하이픈 범위 (Hyphen Range)

1.2.3 - 2.3.4  ≡  >=1.2.3 <=2.3.4

🏷️ 프리릴리즈 & dist-tag

프리릴리즈 버전

1.0.0-alpha.1    개발 초기
1.0.0-beta.2     기능 완성, 테스트 중
1.0.0-rc.1       Release Candidate (최종 후보)
1.0.0            정식 출시

# 프리릴리즈 버전 설치
npm install next@canary        # 카나리 빌드
npm install react@beta         # 베타
npm install @tanstack/query@alpha  # 알파
 
# 정확한 프리릴리즈 버전 고정
npm install react@19.0.0-rc.1

🔥 중요: ^ 기호는 프리릴리즈 버전을 자동으로 포함하지 않는다. ^18.0.0 은 19.0.0-rc.1 을 허용하지 않는다.

dist-tag — 버전에 붙이는 별칭

npm dist-tag ls react        # react 의 모든 태그 확인

latest: 18.2.0        ← npm install react 시 기본으로 설치되는 버전
next: 19.0.0-rc.1
canary: 19.0.0-canary.xxx

npm install react             # latest 태그의 버전 설치 (18.2.0)
npm install react@next        # next 태그의 버전 설치 (19.0.0-rc.1)
npm install react@latest      # latest 태그 명시 (같은 결과)

내 패키지에 태그 붙이기:

npm publish --tag beta        # 배포하되 latest 가 아닌 beta 태그
npm dist-tag add @youngsoo/ui@1.1.0-beta.1 beta

🔥 실무에서 터지는 SemVer 함정 5가지

함정 1 — 라이브러리가 SemVer 를 지키지 않는 경우

react-beautiful-dnd@14.2.0 → 14.3.0 에서 API 변경 (Breaking Change!)
하지만 MINOR 만 올림 → SemVer 위반

대응:

{
  "dependencies": {
    // 💡 버그 없는 게 확인된 가장 마지막 버전으로 "완전 고정(exact)" 시켜서 더 이상 업데이트 안 되게 막는 응급조치입니다!
    "react-beautiful-dnd": "14.2.0"
  }
}

문제가 발견된 순간 exact 버전으로 고정하고, 업그레이드 시 반드시 체인지로그를 확인한다.

함정 2 — lock 파일 없이 ^ 버전 사용

팀원 A: npm install → react-beautiful-dnd@14.2.0 설치
1달 후
팀원 B: npm install → react-beautiful-dnd@14.3.0 설치 (새 버전 나옴)
→ A 로컬에서만 재현되는 버그 발생

대응: package-lock.json 을 항상 git 커밋. npm ci 사용.

함정 3 — ^0.x.x 를 ^1.x.x 처럼 착각

{
  "dependencies": {
    "some-early-lib": "^0.3.0"
  }
}

^0.3.0 은 0.3.x 만 허용한다. 0.4.0 은 포함하지 않는다. 이걸 모르고 "자동으로 업그레이드될 거야" 하면 안 된다.

함정 4 — npm update 와 npm install 혼동

npm install   # package-lock.json 기준으로 설치 (lock 있으면 버전 고정)
npm update    # package.json 의 범위 내에서 최신 버전으로 업그레이드 + lock 갱신

🚨 위험: npm update 는 package-lock.json 을 변경한다. CI 에서 절대 npm update 를 실행하면 안 된다.

함정 5 — peerDependencies 버전 범위와 실제 설치 버전 불일치

// some-ui-lib 의 peerDependencies
{
  "peerDependencies": {
    "react": "^17.0.0"
  }
}

내 앱이 react@18.x 를 쓰면 npm v7+ 에서는 에러, --legacy-peer-deps 로 강행하면 두 React 인스턴스 문제.

올바른 대응:

// 라이브러리가 React 18 을 지원하는 버전으로 업그레이드
{
  "dependencies": {
    "some-ui-lib": "^2.0.0"    // React 18 지원 버전
  }
}

🛠️ 버전 관련 유용한 명령어

# 현재 설치된 버전 확인
npm list react
npm list --depth=0        # 직접 의존성만
 
# 업데이트 가능한 패키지 확인
npm outdated
# → 현재버전 / 원하는버전 / 최신버전 비교 테이블 출력
 
# 버전 올리기 (package.json + git tag 동시 생성)
npm version patch         # x.x.1 → x.x.2
npm version minor         # x.1.x → x.2.0
npm version major         # 1.x.x → 2.0.0
npm version 2.1.0         # 정확한 버전으로 지정
 
# SemVer 범위 계산 (디버깅용)
npx semver "14.1.0" -r "^14.0.0"   # true/false 로 포함 여부 확인
 
# 레지스트리에서 패키지 버전 정보 확인
npm view react versions --json      # 전체 버전 목록
npm view react version              # 최신 버전만
npm view next dist-tags             # dist-tag 목록

🏁 이번에 배운 내용 총정리

📝 마무리 퀴즈

Q1. "some-lib": "^0.4.2" 가 허용하는 버전 범위는?

a) >=0.4.2 <1.0.0 — 0.x.x 전체
b) >=0.4.2 <0.5.0 — 0.4.x 만
c) >=0.0.0 — 모든 버전
d) >=0.4.2 <0.4.3 — 정확히 0.4.2 만

✅ 정답: b — >=0.4.2 <0.5.0

💡 상세 해설:

• 원리 설명: ^ 는 "첫 번째 0이 아닌 숫자를 고정"하는 규칙이다. 0.4.2 에서 첫 번째 0이 아닌 숫자는 4 (MINOR)다. 따라서 MINOR 를 고정하고 PATCH 만 허용해 0.4.x 범위가 된다. 0.x.x 패키지는 아직 불안정한 초기 개발 단계로 간주되기 때문에 ^ 가 더 보수적으로 동작한다.
• 오답 피드백: a — ^1.4.2 였다면 MAJOR 를 고정해 >=1.4.2 <2.0.0 이 맞지만, 0.4.2 에서는 다르다. c — * 의 동작이다. d — exact 버전 0.4.2 의 동작이다.
• 📌 핵심 기억법: "^0.x.x 는 MINOR 를 고정한다. 0.x.x 는 SemVer 특수 케이스!"

Q2. npm outdated 명령어 실행 결과가 아래와 같을 때, npm update 를 실행하면 설치되는 버전은?

Package      Current  Wanted   Latest
next         14.0.0   14.1.4   14.1.4
react        18.0.0   18.2.0   18.2.0
typescript   5.0.0    5.3.3    5.3.3

a) Current 열의 버전 (현재 버전 유지)
b) Wanted 열의 버전 (package.json 범위 내 최신)
c) Latest 열의 버전 (레지스트리 최신)
d) 아무것도 변경되지 않는다

✅ 정답: b — Wanted 열의 버전 (package.json 범위 내 최신)

💡 상세 해설:

• 원리 설명: npm update 는 package.json 에 명시된 버전 범위(^, ~ 등) 내에서 허용되는 최신 버전으로 업그레이드한다. Wanted 열이 바로 그 값이다. Latest 가 더 높더라도 범위 밖이면 설치하지 않는다. 예를 들어 "next": "^14.0.0" 이면 14.1.4 까지만 올리고 15.0.0 은 올리지 않는다.
• 오답 피드백: a — npm install (lock 파일 있을 때)의 동작이다. c — Latest 가 범위를 벗어나도 설치하는 방식은 없다. 직접 버전을 지정해야 한다. d — npm update 는 실제로 버전을 변경한다.
• 📌 핵심 기억법: "Wanted = package.json 범위 내 최신. npm update 는 Wanted 까지만 간다."

Q3. 🐣 영철이의 테스트 타임 — 실무 딜레마

영철이가 react-beautiful-dnd@^14.0.0 을 사용하고 있었는데, 14.3.0 이 릴리즈되면서 드래그 앤 드롭이 망가졌다 (SemVer 위반 — MINOR 에 Breaking Change 포함). 영호 리드가 "지금 당장 이 상황을 고치되, 앞으로 이런 사고를 예방하는 방법도 함께 적용해줘" 라고 했다. 어떻게 해결해야 하는가?

✅ 정답: 즉각 exact 버전 고정 + overrides 로 장기적 제어 + 체인지로그 모니터링 습관화

// 즉각 조치 — 14.2.0 으로 고정 (정상 동작하던 마지막 버전)
{
  "dependencies": {
    // 🦁 [1차 방어막] 내가 직접 쓰는 패키지의 버전을 확실한 버전으로 고정!
    "react-beautiful-dnd": "14.2.0"
  }
}

# package-lock.json 재생성
npm install

// 장기적 조치 — npm overrides 로 특정 버전 강제 (npm 8.3+)
{
  "overrides": {
    // 💡 [2차 방어막] 혹시 다른 패키지가 몰래 react-beautiful-dnd 의 문제 버전을 가져올까 봐
    // "누가 어떻게 가져오든 통일해서 이거만 써라!" 하고 찍어 누르는 강력한 외과 수술 설정입니다.
    "react-beautiful-dnd": "14.2.0"
  }
}

# GitHub Actions 에 체인지로그 확인 단계 추가
- name: Check for updates
  run: npm outdated || true    # 경고만 출력, 빌드 실패 안 함

💡 상세 해설:

• 즉각 조치: 정상 동작하는 마지막 버전(14.2.0)을 exact 버전으로 고정해 추가 업그레이드를 막는다.
• overrides 활용: overrides 는 npm 8.3+ 에서 지원하는 기능으로, 직접 의존성뿐 아니라 간접 의존성의 버전도 강제로 지정할 수 있다. 여러 패키지가 동일 라이브러리에 의존하는 경우 버전을 통일시킬 때 유용하다.
• 장기 예방: npm outdated 를 CI 에 포함해 주기적으로 업데이트 가능 목록을 확인한다. 업그레이드 전에는 반드시 해당 패키지의 CHANGELOG 를 읽는다. 특히 MINOR 버전 업그레이드도 체인지로그를 무시하면 안 된다.
• 📌 핵심 기억법: "SemVer 를 지키지 않는 라이브러리는 exact 로 고정하고, overrides 로 간접 의존성까지 제어한다."

🐣 영철이의 퇴근 일기

오늘 저녁은 집 근처 분식집에서 떡볶이 먹었다. 혼자 먹으면서 머릿속으로 SemVer 를 복기했다.

^ 기호가 그냥 "최신 버전" 이 아니라 "MAJOR 를 고정하고 MINOR 와 PATCH 를 허용한다" 는 건 알고 있었다. 근데 ^0.4.2 가 0.4.x 만 허용한다는 건 몰랐다. 0.x.x 에서는 MINOR 가 Breaking Change 를 포함할 수 있어서 더 보수적으로 동작하는 거였다. 오늘 그 차이 때문에 스스로 실험해봤다 — npx semver "0.4.2" -r "^0.4.2" 해보니 true 가 나오고, npx semver "0.5.0" -r "^0.4.2" 는 false 가 나오는 걸 직접 눈으로 확인했다.

💡 오늘의 교훈: "버전 기호는 약속이다. 라이브러리가 그 약속을 지킬 거라고 맹신하지 말고, lock 파일과 exact 버전 고정으로 직접 방어선을 쳐야 한다."

사실 오늘 react-beautiful-dnd 때문에 나온 장애 보고서 때문에 영수 님한테 좀 혼났다. 아직은 좀 아프지만, 이걸 이렇게 배우는 거라고 생각하기로 했다. 내일은 의존성 4종 세트를 파볼 거다. 헬스장 갔다 와서 씻고 자야겠다.

🔗 더 알아보기

• SemVer 공식 스펙 — semver.org
• npm 공식 문서 — About semantic versioning
• npm semver 계산기
• npm 공식 문서 — npm outdated
• npm 공식 문서 — npm version