pubspec.yaml — 개념, 구조 및 Flutter 종속성 구성

pubspec.yaml이란

pubspec.yaml은 YAML 형식의 매니페스트 파일로, pub 패키지 관리자가 Dart 및 Flutter 프로젝트를 관리하는 데 사용합니다. 프로젝트 루트에 위치하며 flutter pub get 명령어가 실행될 때마다 처리됩니다. 구성이 여러 파일에 분산되어 있는 다른 플랫폼과 달리, Flutter는 모든 요구 사항에 대해 단일 중앙 집중식 매니페스트를 사용합니다.

파일에는 메타데이터(프로젝트 이름, 설명, 버전, 작성자)가 포함됩니다. 이 데이터는 pub.dev에 패키지를 게시할 때와 App Store 및 Google Play용 애플리케이션을 빌드할 때 사용됩니다. description 필드는 패키지 검색 결과에 표시되므로, 정보를 담고 있어야 하며 다른 개발자가 라이브러리를 찾을 수 있는 키워드를 포함해야 합니다.

올바른 pubspec.yaml 없이는 Flutter 프로젝트를 빌드할 수 없습니다. 구문 오류나 잘못된 들여쓰기는 Error on line X 메시지와 함께 즉각적인 컴파일 실패로 이어집니다. YAML은 공백에 민감합니다. 추가 공백 하나가 데이터 구조를 변경하고, 탭은 구문 오류를 유발합니다. 따라서 pubspec.yaml을 수동으로 편집할 때는 VS Code의 공식 Flutter 확장 프로그램과 같이 YAML 구문 강조 기능이 있는 편집기를 사용하는 것이 중요합니다.

pubspec.yaml의 주요 섹션

pubspec.yaml은 필수 섹션과 선택적 섹션으로 구성됩니다. 각 섹션은 프로젝트 구성의 특정 측면을 담당합니다. 섹션의 순서는 중요하지 않지만, 커뮤니티 관례에 따라 메타데이터, 환경, 종속성, 리소스, 플랫폼 순서를 따릅니다.

name 및 description

name 필드는 소문자 라틴 문자, 숫자 및 밑줄로만 구성된 snake_case 형식의 고유 패키지 식별자를 설정합니다. description 필드는 최대 180자의 간략한 프로젝트 요약으로, pub.dev에 게시하는 데 필수입니다. 설명은 이름을 반복하지 않고 패키지의 목적을 설명해야 하며, 저장소 검색 최적화를 위한 키워드를 포함해야 합니다.

name: my_flutter_app
description: Flutter 기반 할 일 관리 앱
publish_to: 'none'

version 및 environment

version 필드는 더하기 기호(1.0.0+1) 뒤에 선택적 빌드 번호와 함께 시맨틱 버전 관리 major.minor.patch를 사용합니다. environment 섹션은 호환성을 보장하기 위해 Dart 및 Flutter SDK의 최소 및 최대 버전을 설정합니다. 새 SDK 버전에 프로젝트 코드와 호환되지 않는 변경 사항이 포함된 경우, 빌드는 명확한 오류 메시지와 함께 중단됩니다.

version: 1.0.0+1
environment:
  sdk: '>=3.2.0 <4.0.0'
  flutter: '>=3.16.0'

dependencies 및 dev_dependencies

dependencies 섹션은 런타임에 애플리케이션 실행에 필요한 패키지를 나열합니다. dev_dependencies 섹션에는 테스트, 코드 생성 및 개발용 패키지가 포함되며, 릴리스 빌드에는 포함되지 않습니다. 종속성을 분리하는 것은 성능에 매우 중요합니다. dependencies의 각 패키지는 최종 APK 또는 IPA 크기를 증가시키고, 추가 라이브러리 초기화로 인한 애플리케이션 시작 시간도 증가시킵니다.

dependencies:
  flutter:
    sdk: flutter
  http: ^1.2.0
  provider: ^6.1.0
  shared_preferences: ^2.2.0
  cached_network_image: ^3.3.0

dev_dependencies:
  flutter_test:
    sdk: flutter
  mockito: ^5.4.0
  build_runner: ^2.4.0

에셋 및 글꼴 구성

flutter 섹션에는 리소스, 글꼴 및 플랫폼 매개변수를 구성하기 위한 하위 섹션이 포함되어 있습니다. 리소스는 특정 파일이나 전체 디렉터리를 지정하는 paths 배열을 통해 연결됩니다. 모든 경로는 pubspec.yaml 기준이 아닌 프로젝트 루트 기준으로 지정됩니다. 이는 초보 Flutter 개발자에게 종종 혼란을 주는 중요한 차이점입니다.

flutter:
  uses-material-design: true
  assets:
    - assets/images/
    - assets/icons/
    - assets/config.json
    - assets/data/translations/
  fonts:
    - family: RobotoMono
      fonts:
        - asset: fonts/RobotoMono-Regular.ttf
        - asset: fonts/RobotoMono-Bold.ttf
          weight: 700
        - asset: fonts/RobotoMono-Italic.ttf
          style: italic

pubspec.yaml을 통해 에셋을 연결하면 런타임에 AssetBundle을 통해 파일에 액세스할 수 있습니다. 이는 이미지, JSON, 텍스트 파일 및 기타 모든 리소스에 대해 작동합니다. Flutter는 다양한 화면 해상도를 자동으로 지원합니다. images/2x/ 및 images/3x/를 추가하면 Flutter는 기기 픽셀 비율에 따라 적절한 이미지 버전을 선택합니다. 이렇게 하려면 assets에 루트 images/ 폴더만 지정하면 됩니다.

사용자 지정 글꼴은 family 이름과 스타일 목록과 함께 fonts 섹션을 통해 추가됩니다. pubspec.yaml을 수정한 후에는 flutter pub get을 실행하여 변경 사항을 적용해야 합니다. 글꼴은 MaterialApp 테마에서 전역적으로 사용하거나 특정 위젯에서 로컬로 사용할 수 있습니다. 각 스타일에 대해 weight(100–900) 및 style(normal, italic)을 지정할 수 있어, 코드에서 FontWeight 및 FontStyle을 사용할 때 Flutter가 올바른 글꼴 파일을 선택할 수 있습니다.

종속성 및 버전 관리

pub은 종속성의 소스를 지정하는 여러 방법을 지원합니다: pub.dev, Git 저장소, 로컬 경로 및 비공개 저장소. 소스 선택은 개발 단계에 따라 달라집니다. 안정적인 버전에는 pub.dev, 포크 및 사용자 지정 수정에는 Git, 병렬로 개발 중인 라이브러리에는 로컬 경로를 사용합니다.

^version 연산자는 호환 가능한 버전을 의미합니다. ^1.2.0은 >=1.2.0 및 <2.0.0 버전을 허용합니다. 이는 CocoaPods의 ~> 연산자 및 npm의 Caret 연산자와 유사합니다. pub은 SAT 솔버 알고리즘을 통해 종속성 지옥을 자동으로 해결하여 모든 제약 조건을 충족하는 버전 조합을 찾습니다. 그러한 조합이 존재하지 않는 경우, pub은 충돌하는 패키지를 나타내는 자세한 메시지를 출력합니다.

pubspec.lock 파일은 종속성의 정확한 버전을 고정합니다. 애플리케이션의 경우 팀의 모든 머신에서 재현 가능한 빌드를 보장하기 위해 버전 관리에 저장해야 합니다. 라이브러리의 경우, 라이브러리 사용자가 다른 종속성 버전으로 사용할 수 있도록 pubspec.lock을 저장소에 포함하지 않습니다. flutter pub upgrade 명령어는 pubspec.yaml의 제약 조건에 따라 모든 종속성을 업데이트하고, flutter pub outdated는 업데이트할 수 있는 패키지를 표시합니다.

빌드 및 게시 구성

pub.dev에 애플리케이션을 게시하려면 publish_to 섹션에서 설정을 지정합니다. 'none' 값은 실수로 패키지가 게시되는 것을 방지하며, 이는 내부 또는 비공개 프로젝트에 중요합니다. publish_to가 없으면 pub은 기본 pub.dev에 패키지를 게시하려고 시도하여 원치 않는 코드 유출이 발생할 수 있습니다.

flutter 섹션에는 플랫폼 매개변수가 포함됩니다: generate는 플랫폼 파일 자동 생성을 위한 것이고, deferred-components는 모듈식 기능 로딩을 위한 것입니다. generate: true 매개변수는 flutter create --platforms를 통해 새 플랫폼을 추가할 때 Flutter가 플랫폼 프로젝트(iOS, Android, Web)를 자동으로 생성하고 업데이트하도록 강제합니다. 이 매개변수가 없으면 플랫폼 폴더 구조가 pubspec.yaml과 동기화되지 않을 수 있습니다.

flutter:
  generate: true
  deferred-components:
    - name: photoEditor
      libraries:
        - package:photo_editor/library.dart

platforms 섹션은 패키지의 대상 플랫폼을 설정합니다. 애플리케이션의 경우 flutter create를 통해 특정 플랫폼 지원을 추가할 때 자동으로 결정됩니다. 플랫폼은 pubspec.yaml을 편집하여 수동으로 추가 및 제거할 수 있습니다. 지연 구성 요소(Deferred Components)는 애플리케이션의 일부를 필요에 따라 로드하여 설치 크기를 줄일 수 있습니다. 이는 특히 게임이나 사용 빈도가 낮은 콘텐츠가 많은 애플리케이션에 적합합니다.

패키지를 게시할 때 pub은 모든 pubspec.yaml 필드가 저장소의 요구 사항을 준수하는지 확인합니다. 필수 필드 name, version 및 description이 없으면 게시가 거부됩니다. 또한 라이선스의 정확성, README.md 및 CHANGELOG.md의 존재 여부가 확인됩니다. 코드 분석기 오류(dart analyze)가 있는 패키지도 검증에 실패합니다. 성공적으로 게시되면 패키지는 몇 분 내에 pub.dev에서 사용할 수 있습니다.

dependency_overrides 섹션을 사용하면 전이적 종속성의 제약 조건을 무시하고 특정 패키지 버전을 강제로 지정할 수 있습니다. 이는 강력하지만 위험한 메커니즘입니다. 잘못 사용하면 라이브러리 비호환성이 발생할 수 있습니다. dependency_overrides는 충돌 해결이나 새 버전 테스트를 위해 일시적으로만 사용하세요. 주요 종속성을 수정한 후에는 장기적으로 프로젝트의 종속성 그래프가 손상되지 않도록 재정의를 제거해야 합니다.

pubspec.yaml의 executables 섹션을 사용하면 패키지 활성화 시 pub이 PATH에 설치하는 실행 가능한 스크립트를 지정할 수 있습니다. 이는 build_runner 또는 dart_code_metrics와 같이 Dart로 작성된 CLI 도구에 유용합니다. dart pub global activate 명령어는 패키지를 전역적으로 설치하여 executables에 지정된 스크립트를 터미널에서 액세스할 수 있게 합니다. 애플리케이션의 경우 진입점이 lib/main.dart의 main을 통해 정의되므로 executables는 일반적으로 사용되지 않습니다.