pubspec ファイル

すべてのpub パッケージには、その依存関係を指定するためのメタデータが必要です。他の人と共有される Pub パッケージは、ユーザーがそれらを発見できるように、その他の情報も提供する必要があります。このメタデータはすべて、パッケージの *pubspec* に格納されます。これは、YAML言語で記述された `pubspec.yaml` という名前のファイルです。

pubspec には、以下のフィールドを含めることができます。

name: すべてのパッケージに必要なフィールドです。詳細はこちら。
version: pub.dev サイトでホストされるパッケージに必要なフィールドです。詳細はこちら。
description: pub.dev サイトでホストされるパッケージに必要なフィールドです。詳細はこちら。
homepage: オプション。パッケージのホームページ（またはソースコードリポジトリ）を指すURLです。詳細はこちら。
repository: オプション。パッケージのソースコードリポジトリを指すURLです。詳細はこちら。
issue_tracker: オプション。パッケージのイシュートラッカーを指すURLです。詳細はこちら。
documentation: オプション。パッケージのドキュメントを指すURLです。詳細はこちら。
dependencies: パッケージに依存関係がない場合は省略できます。詳細はこちら。
dev_dependencies: パッケージに開発用依存関係がない場合は省略できます。詳細はこちら。
dependency_overrides: 依存関係をオーバーライドする必要がない場合は省略できます。詳細はこちら。
environment: Dart 2 以降必須です。詳細はこちら。
executables: オプション。パッケージの実行ファイルを PATH に追加するために使用されます。詳細はこちら。
platforms: オプション。pub.dev サイトでサポートされているプラットフォームを明示的に宣言するために使用されます。詳細はこちら。
publish_to: オプション。パッケージの公開先を指定します。詳細はこちら。
funding: オプション。ユーザーがパッケージの開発をスポンサーできるURLのリストです。詳細はこちら。
false_secrets: オプション。潜在的なシークレットの漏洩を事前に検索する際に無視するファイルを指定します。詳細はこちら。
screenshots: オプション。pub.dev サイトに表示するスクリーンショットファイルのリストを指定します。詳細はこちら。
topics: オプション。パッケージのトピックのリストです。詳細はこちら。
ignored_advisories: オプション。無視されたセキュリティに関する勧告のリストです。詳細はこちら。

Pub はその他のフィールドをすべて無視します。

カスタムフィールドを追加する場合は、将来の pubspec フィールドと競合しない一意の名前を付けます。たとえば、`bugs` を追加する代わりに、`my_pkg_bugs` という名前のフィールドを追加できます。

シンプルで完全な pubspec は、次のようになります。

yamlname: newtify
description: >-
  Have you been turned into a newt?  Would you like to be?
  This package can help. It has all of the
  newt-transmogrification functionality you have been looking
  for.
version: 1.2.3
homepage: https://example-pet-store.com/newtify
documentation: https://example-pet-store.com/newtify/docs

environment:
  sdk: '^3.2.0'
  
dependencies:
  efts: ^2.0.4
  transmogrify: ^0.4.0
  
dev_dependencies:
  test: '>=1.15.0 <2.0.0'

このセクションでは、各 pubspec フィールドの詳細について説明します。

すべてのパッケージには名前が必要です。これは、他のパッケージがあなたのパッケージを参照する方法であり、公開する場合は世界に表示される方法です。

名前はすべて小文字で、単語を区切るためにアンダースコアを使用する必要があります（`just_like_this` のように）。基本的なラテン文字とアラビア数字のみを使用してください（`[a-z0-9_]`）。また、名前が有効な Dart の識別子であること、つまり数字で始まらないこと、および予約語ではないことを確認してください。

明確で簡潔で、まだ使用されていない名前を選択してみてください。pub.dev サイトでパッケージをすばやく検索して、他のパッケージがあなたの名前を使用していないことを確認することをお勧めします。

すべてのパッケージにはバージョンがあります。バージョン番号は、パッケージを pub.dev サイトでホストするために必要ですが、ローカルのみのパッケージの場合は省略できます。省略した場合、パッケージのバージョンは暗黙的に `0.0.0` となります。

バージョン管理は、コードの再利用を可能にしつつ、迅速な進化を可能にするために必要です。バージョン番号は、ドットで区切られた3つの数字（`0.2.43` のように）です。ビルド（`+1`、`+2`、`+hotfix.oopsie` など）またはプリリリース（`-dev.4`、`-alpha.12`、`-beta.7`、`-rc.5` など）のサフィックスをオプションで含めることもできます。

パッケージを公開するたびに、特定のバージョンで公開します。それが完了したら、それは密閉されたものと見なされます。変更を加えるには、新しいバージョンが必要です。

バージョンを選択する際には、セマンティックバージョン管理に従ってください。

これはあなた自身の個人用パッケージではオプションですが、パッケージを公開する予定がある場合は、説明を提供する必要があります。説明は英語で記述する必要があります。説明は比較的短く（60～180文字）し、カジュアルな読者にパッケージについて知っておきたいことを伝えるようにしてください。

説明は、パッケージのセールストークと考えてください。ユーザーは、パッケージを閲覧する際にこれを見ます。説明はプレーンテキストです。Markdown や HTML は使用できません。

これは、パッケージのウェブサイトを指すURLである必要があります。ホストされたパッケージの場合、このURLはパッケージのページからリンクされています。`homepage` の提供はオプションですが、`homepage` または `repository`（または両方）を *必ず提供してください*。これにより、ユーザーはパッケージの出所を理解するのに役立ちます。

オプションの `repository` フィールドには、パッケージのソースコードリポジトリのURLを含める必要があります（例：`https://github.com/<user>/<repository>`）。パッケージを pub.dev サイトに公開する場合、パッケージのページにリポジトリのURLが表示されます。`repository` の提供はオプションですが、`homepage` または `repository`（または両方）を *必ず提供してください*。これにより、ユーザーはパッケージの出所を理解するのに役立ちます。

オプションの `issue_tracker` フィールドには、パッケージのイシュートラッカーのURLを含める必要があります。ここでは、既存のバグを表示したり、新しいバグを報告したりできます。pub.dev サイトは、このフィールドの値を使用して、各パッケージのイシュートラッカーへのリンクを表示しようとします。`issue_tracker` が存在せず、`repository` が存在し、GitHub を指している場合、pub.dev サイトはデフォルトのイシュートラッカー（`https://github.com/<user>/<repository>/issues`）を使用します。

一部のパッケージには、メインのホームページやPubで生成されたAPIリファレンスとは別に、ドキュメントをホストするサイトがあります。パッケージに追加のドキュメントがある場合は、そのURLをdocumentation:フィールドに追加してください。Pubは、パッケージページにこのドキュメントへのリンクを表示します。

依存関係は、pubspecのraison d'être（存在理由）です。このセクションでは、パッケージが動作するために必要なパッケージをそれぞれリストします。

依存関係には2つのタイプがあります。通常の依存関係はdependencies:の下にリストされます。これらは、パッケージを使用するすべての人が必要とするパッケージです。パッケージ自体の開発段階でのみ必要な依存関係は、dev_dependenciesの下にリストされます。

開発プロセス中に、依存関係を一時的にオーバーライドする必要がある場合があります。dependency_overridesを使用して実行できます。

詳細については、パッケージの依存関係を参照してください。

パッケージは、コマンドラインから直接実行できる実行可能ファイルとして、1つ以上のスクリプトを公開する場合があります。スクリプトを公開するには、executablesフィールドにリストします。エントリはキー/値ペアとしてリストされます。

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

たとえば、次のpubspecエントリは2つのスクリプトをリストしています。

yamlexecutables:
  slidy: main
  fvm:

dart pub global activateを使用してパッケージをアクティブ化すると、slidyと入力するとbin/main.dartが実行され、fvmと入力するとbin/fvm.dartが実行されます。値を指定しない場合は、キーから推測されます。

詳細については、pub globalを参照してください。

パッケージを公開すると、pub.devはパッケージがサポートするプラットフォームを自動的に検出します。このプラットフォームサポートリストが正しくない場合は、platformsを使用して、パッケージがサポートするプラットフォームを明示的に宣言します。

たとえば、次のplatformsエントリにより、pub.devはパッケージをAndroid、iOS、Linux、macOS、Web、Windowsをサポートするものとしてリストします。

yaml# This package supports all platforms listed below.
platforms:
  android:
  ios:
  linux:
  macos:
  web:
  windows:

パッケージがLinuxとmacOSのみをサポートし（たとえば、Windowsはサポートしない）、宣言する例を以下に示します。

yaml# This package supports only Linux and macOS.
platforms:
  linux:
  macos:

デフォルトではpub.devサイトを使用します。パッケージの公開を禁止するにはnoneを指定します。この設定は、カスタムPubパッケージサーバーを指定して公開する場合に使用できます。

yaml

publish_to: none

パッケージ作成者は、fundingプロパティを使用して、ユーザーがパッケージの開発を支援する方法に関する情報を提供するURLのリストを指定できます。例：

yamlfunding:
 - https://www.buymeacoffee.com/example_user
 - https://www.patreon.com/some-account

pub.devに公開された場合、リンクはパッケージページに表示されます。これは、ユーザーが依存関係の開発に資金を提供するのを支援することを目的としています。

パッケージを公開しようとすると、Pubは秘密の認証情報、APIキー、または暗号キーの潜在的な漏洩を検索します。公開されるファイルに潜在的な漏洩が検出された場合、Pubは警告を表示し、パッケージの公開を拒否します。

漏洩検出は完璧ではありません。誤検知を避けるために、gitignoreパターンを使用して、pubspecのfalse_secretsで特定のファイルの検索を禁止できます。

たとえば、次のエントリにより、lib/src/hardcoded_api_key.dartファイルとtest/localhost_certificates/ディレクトリ内のすべての.pemファイルで漏洩が検索されなくなります。

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

gitignoreパターンをスラッシュ（/）で開始すると、パターンがパッケージのルートディレクトリを基準として相対的に考慮されます。

パッケージは、pub.devページに表示されるスクリーンショットを使用して、ウィジェットやその他の視覚要素を展示できます。パッケージに表示するスクリーンショットを指定するには、screenshotsフィールドを使用します。

パッケージは、screenshotsフィールドの下に最大10枚のスクリーンショットをリストできます。このセクションには、ロゴやその他のブランドイメージを含めないでください。各スクリーンショットには、1つのdescriptionと1つのpathが含まれます。descriptionは、スクリーンショットが何を表しているかを160文字以内で説明します。例：

yamlscreenshots:
  - description: 'This screenshot shows the transformation of a number of bytes 
  to a human-readable expression.'
    path: path/to/image/in/package/500x500.webp
  - description: 'This screenshot shows a stack trace returning a human-readable
  representation.'
    path: path/to/image/in/package.png

Pub.devは、スクリーンショットに次の仕様を適用します。

ファイルサイズ：画像あたり最大4MB。
ファイルタイプ：png、jpg、gif、またはwebp。
静止画とアニメーション画像の両方が許可されています。

スクリーンショットファイルは小さく保ってください。パッケージのダウンロードごとに、すべてのスクリーンショットファイルが含まれます。

Pub.devは、最初のスクリーンショットからパッケージのサムネイル画像を生成します。このスクリーンショットがアニメーションを使用している場合、Pub.devはその最初のフレームを使用します。

パッケージ作成者は、topicsフィールドを使用してパッケージを分類できます。トピックは、pub.devでフィルターを使用して検索する際の検出可能性を向上させるために使用できます。Pub.devは、パッケージページと検索結果の両方でトピックを表示します。

このフィールドは、名前のリストで構成されます。例：

yamltopics:
  - network
  - http

Pub.devは、トピックに次の仕様を適用します。

各パッケージには、最大5つのトピックをタグ付けします。
トピック名は、次の要件に従って記述してください。
- 2～32文字を使用します。
- 小文字の英数字またはハイフン（a-z、0-9、-）のみを使用します。
- 連続する2つのハイフン（--）を使用しないでください。
- 名前を小文字のアルファベットで開始します（a-z）。
- 英数字で終了します（a-zまたは0-9）。

トピックを選択する際には、既存のトピックが関連するかどうかを検討してください。既存のトピックでタグ付けすると、ユーザーがパッケージを発見しやすくなります。

パッケージがセキュリティ上のアドバイザリの影響を受ける依存関係を持つ場合、Pubは依存関係の解決中にアドバイザリについて警告します。パッケージ作成者は、ignored_advisoriesフィールドを、パッケージに関連しないトリガーされたアドバイザリの許可リストとして使用できます。

アドバイザリに関する警告を抑制するには、アドバイザリ識別子をignored_advisoriesリストに追加します。例：

yamlname: myapp
dependencies:
  foo: ^1.0.0
ignored_advisories:
 - GHSA-4rgh-jx4f-qfcq

詳細については、セキュリティ上のアドバイザリを参照してください。

パッケージは、サポートする依存関係のバージョンを示すことができますが、パッケージには別の暗黙的な依存関係があります。それはDartプラットフォーム自体です。Dartプラットフォームは時間とともに進化し、パッケージは特定のバージョンのプラットフォームでのみ動作する場合があります。

パッケージは、SDK制約を使用してこれらのバージョンを指定できます。この制約は、pubspec内の別の最上位レベルのenvironmentフィールド内にあり、依存関係と同じバージョン制約構文を使用します。

たとえば、次の制約は、このパッケージがバージョン3.0.0以降のDart SDKで動作することを示しています。

yamlenvironment:
  sdk: ^3.0.0

Pubは、インストールされているDart SDKのバージョンと動作するSDK制約を持つパッケージの最新バージョンを見つけようとします。

SDK制約を省略すると、エラーになります。pubspecにSDK制約がない場合、dart pub getは次のメッセージのようなメッセージで失敗します。

pubspec.yaml has no lower-bound SDK constraint.
You should edit pubspec.yaml to contain an SDK constraint:

environment:
  sdk: '^3.2.0'
  
See https://dart.dokyumento.jp/go/sdk-constraint

Pubは、environment:フィールドの下でFlutter SDK制約の指定をサポートしています。

yamlenvironment:
  sdk: ^3.2.0
  flutter: '>= 3.22.0'

Flutter SDK制約は、pubがflutter実行可能ファイルのコンテキストで実行され、Flutter SDKのversionファイルがバージョン制約の下限を満たしている場合にのみ満たされます。そうでない場合、パッケージは選択されません。

Flutter SDK制約付きのパッケージを公開するには、少なくとも1.19.0の最小バージョンを持つDart SDK制約を指定して、古いバージョンのPubがFlutterを必要とするパッケージを誤ってインストールしないようにする必要があります。

特に明記されていない限り、このサイトのドキュメントはDart 3.5.3を反映しています。ページの最終更新日：2024年10月7日。ソースを表示または問題を報告する。

pubspec ファイル

サポートされているフィールド

例

詳細

名前

バージョン

説明

ホームページ

リポジトリ

イシュートラッカー

ドキュメント

依存関係

実行ファイル

プラットフォーム

公開先

資金提供

不正なシークレット

スクリーンショット

トピック

無視された勧告

SDK 制約

Flutter SDK制約