Flutter 튜토리얼 66편: 패키지 사용하기

요약#

핵심 요지#

  • 문제 정의: 모든 기능을 처음부터 직접 만들면 시간이 오래 걸리고 버그가 생기기 쉽다.
  • 핵심 주장: 커뮤니티가 만든 패키지를 활용하면 개발 속도를 높이고 검증된 코드를 사용할 수 있다.
  • 주요 근거: pub.dev에는 수만 개의 패키지가 있으며, Flutter Favorites로 품질이 검증된 패키지를 쉽게 찾을 수 있다.
  • 실무 기준: flutter pub add로 패키지를 추가하고, 버전 범위를 지정하여 호환성을 유지한다.
  • 한계: 패키지 품질이 천차만별이므로, 선택 시 점수, 유지보수 상태, 라이선스를 반드시 확인해야 한다.

문서가 설명하는 범위#

  • 패키지와 플러그인의 차이점
  • pub.dev에서 패키지 검색하기
  • 프로젝트에 패키지 추가하고 제거하기
  • 버전 충돌 해결하기
  • Flutter Favorites 프로그램 이해하기

읽는 시간: 12분 | 난이도: 초급


참고 자료#


문제 상황#

앱을 만들다 보면 다양한 기능이 필요합니다. HTTP 요청, 로컬 저장소, 상태 관리, UI 컴포넌트 등 모든 것을 직접 만들려면 시간이 오래 걸립니다.

// 모든 기능을 직접 구현하면?
// - HTTP 클라이언트 구현: 1주일
// - JSON 파싱 유틸리티: 3일
// - 로컬 저장소 래퍼: 2일
// - 날짜 선택기 UI: 1주일
// 총 개발 시간: 3주 이상

문제는 다음과 같습니다.

  • 검증된 코드를 처음부터 다시 만드는 것은 비효율적이다.
  • 직접 만든 코드는 버그가 있을 가능성이 높다.
  • 유지보수와 업데이트를 모두 혼자 감당해야 한다.

해결 방법#

Flutter 생태계에는 수만 개의 패키지가 있습니다. 다른 개발자들이 만들고 검증한 코드를 활용하면 빠르고 안정적으로 앱을 만들 수 있습니다.

챕터 1: 패키지와 플러그인 이해하기#

Why#

NOTE

Flutter에서 “패키지”와 “플러그인”이라는 용어가 자주 등장합니다. 두 용어의 차이를 이해하면 필요한 라이브러리를 정확히 찾을 수 있습니다.

플러그인은 패키지의 한 종류입니다. 정식 명칭은 “플러그인 패키지”이지만, 보통 “플러그인”으로 줄여서 부릅니다.

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에서 확인:

  1. 패키지 페이지의 “Platforms” 섹션 확인
  2. Android, iOS 등 플랫폼별 아이콘이 있으면 플러그인
  3. “Dart” 아이콘만 있으면 순수 Dart 패키지

pubspec.yaml에서 확인:

# 순수 Dart 패키지
flutter:
plugin:
platforms: {} # 비어있거나 이 섹션이 없음
# 플러그인 패키지
flutter:
plugin:
platforms:
android:
package: com.example.plugin
ios:
pluginClass: MyPlugin

Watch out#

WARNING

플러그인 사용 시 주의사항:

  • 플러그인을 추가한 후에는 앱을 완전히 재시작해야 합니다.
  • 핫 리로드나 핫 리스타트로는 네이티브 코드가 적용되지 않습니다.
  • 플러그인이 지원하지 않는 플랫폼에서 사용하면 MissingPluginException이 발생합니다.
// 플랫폼 지원 여부 확인
import 'dart:io' show Platform;
if (Platform.isAndroid || Platform.isIOS) {
// 모바일 전용 플러그인 사용
} else {
// 웹이나 데스크톱에서는 대체 로직
}

챕터 2: pub.dev에서 패키지 찾기#

Why#

NOTE

pub.dev는 Dart와 Flutter 패키지의 공식 저장소입니다. 수만 개의 패키지 중에서 좋은 패키지를 찾는 방법을 알아야 합니다.

잘못된 패키지를 선택하면 다음과 같은 문제가 생깁니다.

  • 유지보수가 중단된 패키지: 보안 취약점 방치
  • 품질이 낮은 패키지: 버그와 성능 문제
  • 라이선스 문제: 상용 앱에서 사용 불가

What#

NOTE

pub.dev에서 패키지 품질을 판단하는 기준입니다.

점수 시스템:

  • Likes: 개발자들이 누른 좋아요 수
  • Pub Points: 문서화, 플랫폼 지원, 코드 품질 등을 평가한 점수 (최대 160점)
  • Popularity: 얼마나 많은 프로젝트에서 사용하는지

Flutter Favorites1:

Flutter 팀과 커뮤니티 위원회가 선정한 고품질 패키지입니다.

  • 높은 전반적 점수
  • 허용적인 라이선스 (Apache, MIT, BSD 등)
  • 완성도 높은 기능
  • 검증된 퍼블리셔
  • 좋은 문서화와 예제 코드

How#

TIP

패키지 검색 방법:

  1. pub.dev 접속
  2. 검색창에 키워드 입력 (예: “http”, “state management”)
  3. 플랫폼별 필터 적용 (Android, iOS, Web 등)

Flutter Favorites 찾기:

https://pub.dev/flutter/favorites

플랫폼별 필터링:

플랫폼검색 쿼리
Androidsdk:flutter platform:android
iOSsdk:flutter platform:ios
Websdk:flutter platform:web
모든 플랫폼필터 조합 가능

패키지 선택 체크리스트:

□ Pub Points 120점 이상
□ 최근 6개월 내 업데이트
□ Null Safety 지원
□ 검증된 퍼블리셔 (verified publisher)
□ 필요한 플랫폼 지원
□ 라이선스 확인 (MIT, BSD, Apache 권장)
□ GitHub 이슈 응답률 확인

Watch out#

WARNING

패키지 선택 시 주의사항:

  • 다운로드 수만 보지 마세요: 오래된 패키지는 다운로드 수가 많아도 유지보수가 안 될 수 있습니다.
  • 마지막 업데이트 확인: 1년 이상 업데이트가 없으면 주의하세요.
  • 이슈 트래커 확인: 미해결 이슈가 너무 많으면 문제가 있을 수 있습니다.
  • 라이선스 주의: GPL 라이선스는 상용 앱에서 문제가 될 수 있습니다.

챕터 3: 패키지 추가하기#

Why#

NOTE

패키지를 찾았으면 프로젝트에 추가해야 합니다. Flutter는 두 가지 방법을 제공합니다.

  1. 명령어로 추가 (flutter pub add)
  2. pubspec.yaml 직접 수정

명령어를 사용하면 최신 버전이 자동으로 설정되어 편리합니다.

What#

NOTE

flutter pub add 명령어:

Terminal window
# 패키지 추가
flutter pub add 패키지이름
# 예시
flutter pub add http
flutter pub add provider
flutter pub add go_router

이 명령어는 다음을 자동으로 수행합니다.

  1. pubspec.yaml에 의존성 추가
  2. flutter pub get 실행하여 패키지 다운로드
  3. pubspec.lock 파일 업데이트

How#

TIP

방법 1: 명령어 사용 (권장)

Terminal window
# 터미널에서 프로젝트 폴더로 이동
cd my_flutter_app
# 패키지 추가
flutter pub add css_colors

방법 2: pubspec.yaml 직접 수정

pubspec.yaml
dependencies:
flutter:
sdk: flutter
css_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});
@override
Widget build(BuildContext context) {
return MaterialApp(
home: Scaffold(
body: Container(color: CSSColors.coral),
),
);
}
}

Watch out#

WARNING

플러그인 추가 후 반드시 앱 재시작:

Terminal window
# 핫 리로드/리스타트로는 네이티브 코드 적용 안 됨
# 앱을 완전히 종료하고 다시 실행해야 함
flutter run

MissingPluginException 해결:

MissingPluginException(No implementation found for method X on channel Y)

이 에러가 나타나면:

  1. 앱을 완전히 종료
  2. flutter clean 실행
  3. flutter pub get 실행
  4. 앱 다시 빌드 및 실행

챕터 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 get

pubspec.lock 이해하기:

  • pubspec.lock은 정확한 패키지 버전을 기록합니다.
  • 팀원 간 동일한 버전을 사용하도록 보장합니다.
  • Git에 커밋해야 합니다.

Watch out#

WARNING

flutter upgrade vs flutter pub upgrade:

명령어대상설명
flutter upgradeFlutter SDKFlutter 자체를 업데이트
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.0
another_package: ^2.0.0
dependency_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#

WARNING

dependency_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.git
ref: develop
# 특정 커밋
my_package:
git:
url: https://github.com/user/my_package.git
ref: a1b2c3d4
# 하위 폴더에 있는 패키지
my_package:
git:
url: https://github.com/flutter/packages.git
path: packages/my_package

SSH Git 의존성 (비공개 저장소):

dependencies:
private_package:
git:
url: [email protected]:company/private_package.git

Watch out#

WARNING

Git 의존성 주의사항:

  • 브랜치(ref: main)보다 태그나 커밋 해시를 사용하세요.
  • 브랜치는 내용이 바뀔 수 있어 빌드 재현성이 떨어집니다.
# 권장하지 않음
ref: main # 내용이 바뀔 수 있음
# 권장
ref: v1.2.3 # 태그
ref: a1b2c3d4e5f6 # 커밋 해시

SSH 설정:

  • 비공개 저장소 사용 시 SSH 키 설정이 필요합니다.
  • CI/CD 환경에서도 SSH 키를 구성해야 합니다.

한계#

이 문서는 패키지 사용법의 기초를 다룹니다. 다음 주제는 별도로 학습해야 합니다.

  • 패키지 개발: 직접 패키지를 만들고 pub.dev에 배포하기
  • 모노레포 관리: melos 등을 사용한 여러 패키지 관리
  • 의존성 주입: get_it, injectable 등 DI 패키지 활용
  • 플러그인 개발: 네이티브 코드를 포함하는 플러그인 만들기

Footnotes#

  1. Flutter Favorites(플러터 페이버릿): Flutter 생태계 위원회가 선정한 고품질 패키지 목록으로, 앱 개발 시 우선적으로 고려할 만한 패키지들이다.

  2. 캐럿 문법(Caret Syntax): ^1.2.3처럼 버전 앞에 캐럿(^)을 붙이는 방식으로, 해당 버전부터 다음 메이저 버전 직전까지의 범위를 의미한다.

공유

이 글이 도움이 되었다면 다른 사람과 공유해주세요!

Flutter 튜토리얼 66편: 패키지 사용하기
https://moodturnpost.net/posts/flutter/flutter-packages-using/
작성자
Moodturn
게시일
2026-01-08
Moodturn

목차