pub: 主要概念、Dartパッケージマネージャーとpubspec.yaml

pubとは？

pub (Package Universal Browser) — Dart SDKに付属する組み込みパッケージマネージャーです。外部ライブラリの管理、バージョン競合の解決、推移的依存関係のダウンロード、パッケージのローカルキャッシュを行います。Flutterエコシステムでは、pubはナビゲーションプラグイン、HTTPクライアント、ステートマネージャー、その他のコンポーネントを接続するための主要ツールとして使用されます。

pubの主な機能は次のとおりです：pub.devレジストリからの依存関係のインストール、ローカルパス（パス依存関係）、gitリポジトリ；セマンティックバージョニングルールに従ったバージョン解決；システムディレクトリへのダウンロード済みパッケージのキャッシュ；公開レジストリへの独自パッケージの公開。これらすべての操作はCLIコマンドdart pubまたは同等のflutter pubを介して利用できます。

pubのアーキテクチャは閉じた依存関係グラフに基づいています：マネージャーは各パッケージが1回だけ表示されるツリーを構築します。2つのライブラリが同じパッケージの異なるバージョンを必要とする場合、pubは互換性のある範囲を見つけようとするか、競合エラーを報告します。これは、同じパッケージの複数のバージョンを異なるツリーノードで許可するnpmのアプローチとは異なります。

pubspec.yamlの構造

pubspec.yamlファイル — DartまたはFlutterプロジェクトの中心的な設定ファイルです。YAML形式で記述され、メタデータ、依存関係、ビルド設定、SDK制約が含まれます。以下はFlutterアプリケーションの典型的な例です：

name: my_app
description: Flutterアプリの例
version: 1.0.0+1
publish_to: none

environment:
  sdk: ">=3.0.0 <4.0.0"
  flutter: ">=3.10.0"

dependencies:
  flutter:
    sdk: flutter
  http: ^1.1.0
  provider: ^6.0.5
  shared_preferences: ^2.2.0
  path_provider: ^2.1.0

dev_dependencies:
  flutter_test:
    sdk: flutter
  flutter_lints: ^3.0.0
  mockito: ^5.4.3

flutter:
  uses-material-design: true
  assets:
    - assets/images/
    - assets/fonts/

pubspec.yamlの主要フィールド：name — 一意のパッケージ名（ラテン文字、アンダースコア、数字のみ）；description — 簡単な説明（公開に必須）；version — プラス記号の後にオプションのビルド番号が付くセマンティックバージョン；environment — 最小Dart SDKおよびFlutter SDKバージョン；dependencies — メインアプリケーションの依存関係；dev_dependencies — 開発とテストのみの依存関係；flutter — Flutter設定セクション（アセット、フォント、プラグイン）。

publish_toフィールドは公開の可否を制御します：値noneは公開を禁止し（アプリケーションに典型的）、デフォルト値はhttps://pub.devです。dependency_overridesフィールドは競合状況でパッケージバージョンを強制的に上書きできます — 注意して使用し、一時的な解決策としてのみ使用してください。

依存関係とその種類

pubは4種類の依存関係をサポートしており、それぞれpubspec.yaml内で独自の構文で指定します：

ホステッド（hosted）

標準タイプ — パッケージはpub.devレジストリまたは他の互換性のあるレジストリからダウンロードされます。パッケージ名とバージョンを指定します。例：http: ^1.1.0はキャレットバージョニングルールに従って範囲>=1.1.0および<2.0.0から最新の互換バージョンをダウンロードします。

SDK依存関係

Flutter SDKまたはDart SDKを含めるために使用されます。構文：flutter: sdk: flutter。パッケージはレジストリではなくローカルのFlutter SDKインストールから取得されます。SDK依存関係はバージョン管理されません — そのバージョンは現在インストールされているFlutterのバージョンによって決まります。

パス（path）

パッケージを含むローカルディレクトリを指定します。公開せずにライブラリを開発およびテストする際に便利です。構文：

dependencies:
  my_local_lib:
    path: ../my_local_lib

パス依存関係はpubspec.lockに固定されません — 更新のたびに指定されたパスから再解決されます。

Git

パッケージをgitリポジトリから直接含めることができます。ブランチ、タグ、コミットがサポートされています：

dependencies:
  my_git_lib:
    git:
      url: https://github.com/user/my_git_lib.git
      ref: main

Git依存関係はフォーク、未公開の修正、Pull Requestでの作業に便利です。ビルド中に予期しない変更を避けるために、ブランチの代わりに特定のタグまたはコミットを指定することをお勧めします。

バージョン管理と範囲

pubはSemantic Versioning 2.0に厳密に従います：形式MAJOR.MINOR.PATCH（MAJOR — 互換性のない変更、MINOR — 後方互換性のある追加、PATCH — 後方互換性のある修正）。このスキームに基づいて、pubはパッケージの互換性を判断し、競合を解決します。

pubspec.yamlでバージョンを指定するには、3つの主要な演算子が使用されます：

• キャレット（^） — ^1.2.3は>=1.2.3かつ<2.0.0に相当します。最も一般的な演算子で、メジャーバージョン内での互換性を意味します。メジャーバージョンが0（ゼロ）のパッケージの場合 — ^0.1.2は>=0.1.2かつ<0.2.0を意味し、不安定なバージョンのSemVerルールに従います。
• チルダ（~） — ~1.2.3は>=1.2.3かつ<1.3.0に相当します。マイナーバージョンを固定し、パッチ更新のみを許可します。あまり使用されず、主にマイナーバージョンレベルで非互換性がわかっている場合に使用されます。
• 正確な範囲 — >=1.2.0 <2.0.0 — 完全な制御を提供する明示的な表記法です。複雑な制約（たとえば推移的依存関係の複数バージョンを使用する場合など）に便利です。

dart pub getを実行すると、pubは解決されたすべてのパッケージ（直接および推移的）の正確なバージョンを固定するpubspec.lockファイルを生成します。このファイルは、すべてのマシンで再現可能なビルドを保証するためにバージョン管理に含める必要があります。dart pub upgradeを実行すると、ロックファイルは指定された制約内で最新の互換バージョンに更新されます。

依存関係競合エラーは、2つのパッケージが同じ依存関係の重複しない範囲を必要とする場合に発生します。pubはどのパッケージが競合しているかとその理由を報告します。解決策：競合しているパッケージの1つを互換性のあるバージョンに更新する、dependency_overrides（一時的な措置）を使用する、または代替パッケージに切り替えます。

pubの主要コマンド

すべてのpub操作は統一されたCLIインターフェースを介して実行されます。Dart SDKはdart pubコマンドを使用し、Flutter SDKは同等のflutter pubを使用します（さらにFlutter SDKの依存関係とプラグインを考慮します）。主要なコマンドは以下のとおりです：

• dart pub get — pubspec.yamlで指定されたすべての依存関係をダウンロードし、バージョンを解決してpubspec.lockを作成/更新します。プロジェクトの初回クローン時または依存関係変更後に実行します。
• dart pub upgrade — pubspec.yamlの制約内ですべての依存関係を最新バージョンに更新し、pubspec.lockを上書きします。個別のパッケージを更新できます：dart pub upgrade http。
• dart pub add <package> — pubspec.yamlに新しい依存関係を追加し、すぐにpub getを実行します。例：dart pub add dioはdioパッケージの最新バージョンを追加します。
• dart pub remove <package> — pubspec.yamlから依存関係を削除し、グラフ解決を再実行します。
• dart pub cache repair — キャッシュされたすべてのパッケージを再読み込みします。ローカルキャッシュの破損やチェックサムエラーの場合に役立ちます。
• dart pub deps — 依存関係ツリーを便利なテキスト形式で表示します。推移的依存関係の分析や重複の検出に便利です。
• dart pub publish — 現在のパッケージをpub.devに公開します。公開前にpubspec.yaml、ライセンス、説明を検証します。
• dart pub outdated — 現在のバージョン、希望するバージョン、利用可能な最新バージョンを示す古い依存関係のリストを表示します。npm outdatedに類似しています。

すべてのコマンドは短縮形dart pub getとしてdart pub gでも利用できます（すべての短縮形があるわけではありません）。Flutterプロジェクトでは、コマンドの前にflutterが付加されます：flutter pub get、flutter pub addなど。Flutterバージョンはターゲットプラットフォームとのプラグイン互換性も追加でチェックします。

pub.devへの公開

pub.dev — DartおよびFlutterエコシステムの中央パッケージレジストリです。2025年1月時点で、50,000以上のパッケージが公開されており、総ダウンロード数は100億を超えています。各パッケージには、説明、ドキュメント、人気スコア、Pub Points評価、バージョンを含むページがあります。

Pub Points — 0から130ポイントまでの自動化されたパッケージ品質評価システムです。ライセンスの有無、説明、例、最新の安定版Dartとの互換性、脆弱性の有無、テストカバレッジ、フォーマットの正確性を考慮します。高いスコアは検索でのパッケージの可視性とユーザーの信頼を高めます。

公開プロセスにはいくつかのステップが含まれます：

1. pubspec.yamlを確認：name、description、version、licenseが存在することを確認します（SPDX識別子を推奨、例：MIT）。
2. dart pub publish --dry-runを実行 — サーバーに送信せずに公開をシミュレーションし、パッケージに含まれるすべてのファイルと可能性のあるエラーを表示します。
3. 初回公開時にGoogleアカウントで認証：dart pub publishはOAuth認証のためにブラウザを開きます。
4. ターミナルで公開を確認します。アップロードが成功すると、パッケージは数分以内にpub.devに表示されます。

重要なルール：一意の名前を持つパッケージのみ公開できます；一度公開されたバージョンは削除できません（7日以内であればdart pub unpublishで非表示にすることは可能）；大規模な更新の場合はSemantic Versioningのルールに従い、メジャーバージョンを変更せずに公開APIを壊さないでください。