pubspec.yaml 완전 정복
pubspec.yaml은 Dart 프로젝트의 신분증입니다. 패키지 이름, 버전, 의존성, SDK 제약까지 프로젝트의 모든 메타데이터를 담고 있습니다. 잘못된 설정 하나가 빌드 실패나 패키지 배포 오류로 이어지기 때문에 정확하게 이해해야 합니다.
전체 구조 개요
name: my_packagedescription: A Dart package for doing something useful.version: 1.2.3repository: https://github.com/user/my_packagehomepage: https://my_package.devissue_tracker: https://github.com/user/my_package/issuesenvironment: sdk: '>=3.0.0 <4.0.0'dependencies: http: ^1.2.0 path: ^1.9.0 collection: ^1.18.0dev_dependencies: lints: ^4.0.0 test: ^1.25.0 build_runner: ^2.4.0flutter: assets: - assets/images/name
패키지 이름입니다. pub.dev에서 식별자로 사용하며, 다른 패키지에서 import할 때 이 이름을 씁니다.
name: my_awesome_package규칙:
- 소문자와 언더스코어만 사용합니다.
- 숫자로 시작하면 안 됩니다.
dart,flutter같은 예약어는 사용할 수 없습니다.
// 다른 패키지에서 import할 때
import 'package:my_awesome_package/my_awesome_package.dart';
version
Semantic Versioning(semver) 형식을 따릅니다.
version: 1.2.3| 버전 구성 | 의미 |
|---|---|
1 (Major) |
하위 호환 불가 변경 |
2 (Minor) |
하위 호환 기능 추가 |
3 (Patch) |
버그 수정 |
사전 출시 버전도 지원합니다.
version: 2.0.0-beta.1version: 1.5.0-rc.2pub.dev에 패키지를 올리지 않는 앱이라면 version 필드는 선택 사항입니다.
environment
사용 가능한 Dart SDK 버전 범위를 지정합니다.
environment: sdk: '>=3.0.0 <4.0.0'이 설정이 맞지 않으면 dart pub get이 실패합니다. Flutter 프로젝트는 Flutter SDK 버전도 지정합니다.
environment: sdk: '>=3.0.0 <4.0.0' flutter: '>=3.16.0'dependencies
런타임에 필요한 패키지입니다. 앱이나 라이브러리가 실행될 때 반드시 있어야 합니다.
dependencies: # pub.dev 패키지 — 버전 제약 http: ^1.2.0 path: '>=1.8.0 <2.0.0' collection: any # 로컬 경로 의존성 (개발 중인 로컬 패키지) my_utils: path: ../my_utils # Git 의존성 some_package: git: url: https://github.com/user/some_package.git ref: main # 브랜치, 태그, 커밋 해시 모두 가능dev_dependencies
개발과 테스트에만 필요한 패키지입니다. 프로덕션 빌드에는 포함되지 않습니다.
dev_dependencies: # lint 규칙 lints: ^4.0.0 # 테스트 프레임워크 test: ^1.25.0 mockito: ^5.4.0 # 코드 생성 build_runner: ^2.4.0 json_serializable: ^6.7.0 # 성능 분석 benchmark_harness: ^2.2.0버전 제약 문법
dependencies: # 캐럿(^): 마이너/패치만 허용, Major 고정 package_a: ^1.2.3 # >=1.2.3 <2.0.0 # 틸드(~): 패치만 허용 package_b: ~1.2.3 # >=1.2.3 <1.3.0 # 범위 지정 package_c: '>=1.0.0 <2.0.0' # 정확한 버전 (권장하지 않음) package_d: 1.2.3 # 어떤 버전이든 OK (권장하지 않음) package_e: any실무에서는 ^ (캐럿)을 가장 많이 씁니다. 호환 업데이트를 자동으로 받으면서 Major 버전 변경으로 인한 파괴적 변경은 막아줍니다.
pubspec.lock
dart pub get 실행 후 생성되는 파일입니다. 실제로 설치된 패키지의 정확한 버전을 기록합니다.
# pubspec.lock (자동 생성, 수동 편집 금지)packages: http: dependency: "direct main" description: name: http sha256: abc123... url: "https://pub.dartlang.org" source: hosted version: "1.2.1"앱 프로젝트: pubspec.lock을 git에 커밋합니다. 팀 전체가 동일한 버전을 사용하게 됩니다.
라이브러리 패키지: pubspec.lock을 .gitignore에 추가합니다. 사용자마다 다른 환경에서 최적 버전이 결정되어야 하기 때문입니다.
추가 메타데이터 (pub.dev 배포용)
pub.dev에 패키지를 올릴 때 필요한 필드입니다.
name: my_packagedescription: >- A well-crafted Dart package that solves common problems. Supports Dart 3.x with full null safety.version: 1.0.0repository: https://github.com/user/my_packagehomepage: https://my_package.devdocumentation: https://pub.dev/documentation/my_package# 오픈소스 라이선스# (pub.dev 점수에 영향)pub publish 전에 dart pub publish --dry-run으로 유효성을 검사합니다.
dart pub publish --dry-run# 배포 검사 결과 출력 (실제 배포는 안 함)자주 발생하는 오류
version solving failed
Because my_app depends on package_a ^1.0.0 and package_b ^2.0.0,
and package_b 2.0.0 depends on package_a ^2.0.0,
version solving failed.
package_a 버전이 충돌합니다. 다음 챕터에서 해결 방법을 다룹니다.
SDK constraint not satisfied
The current Dart SDK version is 3.5.0.
Because my_package requires SDK >=3.8.0, version solving failed.
environment.sdk 제약을 현재 SDK 버전에 맞게 수정하거나 SDK를 업그레이드합니다.
정리
이번 챕터에서 다룬 내용입니다.
name,version,environment.sdk는 모든 Dart 패키지의 필수 요소입니다.dependencies는 런타임 의존성,dev_dependencies는 개발/테스트 의존성입니다.- 버전 제약은
^(캐럿)을 기본으로 사용합니다. pubspec.lock은 앱에서는 커밋하고, 라이브러리에서는.gitignore에 추가합니다.
다음 챕터에서는 dart pub 명령어로 의존성을 실제로 관리하는 방법을 다룹니다.