Profile Image of the Author
Moodturn
Welcome to MoodturnPost!

Dart 튜토리얼 17편: 패키지 사용과 의존성 관리(pubspec·dart pub get/add·환경 변수)

2026-01-04
study
dart study

요약#

핵심 요지#

  • 문제 정의: 라이브러리/도구를 재사용하려면 패키지를 써야 하는데, pubspec 작성/설치/버전 범위/캐시 위치 같은 기본 규칙을 모르면 의존성 문제로 쉽게 막힌다.
  • 핵심 주장: pub는 pubspec.yaml1에 의존성을 선언하고, dart pub get2/dart pub add3로 가져오며, 필요하면 환경 변수로 캐시/레포 주소를 조정하는 흐름으로 사용한다.
  • 주요 근거: 최소 pubspec 예시, dart pub add 출력 예시, dart pub get가 package_config.json4을 생성하는 설명, PUB_CACHE5/PUB_HOSTED_URL6의 역할이 제시된다.
  • 실무 기준: “(1) pubspec 선언 → (2) dart pub get → (3) package: import”를 기본 템플릿으로 두고, 조직 환경에서는 PUB_CACHE/PUB_HOSTED_URL로 동작을 통제한다.

문서가 설명하는 범위#

  • pubspec.yaml로 의존성과 메타데이터를 선언하는 방법
  • dart pub get/dart pub add로 의존성을 설치/갱신하는 방법
  • PUB_CACHE/PUB_HOSTED_URL로 pub의 캐시/호스팅 레포를 조정하는 방법

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

참고 자료#

문제 상황#

패키지 생태계가 커질수록 “내 코드”는 더 짧아지지만, 대신 “의존성 관리”가 중요해집니다.
의존성이 잘못 잡히면 빌드가 깨지거나, 환경마다 다른 버전이 설치되거나, 캐시 위치 때문에 회사 환경에서 설치가 실패할 수 있습니다.
그래서 pub의 기본 흐름을 “고정된 절차”로 만들어두는 것이 필요합니다.

해결 방법#

단계 1: pubspec.yaml로 의존성을 선언하고 dart pub get으로 설치하기#

Why#

NOTE

pub는 “프로젝트가 무엇을 필요로 하는지”를 pubspec.yaml에서 읽습니다.
그래서 의존성 관리는 코드가 아니라 pubspec에서 시작합니다.

What#

NOTE

가장 단순한 pubspec는 이름만 포함할 수 있고, 의존성은 dependencies: 아래에 선언합니다.

How#

TIP

최소 pubspec 예시는 다음과 같습니다.

name: my_app

의존성을 선언하는 예시는 다음과 같이 제시됩니다.

name: my_app


dependencies:
  intl: ^0.20.2
  path: ^1.9.1

의존성을 설치(가져오기)할 때는 프로젝트 루트에서 dart pub get을 실행합니다.

Terminal window
$ cd <path-to-my_app>
$ dart pub get

Watch out#

WARNING

dart pub get은 의존성을 해결한 뒤 .dart_tool/ 아래에 package_config.json을 생성합니다.
즉, 패키지 import는 이 설정 파일을 기반으로 동작합니다.

결론: 의존성 관리는 pubspec.yaml로 선언하고 dart pub get으로 “설치”를 완료합니다.

단계 2: dart pub add로 pubspec 수정까지 자동화하기#

Why#

NOTE

의존성을 직접 편집하면 오타/들여쓰기 실수가 생길 수 있습니다.
그래서 pubspec 편집까지 커맨드로 처리하는 흐름이 제시됩니다.

What#

NOTE

dart pub add는 pubspec을 업데이트하면서 의존성 설치까지 진행합니다.

How#

TIP

다음 예시는 vector_math를 추가하는 흐름입니다.

Terminal window
$ dart pub add vector_math
Resolving dependencies...
+ vector_math 2.1.3
Downloading vector_math 2.1.3...
Changed 1 dependency!

Watch out#

WARNING

의존성은 “직접 사용하는 것(직접 의존성)”만 선언하고, 그 아래 단계(전이 의존성)는 pub가 처리하는 것으로 설명됩니다.
즉, 전이 의존성까지 직접 나열하려고 하지 않는 편이 흐름이 단순합니다.

결론: dart pub add로 “추가 + 설치”를 한 번에 처리해 pubspec 실수를 줄입니다.

단계 3: 패키지 라이브러리는 package: import로 가져오기#

Why#

NOTE

패키지를 설치했어도 import를 잘못하면 “어디에 있는 파일을 가져오는지”가 흔들릴 수 있습니다.
그래서 패키지 라이브러리는 package: 접두사를 사용하는 규칙이 제시됩니다.

What#

NOTE

package: import는 package_config.json에서 패키지 이름을 찾아 실제 경로로 매핑합니다.

How#

TIP

다음은 package: import 예시입니다.

import 'package:js/js.dart' as js;
import 'package:intl/intl.dart';

Watch out#

WARNING

의존성 선언이 없는데 package: import를 하면, 당연히 매핑이 없어서 실패합니다.
즉, import 문제는 먼저 pubspec/dart pub get 흐름을 확인해야 합니다.

결론: 패키지 라이브러리는 package: import로 가져오고, 매핑은 package_config.json이 담당합니다.

단계 4: 환경 변수로 pub의 캐시/레포 동작을 조정하기#

Why#

NOTE

개발 환경이나 조직 환경에서는 “캐시 위치”나 “패키지 레포 주소”를 고정해야 하는 경우가 있습니다.
이때 환경 변수로 pub 동작을 조정할 수 있습니다.

What#

NOTE

PUB_CACHE는 pub 캐시 디렉터리 위치를 지정합니다.
PUB_HOSTED_URL은 pub가 의존성을 내려받는 호스팅 레포 주소를 지정합니다.

How#

TIP

PUB_HOSTED_URL 설정 예시는 다음과 같이 제시됩니다.

Terminal window
PUB_HOSTED_URL = https://pub.example.com

Watch out#

WARNING

캐시/레포 설정은 “모든 의존성 설치 동작”에 영향을 줍니다.
따라서 조직에서 미러 서버를 쓰는 경우, 이 값이 올바른지 먼저 확인해야 합니다.

결론: pub 환경 변수는 설치 동작 전체에 영향을 주므로, 조직 환경에서는 먼저 값부터 고정합니다.

Footnotes#

  1. pubspec.yaml(pubspec): 패키지 메타데이터와 의존성을 선언하는 파일이다. ↩

  2. dart pub get(pub get): pubspec을 바탕으로 의존성을 해결하고 내려받는 명령이다. ↩

  3. dart pub add(pub add): pubspec에 의존성을 추가하고 설치까지 수행하는 명령이다. ↩

  4. package_config.json(package config): package: import 매핑 정보를 담는 설정 파일이다. ↩

  5. PUB_CACHE(PUB_CACHE): pub 캐시 디렉터리 위치를 지정하는 환경 변수다. ↩

  6. PUB_HOSTED_URL(PUB_HOSTED_URL): 의존성을 내려받는 호스팅 레포 주소를 지정하는 환경 변수다. ↩

공유

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

Dart 튜토리얼 17편: 패키지 사용과 의존성 관리(pubspec·dart pub get/add·환경 변수)
https://moodturnpost.net/posts/dart/dart-pub-dependency-management/
작성자
Moodturn
게시일
2026-01-04
Moodturn
Dart 튜토리얼 18편: 패키지 제작과 구조(dart create·lib/src·package layout·패키지 페이지)
Dart 튜토리얼 16편: Effective Dart 요약(Style·Documentation·Usage·Design)
© 2026 Moodturn. All Rights Reserved.
Powered by Astro

목차