Flutter 튜토리얼 66편: 패키지 사용하기
요약
핵심 요지
- 문제 정의: 모든 기능을 처음부터 직접 만들면 시간이 오래 걸리고 버그가 생기기 쉽다.
- 핵심 주장: 커뮤니티가 만든 패키지를 활용하면 개발 속도를 높이고 검증된 코드를 사용할 수 있다.
- 주요 근거: pub.dev에는 수만 개의 패키지가 있으며, Flutter Favorites로 품질이 검증된 패키지를 쉽게 찾을 수 있다.
- 실무 기준:
flutter pub add로 패키지를 추가하고, 버전 범위를 지정하여 호환성을 유지한다. - 한계: 패키지 품질이 천차만별이므로, 선택 시 점수, 유지보수 상태, 라이선스를 반드시 확인해야 한다.
문서가 설명하는 범위
- 패키지와 플러그인의 차이점
- pub.dev에서 패키지 검색하기
- 프로젝트에 패키지 추가하고 제거하기
- 버전 충돌 해결하기
- Flutter Favorites 프로그램 이해하기
읽는 시간: 12분 | 난이도: 초급
참고 자료
- Using packages - 공식 패키지 사용 가이드
- Flutter Favorites - Flutter Favorites 프로그램 안내
- pub.dev - Dart/Flutter 패키지 저장소
- Package dependencies - 의존성 관리 상세 문서
문제 상황
앱을 만들다 보면 다양한 기능이 필요합니다. HTTP 요청, 로컬 저장소, 상태 관리, UI 컴포넌트 등 모든 것을 직접 만들려면 시간이 오래 걸립니다.
// 모든 기능을 직접 구현하면?// - HTTP 클라이언트 구현: 1주일// - JSON 파싱 유틸리티: 3일// - 로컬 저장소 래퍼: 2일// - 날짜 선택기 UI: 1주일// 총 개발 시간: 3주 이상문제는 다음과 같습니다.
- 검증된 코드를 처음부터 다시 만드는 것은 비효율적이다.
- 직접 만든 코드는 버그가 있을 가능성이 높다.
- 유지보수와 업데이트를 모두 혼자 감당해야 한다.
해결 방법
Flutter 생태계에는 수만 개의 패키지가 있습니다. 다른 개발자들이 만들고 검증한 코드를 활용하면 빠르고 안정적으로 앱을 만들 수 있습니다.
챕터 1: 패키지와 플러그인 이해하기
Why
NOTEFlutter에서 “패키지”와 “플러그인”이라는 용어가 자주 등장합니다. 두 용어의 차이를 이해하면 필요한 라이브러리를 정확히 찾을 수 있습니다.
플러그인은 패키지의 한 종류입니다. 정식 명칭은 “플러그인 패키지”이지만, 보통 “플러그인”으로 줄여서 부릅니다.
What
NOTE**패키지(Package)**는 재사용 가능한 Dart 코드 모음입니다.
pubspec.yaml파일이 있는 디렉토리- 순수 Dart 코드만 포함할 수 있음
- 예:
http,provider,intl**플러그인(Plugin)**은 플랫폼 네이티브 코드를 포함하는 특수한 패키지입니다.
- Android(Kotlin/Java), iOS(Swift/Objective-C) 등의 코드 포함
- 카메라, GPS, 센서 등 기기 기능에 접근할 때 필요
- 예:
camera,geolocator,battery_plus
구분 패키지 플러그인 네이티브 코드 없음 있음 플랫폼 의존성 없음 있음 사용 예시 상태 관리, HTTP 카메라, GPS
How
TIP패키지인지 플러그인인지 확인하는 방법입니다.
pub.dev에서 확인:
- 패키지 페이지의 “Platforms” 섹션 확인
- Android, iOS 등 플랫폼별 아이콘이 있으면 플러그인
- “Dart” 아이콘만 있으면 순수 Dart 패키지
pubspec.yaml에서 확인:
# 순수 Dart 패키지flutter:plugin:platforms: {} # 비어있거나 이 섹션이 없음# 플러그인 패키지flutter:plugin:platforms:android:package: com.example.pluginios:pluginClass: MyPlugin
Watch out
WARNING플러그인 사용 시 주의사항:
- 플러그인을 추가한 후에는 앱을 완전히 재시작해야 합니다.
- 핫 리로드나 핫 리스타트로는 네이티브 코드가 적용되지 않습니다.
- 플러그인이 지원하지 않는 플랫폼에서 사용하면
MissingPluginException이 발생합니다.// 플랫폼 지원 여부 확인import 'dart:io' show Platform;if (Platform.isAndroid || Platform.isIOS) {// 모바일 전용 플러그인 사용} else {// 웹이나 데스크톱에서는 대체 로직}
챕터 2: pub.dev에서 패키지 찾기
Why
NOTEpub.dev는 Dart와 Flutter 패키지의 공식 저장소입니다. 수만 개의 패키지 중에서 좋은 패키지를 찾는 방법을 알아야 합니다.
잘못된 패키지를 선택하면 다음과 같은 문제가 생깁니다.
- 유지보수가 중단된 패키지: 보안 취약점 방치
- 품질이 낮은 패키지: 버그와 성능 문제
- 라이선스 문제: 상용 앱에서 사용 불가
What
NOTEpub.dev에서 패키지 품질을 판단하는 기준입니다.
점수 시스템:
- Likes: 개발자들이 누른 좋아요 수
- Pub Points: 문서화, 플랫폼 지원, 코드 품질 등을 평가한 점수 (최대 160점)
- Popularity: 얼마나 많은 프로젝트에서 사용하는지
Flutter Favorites1:
Flutter 팀과 커뮤니티 위원회가 선정한 고품질 패키지입니다.
- 높은 전반적 점수
- 허용적인 라이선스 (Apache, MIT, BSD 등)
- 완성도 높은 기능
- 검증된 퍼블리셔
- 좋은 문서화와 예제 코드
How
TIP패키지 검색 방법:
- pub.dev 접속
- 검색창에 키워드 입력 (예: “http”, “state management”)
- 플랫폼별 필터 적용 (Android, iOS, Web 등)
Flutter Favorites 찾기:
https://pub.dev/flutter/favorites플랫폼별 필터링:
플랫폼 검색 쿼리 Android sdk:flutter platform:androidiOS sdk:flutter platform:iosWeb sdk:flutter platform:web모든 플랫폼 필터 조합 가능 패키지 선택 체크리스트:
□ Pub Points 120점 이상□ 최근 6개월 내 업데이트□ Null Safety 지원□ 검증된 퍼블리셔 (verified publisher)□ 필요한 플랫폼 지원□ 라이선스 확인 (MIT, BSD, Apache 권장)□ GitHub 이슈 응답률 확인
Watch out
WARNING패키지 선택 시 주의사항:
- 다운로드 수만 보지 마세요: 오래된 패키지는 다운로드 수가 많아도 유지보수가 안 될 수 있습니다.
- 마지막 업데이트 확인: 1년 이상 업데이트가 없으면 주의하세요.
- 이슈 트래커 확인: 미해결 이슈가 너무 많으면 문제가 있을 수 있습니다.
- 라이선스 주의: GPL 라이선스는 상용 앱에서 문제가 될 수 있습니다.
챕터 3: 패키지 추가하기
Why
NOTE패키지를 찾았으면 프로젝트에 추가해야 합니다. Flutter는 두 가지 방법을 제공합니다.
- 명령어로 추가 (
flutter pub add)pubspec.yaml직접 수정명령어를 사용하면 최신 버전이 자동으로 설정되어 편리합니다.
What
NOTEflutter pub add 명령어:
Terminal window # 패키지 추가flutter pub add 패키지이름# 예시flutter pub add httpflutter pub add providerflutter pub add go_router이 명령어는 다음을 자동으로 수행합니다.
pubspec.yaml에 의존성 추가flutter pub get실행하여 패키지 다운로드pubspec.lock파일 업데이트
How
TIP방법 1: 명령어 사용 (권장)
Terminal window # 터미널에서 프로젝트 폴더로 이동cd my_flutter_app# 패키지 추가flutter pub add css_colors방법 2: pubspec.yaml 직접 수정
pubspec.yaml dependencies:flutter:sdk: fluttercss_colors: ^1.0.0 # 추가Terminal window # 패키지 설치flutter pub get패키지 사용하기:
// 1. import 추가import 'package:css_colors/css_colors.dart';// 2. 코드에서 사용Container(color: CSSColors.orange,)전체 예제:
import 'package:css_colors/css_colors.dart';import 'package:flutter/material.dart';void main() {runApp(const MyApp());}class MyApp extends StatelessWidget {const MyApp({super.key});@overrideWidget build(BuildContext context) {return MaterialApp(home: Scaffold(body: Container(color: CSSColors.coral),),);}}
Watch out
WARNING플러그인 추가 후 반드시 앱 재시작:
Terminal window # 핫 리로드/리스타트로는 네이티브 코드 적용 안 됨# 앱을 완전히 종료하고 다시 실행해야 함flutter runMissingPluginException 해결:
MissingPluginException(No implementation found for method X on channel Y)이 에러가 나타나면:
- 앱을 완전히 종료
flutter clean실행flutter pub get실행- 앱 다시 빌드 및 실행
챕터 4: 패키지 제거와 업데이트
Why
NOTE사용하지 않는 패키지는 제거해야 합니다. 불필요한 패키지는 앱 크기를 늘리고 빌드 시간을 증가시킵니다.
또한 패키지는 주기적으로 업데이트하여 보안 패치와 새 기능을 받아야 합니다.
What
NOTE패키지 제거:
Terminal window flutter pub remove 패키지이름# 예시flutter pub remove css_colors패키지 업데이트:
Terminal window # 모든 패키지를 허용 범위 내 최신 버전으로 업데이트flutter pub upgrade# 특정 패키지만 업데이트flutter pub upgrade 패키지이름현재 설치된 패키지 확인:
Terminal window # 의존성 트리 확인flutter pub deps# 업데이트 가능한 패키지 확인flutter pub outdated
How
TIP패키지 업데이트 워크플로우:
Terminal window # 1. 업데이트 가능한 패키지 확인flutter pub outdated# 출력 예시:# Package Current Upgradable Resolvable Latest# http 0.13.5 0.13.6 1.1.0 1.1.0# provider 6.0.5 6.0.5 6.1.1 6.1.1# 2. 안전한 업데이트 (버전 범위 내)flutter pub upgrade# 3. 메이저 버전 업데이트 (주의 필요)# pubspec.yaml에서 버전 직접 수정 후flutter pub getpubspec.lock 이해하기:
pubspec.lock은 정확한 패키지 버전을 기록합니다.- 팀원 간 동일한 버전을 사용하도록 보장합니다.
- Git에 커밋해야 합니다.
Watch out
WARNINGflutter upgrade vs flutter pub upgrade:
명령어 대상 설명 flutter upgradeFlutter SDK Flutter 자체를 업데이트 flutter pub upgrade패키지 프로젝트 패키지를 업데이트 메이저 버전 업데이트 주의:
# 0.x.x → 1.x.x 또는 1.x.x → 2.x.x 변경 시# Breaking changes가 있을 수 있음# 반드시 CHANGELOG 확인 필요
챕터 5: 버전 관리와 충돌 해결
Why
NOTE여러 패키지를 사용하다 보면 버전 충돌이 발생할 수 있습니다. 패키지 A와 패키지 B가 같은 패키지 C의 서로 다른 버전을 요구하는 경우입니다.
버전 범위를 잘 지정하면 이런 충돌을 줄일 수 있습니다.
What
NOTE버전 지정 방식:
dependencies:# 정확한 버전 (권장하지 않음)http: '1.1.0'# 캐럿 문법 (권장)http: ^1.1.0 # >=1.1.0 <2.0.0# 범위 지정http: '>=1.1.0 <2.0.0'# 최신 버전 (권장하지 않음)http: any캐럿 문법(^)2:
^1.1.0은>=1.1.0 <2.0.0과 같습니다.
- 마이너 버전과 패치 버전 업데이트 허용
- 메이저 버전 변경은 차단
- 대부분의 경우 이 방식을 사용합니다.
How
TIP버전 충돌 해결하기:
충돌 상황:
# some_package는 url_launcher ^5.0.0 필요# another_package는 url_launcher ^6.0.0 필요해결 방법 1: dependency_overrides 사용
dependencies:some_package: ^1.0.0another_package: ^2.0.0dependency_overrides:url_launcher: ^6.0.0 # 강제로 특정 버전 사용해결 방법 2: 패키지 버전 조정
Terminal window # 충돌 원인 확인flutter pub deps# 호환되는 패키지 버전 찾기Android Gradle 의존성 충돌:
android/build.gradle configurations.all {resolutionStrategy {force 'com.google.guava:guava:28.0-android'}}
Watch out
WARNINGdependency_overrides 주의사항:
- 오버라이드한 버전이 실제로 호환되는지 테스트 필요
- 런타임에 예상치 못한 에러 발생 가능
- 임시 해결책으로만 사용하고, 근본적인 해결책을 찾으세요
# 경고: dependency_overrides는 마지막 수단# 패키지 작성자에게 이슈 제보하는 것이 좋음dependency_overrides:problematic_package: ^2.0.0
챕터 6: 미출시 패키지 사용하기
Why
NOTE때로는 pub.dev에 아직 올라가지 않은 패키지를 사용해야 합니다.
- 직접 만든 비공개 패키지
- 수정이 필요한 오픈소스 패키지의 포크
- 아직 출시되지 않은 새 버전
What
NOTE미출시 패키지 의존성 유형:
유형 사용 시점 경로 의존성 로컬에 있는 패키지 Git 의존성 GitHub 등 저장소의 패키지 SSH Git 의존성 비공개 저장소의 패키지
How
TIP경로 의존성 (로컬 패키지):
dependencies:my_local_package:path: ../my_local_package/Git 의존성:
dependencies:# 저장소 루트에 있는 패키지my_package:git:url: https://github.com/user/my_package.git# 특정 브랜치my_package:git:url: https://github.com/user/my_package.gitref: develop# 특정 커밋my_package:git:url: https://github.com/user/my_package.gitref: a1b2c3d4# 하위 폴더에 있는 패키지my_package:git:url: https://github.com/flutter/packages.gitpath: packages/my_packageSSH Git 의존성 (비공개 저장소):
dependencies:private_package:git:
Watch out
WARNINGGit 의존성 주의사항:
- 브랜치(
ref: main)보다 태그나 커밋 해시를 사용하세요.- 브랜치는 내용이 바뀔 수 있어 빌드 재현성이 떨어집니다.
# 권장하지 않음ref: main # 내용이 바뀔 수 있음# 권장ref: v1.2.3 # 태그ref: a1b2c3d4e5f6 # 커밋 해시SSH 설정:
- 비공개 저장소 사용 시 SSH 키 설정이 필요합니다.
- CI/CD 환경에서도 SSH 키를 구성해야 합니다.
한계
이 문서는 패키지 사용법의 기초를 다룹니다. 다음 주제는 별도로 학습해야 합니다.
- 패키지 개발: 직접 패키지를 만들고 pub.dev에 배포하기
- 모노레포 관리: melos 등을 사용한 여러 패키지 관리
- 의존성 주입: get_it, injectable 등 DI 패키지 활용
- 플러그인 개발: 네이티브 코드를 포함하는 플러그인 만들기
Footnotes
공유
이 글이 도움이 되었다면 다른 사람과 공유해주세요!