Dart 튜토리얼 20편: Pub 문제 해결(트러블슈팅·커스텀 레포·커밋 금지 파일)

Why#

NOTE

pub publish 실행 시 403 오류는 “업로더가 아니다” 또는 “계정이 다르다” 같은 인증 흐름 문제로 발생할 수 있습니다.
이때는 pub 인증 과정을 리셋해야 합니다.

What#

NOTE

인증 리셋 방법으로 pub 자격 증명 파일(pub-credentials.json³)을 삭제하는 절차가 제시됩니다.

How#

TIP

macOS에서는 다음 경로의 파일을 삭제하는 예시가 제시됩니다.

1
$ rm $HOME/Library/Application Support/dart/pub-credentials.json

Watch out#

WARNING

이 작업은 “인증 정보를 삭제”하는 동작입니다.
즉, 이후 다시 인증 절차가 진행될 수 있으므로, 어떤 계정으로 로그인되는지 확인해야 합니다.

결론: publish 403은 코드 문제가 아니라 인증 상태 문제일 수 있으므로, pub 자격 증명을 재설정해 원인을 좁힙니다.

Why#

NOTE

방화벽/프록시 환경에서는 dart pub get이 실패할 수 있습니다.
이때는 네트워크 설정을 환경 변수로 전달해야 합니다.

What#

NOTE

명령줄에서 pub는 http_proxy/https_proxy 환경 변수를 인식하는 것으로 설명됩니다.

How#

TIP

Linux/macOS에서 https_proxy를 설정하는 예시는 다음과 같습니다.

1
$ export https_proxy=hostname:port

Watch out#

WARNING

프록시에 인증 정보가 필요하면 추가 설정이 필요할 수 있습니다.
즉, 단순 연결 실패라면 먼저 프록시 환경 변수부터 확인해야 합니다.

결론: 네트워크 제약이 있는 환경에서는 프록시 환경 변수부터 먼저 확인합니다.

Why#

NOTE

조직 내부 패키지를 배포/사용하려면, pub.dev가 아닌 사설 패키지 레포를 쓰는 경우가 있습니다.
이때는 레포 인증과 의존성 선언 방식이 달라집니다.

What#

NOTE

커스텀 패키지 레포는 hosted URL로 식별되며, pub는 토큰을 요청에 붙여 인증할 수 있다고 설명됩니다.
토큰은 직접 입력하거나, --env-var로 환경 변수에서 읽도록 설정할 수 있습니다.

How#

TIP

토큰을 직접 등록하는 예시는 다음과 같습니다.

1
$ dart pub token add https://dart-packages.example.com
2
Enter secret token: [enter secret token]
3
Requests to "https://dart-packages.example.com" will now be authenticated using the secret token.

CI 환경을 위해 환경 변수에서 토큰을 읽도록 설정하는 예시는 다음과 같습니다.

1
$ dart pub token add https://dart-packages.example.com --env-var MY_SECRET_TOKEN
2
Requests to "https://dart-packages.example.com" will now be authenticated using the secret token stored in the environment variable "MY_SECRET_TOKEN".

의존성은 pubspec.yaml에서 hosted로 레포를 지정하는 방식이 제시됩니다.

1
dependencies:
2
  example_package:
3
    hosted: https://dart-packages.example.com
4
    version: ^1.4.0

Watch out#

WARNING

토큰을 환경 변수로 읽도록 설정하면, pub가 실제 토큰 값을 설정 파일에 저장하지 않고 “환경 변수에서 읽어야 한다는 사실”만 저장하는 것으로 설명됩니다.
즉, 공유 CI 환경에서 비밀값이 섞이는 사고를 줄이려면 이 방식을 우선 고려해야 합니다.

결론: 사설 레포는 “token 인증 + hosted dependency” 흐름으로 연결하고, CI에서는 --env-var로 비밀값 노출 위험을 낮춥니다.

Why#

NOTE

도구가 만든 파일을 커밋하면 저장소가 불필요하게 커지고, 개인 환경 정보가 노출될 수 있으며, 유지보수가 어려워질 수 있습니다.
그래서 커밋 금지 목록을 초기에 고정하는 것이 유리합니다.

What#

NOTE

pub가 생성하는 파일/디렉터리 중 커밋하지 말아야 할 목록이 제시됩니다.
특히 pubspec.lock⁴은 패키지와 앱에서 권장 방식이 다르다는 예외 규칙이 제시됩니다.

How#

TIP

커밋 금지 목록 예시는 다음과 같습니다.

1
.dart_tool/
2
build/
3
pubspec.lock  # 애플리케이션 패키지는 예외

문서 생성 도구가 만드는 API 문서 디렉터리도 커밋하지 않는 목록으로 제시됩니다.

1
doc/api/

Watch out#

WARNING

pubspec.lock은 “패키지”에서는 커밋하지 말고, “애플리케이션”에서는 커밋을 권장하는 것으로 설명됩니다.
즉, 저장소 성격(패키지인지/앱인지)에 따라 규칙을 다르게 적용해야 합니다.

결론: 생성 파일 커밋 금지 규칙을 먼저 적용하면, 의존성/배포/협업 문제를 줄일 수 있습니다.