pubspec.yaml — その概要、構造、Flutterにおける依存関係の設定

pubspec.yamlとは

pubspec.yamlはYAML形式のマニフェストファイルで、pubパッケージマネージャーがDartおよびFlutterプロジェクトを管理するために使用します。プロジェクトルートに配置され、flutter pub getコマンドのたびに処理されます。設定が複数のファイルに分散している他のプラットフォームとは異なり、Flutterはすべてのニーズに対して単一の集中型マニフェストを使用します。

ファイルにはメタデータ（プロジェクト名、説明、バージョン、作成者）が含まれています。このデータはpub.devにパッケージを公開するときや、App StoreやGoogle Play用にアプリケーションをビルドするときに使用されます。descriptionフィールドはパッケージ検索結果に表示されるため、情報が豊富で、他の開発者がライブラリを見つけられるキーワードを含める必要があります。

正しいpubspec.yamlがなければ、Flutterプロジェクトはビルドできません。構文エラーや誤ったインデントは、Error on line Xというメッセージとともに即座にコンパイル失敗を引き起こします。YAMLは空白に敏感です。余分なスペース1つでデータ構造が変わり、タブは構文エラーを引き起こします。そのため、pubspec.yamlを手動で編集する場合は、VS Codeの公式Flutter拡張機能など、YAML構文のハイライト表示に対応したエディターを使用することが重要です。

pubspec.yamlの主要セクション

pubspec.yamlは必須セクションとオプションセクションで構成されています。各セクションはプロジェクト設定の特定の側面を担当します。セクションの順序は重要ではありませんが、コミュニティの慣習に従い、メタデータ、環境、依存関係、リソース、プラットフォームの階層に従います。

nameとdescription

nameフィールドは、小文字のラテン文字、数字、アンダースコアのみで構成されるsnake_case形式の一意のパッケージ識別子を設定します。descriptionフィールドは最大180文字のプロジェクト概要であり、pub.devでの公開に必須です。説明は名前を繰り返さずにパッケージの目的を説明し、リポジトリの検索最適化のためのキーワードを含める必要があります。

name: my_flutter_app
description: Flutter製のタスク管理アプリ
publish_to: 'none'

versionとenvironment

versionフィールドは、プラス記号（1.0.0+1）の後にオプションのビルド番号を付けたセマンティックバージョニングmajor.minor.patchを使用します。environmentセクションは、互換性を確保するためにDartおよびFlutter SDKの最小バージョンと最大バージョンを設定します。新しいSDKバージョンにプロジェクトコードと互換性のない破壊的変更が含まれている場合、ビルドは明確なエラーメッセージとともに中断されます。

version: 1.0.0+1
environment:
  sdk: '>=3.2.0 <4.0.0'
  flutter: '>=3.16.0'

dependenciesとdev_dependencies

dependenciesセクションは、アプリケーションの実行時に必要なパッケージをリストします。dev_dependenciesセクションには、テスト、コード生成、開発用のパッケージが含まれ、リリースビルドには含まれません。依存関係を分離することはパフォーマンスにとって重要です。dependencies内の各パッケージは最終的なAPKまたはIPAのサイズを増加させ、追加のライブラリの初期化によるアプリケーションの起動時間も増加させます。

dependencies:
  flutter:
    sdk: flutter
  http: ^1.2.0
  provider: ^6.1.0
  shared_preferences: ^2.2.0
  cached_network_image: ^3.3.0

dev_dependencies:
  flutter_test:
    sdk: flutter
  mockito: ^5.4.0
  build_runner: ^2.4.0

アセットとフォントの設定

flutterセクションには、リソース、フォント、プラットフォームパラメータを設定するためのサブセクションが含まれています。リソースは、特定のファイルまたはディレクトリ全体を指定するpaths配列を介して接続されます。すべてのパスは、pubspec.yamlからの相対パスではなく、プロジェクトルートからの相対パスで指定されます。これは、Flutter初心者の開発者をしばしば混乱させる重要なニュアンスです。

flutter:
  uses-material-design: true
  assets:
    - assets/images/
    - assets/icons/
    - assets/config.json
    - assets/data/translations/
  fonts:
    - family: RobotoMono
      fonts:
        - asset: fonts/RobotoMono-Regular.ttf
        - asset: fonts/RobotoMono-Bold.ttf
          weight: 700
        - asset: fonts/RobotoMono-Italic.ttf
          style: italic

pubspec.yamlを介してアセットを接続すると、実行時にAssetBundleを介してファイルにアクセスできるようになります。これは画像、JSON、テキストファイル、その他のリソースで機能します。Flutterは異なる画面解像度を自動的にサポートします。images/2x/とimages/3x/を追加すると、Flutterはデバイスピクセル比に基づいて適切な画像バージョンを選択します。これを行うには、assetsにルートのimages/フォルダのみを指定するだけで十分です。

カスタムフォントは、family名とスタイルのリストを指定してfontsセクションから追加します。pubspec.yamlを変更した後、変更を適用するにはflutter pub getを実行する必要があります。フォントはMaterialAppテーマでグローバルに使用することも、特定のウィジェットでローカルに使用することもできます。各スタイルに対してweight（100〜900）とstyle（normal、italic）を指定でき、コード内でFontWeightとFontStyleを使用する際にFlutterが正しいフォントファイルを選択できるようになります。

依存関係とバージョンの管理

pubは依存関係のソースを指定するいくつかの方法をサポートしています：pub.dev、Gitリポジトリ、ローカルパス、プライベートリポジトリ。ソースの選択は開発段階によって異なります。安定版にはpub.dev、フォークやカスタム修正にはGit、並行して開発されているライブラリにはローカルパスを使用します。

^version演算子は互換性のあるバージョンを示します。^1.2.0は>=1.2.0かつ<2.0.0のバージョンを許可します。これはCocoaPodsの~>演算子やnpmのCaret演算子に類似しています。pubはSATソルバーアルゴリズムを使用して依存関係地獄を自動的に解決し、すべての制約を満たすバージョンの組み合わせを見つけます。そのような組み合わせが存在しない場合、pubは競合するパッケージを示す詳細なメッセージを出力します。

pubspec.lockファイルは依存関係の正確なバージョンを固定します。アプリケーションの場合は、チームのすべてのマシンで再現可能なビルドを確保するためにバージョン管理に保存する必要があります。ライブラリの場合は、ライブラリのユーザーが異なる依存関係バージョンで使用できるように、pubspec.lockはリポジトリに含めません。flutter pub upgradeコマンドはpubspec.yamlの制約に従ってすべての依存関係を更新し、flutter pub outdatedは更新可能なパッケージを表示します。

ビルドと公開の設定

pub.devにアプリケーションを公開するには、publish_toセクションで設定を指定します。値'none'はパッケージの誤った公開を防ぎます。これは内部プロジェクトや非公開プロジェクトにとって重要です。publish_toが欠落している場合、pubはデフォルトのpub.devにパッケージを公開しようとし、望ましくないコード漏洩につながる可能性があります。

flutterセクションには、プラットフォームパラメータが含まれます：プラットフォームファイルの自動生成用のgenerate、モジュール式機能ロード用のdeferred-components。generate: trueパラメータは、flutter create --platformsで新しいプラットフォームを追加する際に、Flutterがプラットフォームプロジェクト（iOS、Android、Web）を自動的に作成および更新するように強制します。このパラメータがないと、プラットフォームフォルダ構造がpubspec.yamlと同期しなくなる可能性があります。

flutter:
  generate: true
  deferred-components:
    - name: photoEditor
      libraries:
        - package:photo_editor/library.dart

platformsセクションはパッケージのターゲットプラットフォームを設定します。アプリケーションの場合、flutter createで特定のプラットフォームのサポートを追加すると自動的に決定されます。プラットフォームはpubspec.yamlを編集して手動で追加および削除できます。Deferred Componentsを使用すると、アプリケーションの一部をオンデマンドでロードでき、インストールサイズを削減できます。これは特にゲームや使用頻度の低いコンテンツが多いアプリケーションに関連します。

パッケージを公開する際、pubはすべてのpubspec.yamlフィールドがリポジトリの要件に準拠しているかチェックします。必須フィールドのname、version、descriptionがないと公開は拒否されます。さらに、ライセンスの正確性、README.mdとCHANGELOG.mdの存在がチェックされます。コードアナライザーのエラー（dart analyze）があるパッケージも検証に失敗します。公開が成功すると、パッケージは数分以内にpub.devで利用可能になります。

dependency_overridesセクションを使用すると、推移的依存関係からの制約を無視して、特定のパッケージバージョンを強制できます。これは強力だが危険なメカニズムです。誤って使用すると、ライブラリの非互換性を引き起こす可能性があります。dependency_overridesは、競合の解決や新しいバージョンのテストのために一時的にのみ使用してください。主要な依存関係を修正した後は、長期的にプロジェクトの依存関係グラフを壊さないようにオーバーライドを削除する必要があります。

pubspec.yamlのexecutablesセクションを使用すると、パッケージをアクティブ化する際にpubがPATHにインストールする実行可能スクリプトを指定できます。これは、build_runnerやdart_code_metricsなど、Dartで書かれたCLIツールに便利です。dart pub global activateコマンドはパッケージをグローバルにインストールし、executablesで指定されたスクリプトをターミナルからアクセス可能にします。アプリケーションの場合、エントリポイントはlib/main.dartのmainで定義されるため、executablesは通常使用されません。