pub: 핵심 개념, Dart 패키지 관리자 및 pubspec.yaml

pub란?

pub (Package Universal Browser) — Dart SDK와 함께 제공되는 내장 패키지 관리자입니다. 외부 라이브러리를 관리하고, 버전 충돌을 해결하며, 전이적 의존성을 다운로드하고 패키지를 로컬에 캐시합니다. Flutter 생태계에서 pub는 탐색 플러그인, HTTP 클라이언트, 상태 관리자 및 기타 구성 요소를 연결하는 주요 도구로 사용됩니다.

pub의 주요 기능은 다음과 같습니다: pub.dev 레지스트리에서 의존성 설치, 로컬 경로(경로 의존성) 및 git 리포지토리; 의미적 버전 관리 규칙에 따른 버전 해결; 시스템 디렉토리에 다운로드된 패키지의 캐싱; 공개 레지스트리에 자체 패키지 게시. 이러한 모든 작업은 CLI 명령어 dart pub 또는 이에 상응하는 flutter pub를 통해 사용할 수 있습니다.

pub의 아키텍처는 폐쇄 의존성 그래프를 기반으로 합니다: 관리자는 각 패키지가 정확히 한 번 나타나는 트리를 구축합니다. 두 라이브러리가 동일한 패키지의 다른 버전을 필요로 하는 경우, pub는 호환 가능한 범위를 찾거나 충돌 오류를 보고합니다. 이는 동일한 패키지의 여러 버전을 다른 트리 노드에서 허용하는 npm의 접근 방식과 다릅니다.

pubspec.yaml 구조

pubspec.yaml 파일 — Dart 또는 Flutter 프로젝트의 중앙 구성 파일입니다. YAML 형식으로 작성되며 메타데이터, 의존성, 빌드 구성 및 SDK 제약 조건이 포함됩니다. 다음은 Flutter 애플리케이션의 일반적인 예입니다:

name: my_app
description: Flutter 앱 예시
version: 1.0.0+1
publish_to: none

environment:
  sdk: ">=3.0.0 <4.0.0"
  flutter: ">=3.10.0"

dependencies:
  flutter:
    sdk: flutter
  http: ^1.1.0
  provider: ^6.0.5
  shared_preferences: ^2.2.0
  path_provider: ^2.1.0

dev_dependencies:
  flutter_test:
    sdk: flutter
  flutter_lints: ^3.0.0
  mockito: ^5.4.3

flutter:
  uses-material-design: true
  assets:
    - assets/images/
    - assets/fonts/

pubspec.yaml의 주요 필드: name — 고유 패키지 이름(라틴 문자, 밑줄, 숫자만); description — 간단한 설명(게시에 필수); version — 더하기 기호 뒤에 선택적 빌드 번호가 있는 의미적 버전; environment — 최소 Dart SDK 및 Flutter SDK 버전; dependencies — 주요 애플리케이션 의존성; dev_dependencies — 개발 및 테스트 전용 의존성; flutter — Flutter 구성 섹션(에셋, 폰트, 플러그인).

publish_to 필드는 게시 가능 여부를 제어합니다: 값 none은 게시를 금지하며(애플리케이션에 일반적), 기본값은 https://pub.dev입니다. dependency_overrides 필드는 충돌 상황에서 패키지 버전을 강제로 재정의할 수 있습니다 — 주의해서 사용하고, 임시 해결책으로만 사용하세요.

의존성 및 유형

pub는 네 가지 유형의 의존성을 지원하며, 각각 pubspec.yaml 내에서 고유한 구문으로 지정됩니다:

호스티드(hosted)

표준 유형 — 패키지가 pub.dev 레지스트리 또는 다른 호환 레지스트리에서 다운로드됩니다. 패키지 이름과 버전을 지정합니다. 예: http: ^1.1.0은 캐럿 버전 관리 규칙에 따라 범위 >=1.1.0 및 <2.0.0에서 최신 호환 버전을 다운로드합니다.

SDK 의존성

Flutter SDK 또는 Dart SDK를 포함하는 데 사용됩니다. 구문: flutter: sdk: flutter. 패키지는 레지스트리가 아닌 로컬 Flutter SDK 설치에서 가져옵니다. SDK 의존성은 버전 관리되지 않습니다 — 해당 버전은 현재 설치된 Flutter 버전에 의해 결정됩니다.

경로(path)

패키지가 포함된 로컬 디렉토리를 가리킵니다. 게시하지 않고 라이브러리를 개발하고 테스트할 때 유용합니다. 구문:

dependencies:
  my_local_lib:
    path: ../my_local_lib

경로 의존성은 pubspec.lock에 고정되지 않습니다 — 업데이트할 때마다 지정된 경로에서 다시 해결됩니다.

Git

git 리포지토리에서 직접 패키지를 포함할 수 있습니다. 브랜치, 태그 및 커밋이 지원됩니다:

dependencies:
  my_git_lib:
    git:
      url: https://github.com/user/my_git_lib.git
      ref: main

Git 의존성은 포크, 미게시된 수정 또는 Pull Request 작업에 편리합니다. 빌드 중 예기치 않은 변경을 방지하려면 브랜치 대신 특정 태그 또는 커밋을 지정하는 것이 좋습니다.

버전 관리 및 범위

pub는 Semantic Versioning 2.0을 엄격히 따릅니다: 형식 MAJOR.MINOR.PATCH(MAJOR — 호환되지 않는 변경, MINOR — 이전 버전과 호환되는 추가, PATCH — 이전 버전과 호환되는 수정). 이 체계를 기반으로 pub는 패키지 호환성을 판단하고 충돌을 해결합니다.

pubspec.yaml에서 버전을 지정하는 데 세 가지 주요 연산자가 사용됩니다:

• 캐럿(^) — ^1.2.3은 >=1.2.3 및 <2.0.0과 동일합니다. 가장 일반적인 연산자로, 주 버전 내에서 호환성을 의미합니다. 주 버전이 0(영)인 패키지의 경우 — ^0.1.2는 >=0.1.2 및 <0.2.0을 의미하며, 불안정한 버전에 대한 SemVer 규칙을 따릅니다.
• 틸드(~) — ~1.2.3은 >=1.2.3 및 <1.3.0과 동일합니다. 부 버전을 고정하고 패치 업데이트만 허용합니다. 덜 자주 사용되며, 주로 부 버전 수준에서 비호환성이 알려진 경우에 사용됩니다.
• 정확한 범위 — >=1.2.0 <2.0.0 — 완전한 제어를 제공하는 명시적 표기법입니다. 복잡한 제약 조건(예: 전이적 의존성의 여러 버전을 사용하는 경우)에 유용합니다.

dart pub get을 실행하면 pub는 해결된 모든 패키지(직접 및 전이적)의 정확한 버전을 고정하는 pubspec.lock 파일을 생성합니다. 이 파일은 모든 머신에서 재현 가능한 빌드를 보장하기 위해 버전 관리에 포함해야 합니다. dart pub upgrade를 실행하면 잠금 파일이 지정된 제약 조건 내에서 최신 호환 버전으로 업데이트됩니다.

의존성 충돌 오류는 두 패키지가 동일한 의존성의 겹치지 않는 범위를 필요로 할 때 발생합니다. pub는 어떤 패키지가 충돌 중이고 그 이유를 보고합니다. 해결책: 충돌하는 패키지 중 하나를 호환 가능한 버전으로 업데이트하고, dependency_overrides(임시 조치)를 사용하거나 대체 패키지로 전환합니다.

pub 주요 명령어

모든 pub 작업은 통합 CLI 인터페이스를 통해 수행됩니다. Dart SDK는 dart pub 명령어를 사용하고, Flutter SDK는 이에 상응하는 flutter pub를 사용합니다(추가로 Flutter SDK 의존성 및 플러그인을 고려). 주요 명령어는 다음과 같습니다:

• dart pub get — pubspec.yaml에 지정된 모든 의존성을 다운로드하고, 버전을 해결하며 pubspec.lock을 생성/업데이트합니다. 프로젝트를 처음 클론하거나 의존성을 변경한 후 실행합니다.
• dart pub upgrade — pubspec.yaml 제약 조건 내에서 모든 의존성을 최신 버전으로 업데이트하고 pubspec.lock을 덮어씁니다. 개별 패키지를 업데이트할 수 있습니다: dart pub upgrade http.
• dart pub add <package> — pubspec.yaml에 새 의존성을 추가하고 즉시 pub get을 실행합니다. 예: dart pub add dio는 dio 패키지의 최신 버전을 추가합니다.
• dart pub remove <package> — pubspec.yaml에서 의존성을 제거하고 그래프 해결을 다시 실행합니다.
• dart pub cache repair — 캐시된 모든 패키지를 다시 로드합니다. 로컬 캐시가 손상되었거나 체크섬 오류가 발생한 경우 도움이 됩니다.
• dart pub deps — 편리한 텍스트 형식으로 의존성 트리를 표시합니다. 전이적 의존성 분석 및 중복 찾기에 유용합니다.
• dart pub publish — 현재 패키지를 pub.dev에 게시합니다. 게시 전에 pubspec.yaml, 라이선스 및 설명을 검증합니다.
• dart pub outdated — 현재, 원하는 및 최신 사용 가능 버전을 나타내는 오래된 의존성 목록을 표시합니다. npm outdated와 유사합니다.

모든 명령어는 축약형 dart pub get을 dart pub g로도 사용할 수 있습니다(모든 축약형이 있는 것은 아님). Flutter 프로젝트에서는 명령어 앞에 flutter가 붙습니다: flutter pub get, flutter pub add 등. Flutter 버전은 대상 플랫폼과의 플러그인 호환성도 추가로 확인합니다.

pub.dev에 게시

pub.dev — Dart 및 Flutter 생태계의 중앙 패키지 레지스트리입니다. 2025년 1월 기준으로 50,000개 이상의 패키지가 게시되었으며, 총 다운로드 수는 100억 회를 초과합니다. 각 패키지에는 설명, 문서, 인기 점수, Pub Points 평가 및 버전이 포함된 페이지가 있습니다.

Pub Points — 0에서 130점까지의 자동화된 패키지 품질 평가 시스템입니다. 라이선스 유무, 설명, 예제, 최신 안정적인 Dart 버전과의 호환성, 취약점 부재, 테스트 커버리지, 형식 지정 정확성을 고려합니다. 높은 점수는 검색에서 패키지의 가시성과 사용자 신뢰를 높입니다.

게시 프로세스는 여러 단계로 구성됩니다:

1. pubspec.yaml 확인: name, description, version, license가 있는지 확인합니다(SPDX 식별자 권장, 예: MIT).
2. dart pub publish --dry-run 실행 — 서버에 보내지 않고 게시를 시뮬레이션하고, 패키지에 포함될 모든 파일과 가능한 오류를 표시합니다.
3. 첫 게시 시 Google 계정으로 인증: dart pub publish가 OAuth 인증을 위해 브라우저를 엽니다.
4. 터미널에서 게시를 확인합니다. 업로드가 성공하면 패키지가 몇 분 내에 pub.dev에 나타납니다.

중요 규칙: 고유한 이름을 가진 패키지만 게시할 수 있습니다; 한 번 게시된 버전은 삭제할 수 없습니다(7일 이내에 dart pub unpublish로 숨길 수만 있음); 주요 업데이트의 경우 Semantic Versioning 규칙을 따르고, 주 버전을 변경하지 않고 공개 API를 깨뜨리지 마세요.