Flutter pub add와 버전 제약: 패키지를 추가할 때 의존성 충돌을 줄이는 법

Flutter 프로젝트에 라이브러리를 넣을 때 pubspec.yaml을 직접 고치고 들여쓰기를 틀리는 일은 생각보다 흔하다. flutter pub add는 패키지와 버전 제약을 의존성 목록에 넣고 해석 과정을 실행하는 출발점이 된다.

pub add는 의존성과 잠금 파일을 함께 갱신한다

도식처럼 pubspec.yaml은 허용 범위를 기록하고, 잠금 파일은 실제로 선택된 버전을 고정한다. 패키지를 하나 추가한 뒤 두 파일의 변화를 나눠 확인해 보자.

flutter pub add http

명령 뒤에는 pubspec.yaml의 dependencies와 실제로 선택된 정확한 버전을 담는 잠금 파일을 확인한다. 애플리케이션은 재현 가능한 설치를 위해 잠금 파일을 팀과 공유하는 것이 일반적이다. 패키지 이름만 보고 필요한 기능·유지 상태·플랫폼 지원을 단정하지 말고 공식 설명과 프로젝트 제약을 확인하자.

caret 제약은 무제한 업데이트가 아니다

dependencies:
  http: ^1.2.0

위 1.2.0은 범위를 읽기 위한 예시이지 설치를 권하는 최신 버전이 아니다. ^1.2.0은 1.2.0 이상, 2.0.0 미만을 허용한다. 0.x 버전은 상한이 달라지므로 같은 방식으로 1.x 범위를 추측하면 안 된다. '최신 버전이면 좋다'는 이유만으로 넓은 범위를 쓰면 다음 설치에서 동작이 달라질 수 있다.

업데이트는 빌드와 테스트로 확인한다

의존성을 추가하거나 올린 뒤에는 최소한 분석·테스트·대상 플랫폼 빌드를 확인한다. 특히 네이티브 플러그인은 Android와 iOS 설정을 함께 바꿀 수 있다. 충돌이 났을 때는 pubspec.lock을 임의로 지우기 전에 어떤 패키지가 상충하는 버전을 요구하는지 확인하자.

flutter pub get
flutter analyze
flutter test

첫 명령에서 해결이 실패하면 pubspec.yaml의 직접 의존성과 오류에 나온 전이 의존성을 함께 확인한다. 분석은 통과했는데 특정 플랫폼 빌드만 실패한다면 패키지의 지원 플랫폼과 네이티브 설정을 따로 확인한다. 테스트 통과만으로 실제 Android·iOS 빌드까지 검증됐다고 말할 수는 없다.

충돌 메시지에서 직접·전이 의존성을 구분한다

패키지 추가가 실패하면 오류에 나온 두 버전만 보고 잠금 파일부터 지우지 않는다. 프로젝트가 직접 선언한 패키지인지, 다른 패키지가 끌고 온 전이 의존성인지 그래프에서 확인한다.

flutter pub deps
flutter pub outdated
flutter analyze
flutter test

pub deps는 선택된 의존성 관계를, pub outdated는 현재 제약 안에서 가능한 버전과 더 새로운 버전을 구분하는 데 도움을 준다. 제약을 넓히기 전에는 바뀌는 직접 의존성과 전이 의존성을 함께 보고, 분석·테스트 뒤 대상 플랫폼 빌드까지 확인한다.

로컬에서만 되고 다른 환경에서 실패한다면 pubspec.yaml, pubspec.lock, Flutter·Dart SDK 버전을 나란히 비교한다. 잠금 파일을 지웠더니 우연히 해결됐다는 결과보다 어떤 제약이 충돌했고 어떤 버전 조합으로 해결됐는지 남겨야 다음 설치도 재현할 수 있다.

핵심 요약

flutter pub add는 의존성 선언과 해석을 시작하는 안전한 방법이다. caret 제약의 허용 범위를 이해하고, 잠금 파일·분석·테스트로 실제 선택 결과를 확인하자. 의존성 추가는 코드 한 줄보다 넓은 변경일 수 있으므로 플랫폼과 라이선스도 함께 검토해야 한다.