【Flutter開発】pubspec.yamlのフィールドまとめ

こんにちは、教育系エンジニアのひらまつ（＠hiramatsuu）です。

ひらまつの簡単な自己紹介

書籍「ゼロからわかる Linuxコマンド200本ノック（技術評論社）」の著者。Udemy受講者8万人。
プログラミング教育をメインに活動するエンジニアとして、動画教材の作成・技術書の執筆・学習アプリの開発などを行なっています（詳しくはこちら）。

本記事では、pubspec.yamlで使えるフィールドについて解説していきます。pubspec.yamlによらない、YAMLの基本的な書き方については「【速習】YAML1.2の概要と基本構文【練習問題付き】」を参照してください。

フィールドの分類

pubspec.yamlに必要なフィールドは、大きく次の4つに分類することができる。

すべてのパッケージに必須
別のパッケージを使用する際に必要
パッケージをpub.devで公開する際に必要
Flutterアプリには必要

本記事では「Flutterアプリ開発でパッケージを使う人」をメインの対象者として解説。

すべてのパッケージに必須のフィールド

name

パッケージの名前を記載するフィールド。すべてのパッケージで必須のフィールド。
パッケージの参照や公開のために使われる。
パッケージの名前はすべて、lowercase with underscores（アンダースコアで区切られた小文字）であるべき（just_like_this）¹。
使える文字は、正規表現で書くと[a-z0−9_]。つまり、アンダースコアの他には、基本のラテン文字とアラビア数字のみ使用可能。また、数字から始まる名前や、予約語を使うことはできない。
明確で、簡潔で、まだ使われていない名前を選ぶようにする。事前にpub.devで同一の名前がないかを調べることが推奨される。

environment

SDK constraintsを記載するフィールド。このフィールドが欠けていると、dart pub getの実行時にエラーが発生するため、基本的に必須のフィールド。
SDK constraintとは、すべてのパッケージが暗黙的に依存している、Dart SDK自体への依存についてのバージョン制約（version constraint）のこと。
Dartも継続的にアップグレードされるので、SDK constraintをpubspec.yamlのenvironmentフィールドで指定することで、正常動作するDartのバージョンを指定しておく必要がある。dependenciesと同じ記法で、指定することができる。
例えば、バージョン3.0.0以上のDart SDKと動作するパッケージの場合は、以下のように指定する。

environment:
  sdk: ^3.0.0

このように書くと、pubはインストールされているDart SDKのバージョンの中から、SDK constraintを満たす最新バージョンを見つけようとする。
注意点として、environmentフィールドは、Dart2.0以降で導入された機能なので、下限バージョンをこのバージョン以上にしておく必要がある。また、caret syntaxをSDK constraintsの指定に使えるようになったのは、Dart2.19以降なので、それ以前のDart SDKバージョンにも対応する場合は、traditional syntaxで指定する必要がある。²
Dart SDKは、複数のDart言語のバージョンを同時に扱うことが可能であり、これはnull safetyなどの互換性のない変更が、Dartに導入された際に役立つ。デフォルトでは、Dart言語のバージョンは、SDK constraintsで指定された、Dart SDKの下限バージョンと一致するが、必要に応じて、別バージョンのDartを利用する。より詳しくは、Language versioningを参照。

別のパッケージを使用する際に必要なフィールド

あなたのパッケージが、別のパッケージを利用する際に、指定する必要のあるフィールドもある。具体的には次の3つのフィールド。

dependencies
dev_dependencies
dependency_overrides

使用するパッケージの、バージョンの範囲の指定方法については、「pubspec.yamlの「^2.4.0」はどういう意味か？【caret syntaxについて解説】」を参照。

dependencies

あなたのパッケージが依存するパッケージを記載するフィールド。pubspec.yamlの存在意義とも言える、極めて重要なフィールド。
dependenciesには、あなたのパッケージのユーザーも、同じく必要になるパッケージを記載する。例えば、アプリの機能を実現するために使うパッケージなど。

dev_dependencies

dependenciesフィールドと同じく、依存するパッケージを記載するフィールドだが、こちらは開発時にだけ使うパッケージへの依存を記載するフィールド。
dev_dependenciesには、あなたのパッケージのユーザーには、必要のないパッケージを記載する。例えば、テスト用のパッケージなど。

dependency_overrides

dependency（依存パッケージ）を一時的にオーバーライドする必要がある場合に使うフィールド。
dependency_overridesについてより詳しくは、「pubspec.yamlの「dependency_overrides」とは何か？【Dart・Flutter】」を参照。

パッケージをpub.devで公開する際に必要なフィールド

ここからは、パッケージを開発して、pub.devなどに公開する際に必要なフィールド。
Flutterアプリ開発においては、基本的に必要のないフィールドなので、詳細は公式ドキュメントに譲るが、パッケージの利用者でも知っておいた方が良い程度の、概要だけを紹介していく。

version

パッケージのバージョンを記載するフィールド。パッケージを、pub.devで公開する際には必須。
ただし、公開せずにローカルだけで使うパッケージでは省略が可能。省略した場合は、暗黙的にバージョン0.0.0になる。
バージョンの決定には、セマンティックバージョニングに従うようにする。³
パッケージのユーザーに及ぶ影響を最小化するために、一度リリースしたバージョンには、一切変更を加えないようにする。変更を行った際は、新しいバージョンとしてリリースする。

description

パッケージの概要・キャッチコピーを記載するフィールド。パッケージを、pub.devで公開する際には必須。
60−180文字の英語のプレーンテキストで書く必要がある。

homepage

パッケージのWebサイトのURLを載せるフィールド。
このフィールド以降は、pub.devでの公開に際しても必須ではない（ただし、記載が推奨される）。

repository

パッケージのソースコードがあるリポジトリのURLを指定するフィールド。通常はGitHubページなど。
パッケージを公開する場合は、homepageとリポジトリの両方（もしくはどちらか）を記載することが推奨される。

issue tracker

パッケージのissueのURLを指定するフィールド。
repositoryにGitHubリポジトリが指定されているなら、pub.devが自動で、issueのタブのリンクを掲載してくれる。

documentation

ドキュメントのURLを指定するフィールド。
pubが作成したAPIリファレンス以外に、ドキュメントがある場合には指定する。

executables

パッケージが持つ、コマンドラインから実行できるスクリプトを公開するために使うフィールド。
executables下に、次のような形式で記載する。

<name-of-executable>: <Dart-script-from-bin>

<Dart-script-from-bin>を省略すると、<name-of-executable>と同じ名前のファイルが指定される。
なので、次のように書くと、bin/fvm.dartが指定されたことになる。

executables:
  slidy: main
  fvm:

platforms

パッケージが対応しているプラットフォームを明示的に記載するフィールド。Dart2.16から追加された。
pub.devが検出した対応プラットフォームが間違っている場合もあるので、その場合に指定する。
Flutterプラグインにおいては、このフィールドの代わりにplugin declarationsを使う。

publish_to

パッケージをどこに公開するかを指定するフィールド。
デフォルトはpub.devで、以下のようにnoneを指定すると、公開しない意図を示すことができる。
custom pub package serverを指定することも可能。

publish_to: none

funding

開発者を経済的に支援したいユーザーのため、buy me coffeeなどのURLを貼ることができるフィールド。
pub.devに公開されたパッケージでは、ページに掲載される。

false_secrets

pubでは、公開の申請時に、機密情報の漏洩がないかを調べて、もしあれば開発者に警告を出し、公開が失敗するようになっている。
ただし、検出の精度は完璧ではないので、偽陽性（問題ないのに問題があると言われる）を避けるために、情報の漏洩の有無を調べないファイルを指定することができる。
false_sercretsは、調べないファイルを指定するためのフィールド。Dart2.15からの機能。
具体的には、以下のように、false_secret下にgitignoreと同じパターンを使って、調べないファイルを指定する。
とはいえ、leak detectionを信頼せずに、自分で確認することが大事。

false_secrets:
 - /lib/src/hardcoded_api_key.dart
 - /test/localhost_certificates/*.pem

screenshots

pub.devに掲載するスクリーンショットを指定するフィールド。

topics

pub.devの検索用途で使われるトピックを追加するためのフィールド。
具体的なトピックの候補は、Topicsを参照。
例えば、次のように指定する。

topics:
  - network
  - http

ignored_advisories

security advisoriesが発する警告を無視するためのフィールド。
より詳しくは、security advisoriesを参照。

Flutterアプリには必要なフィールド

これまでに見てきたのは、すべてのDartパッケージのpubspec.yamlにおいて必要なフィールドだったが、Flutterアプリのpubspec.yamlでのみ、必要なフィールドもある。
以下のpubspec.yamlは、flutter.devに掲載されている例を、コメント部分を和訳するなど、少し修正して引用したもの。⁴
これまでに登場したフィールドもあるが、復習がてら、すべて意味がわかるか確認してみよう。
以下で指定している、バージョンやパスなどの具体的な値に深い意味はないので、どんなフィールドがあるかだけに注目。

name: <project name>
description: A new Flutter project.

publish_to: none

version: 1.0.0+1

environment:
  sdk: ^3.3.0

dependencies:
  flutter:          # Flutterプロジェクトに必須
    sdk: flutter # Flutterプロジェクトに必須
  flutter_localizations: # ローカライゼーションを有効にするために必須
    sdk: flutter # ローカライゼーションを有効にするために必須

  cupertino_icons: ^1.0.6 # Cupertino（iOSスタイル）のアイコンを使用する場合に必要

dev_dependencies:
  flutter_test:
    sdk: flutter # テストを含むFlutterプロジェクトに必須

  flutter_lints: ^3.0.1 # Flutterのコードに推奨されるリントのセットを含む

flutter:

  uses-material-design: true # Materialアイコンフォントを使用する場合に必須

  generate: true # arbファイルからのローカライズされた文字列の生成を有効にする

  assets:  # 画像ファイルなどのアセットをリストする
    - images/a_dot_burr.jpeg
    - images/a_dot_ham.jpeg

  fonts:    # アプリがカスタムフォントを使用する場合に必須
    - family: Schyler
      fonts:
        - asset: fonts/Schyler-Regular.ttf
        - asset: fonts/Schyler-Italic.ttf
          style: italic
    - family: Trajan Pro
      fonts:
        - asset: fonts/TrajanPro.ttf
        - asset: fonts/TrajanPro_Bold.ttf
          weight: 700