buildpack
最終更新日 2025年04月03日(木)
Table of Contents
buildpack はコードを最小限の構成でデプロイ可能なアーティファクトに変換し、dyno で実行するスクリプトのセットです。コードをデプロイすると、可能な場合はアプリに使用する適切な buildpack が自動的に検出されます。
Heroku では一連のオープンソース buildpack を通じて、Ruby、Python、Java、Clojure、Node.js、Scala、Go、PHP、.NET のサポートを実装しています。
典型的な buildpack は次のような操作を実行します。
- ソースコードを検査してプログラミング言語とバージョンを検出する
- プログラミング言語のバイナリをインストールする
- 依存関係をインストールする
- コードをコンパイルする
- フロントエンドアセットを構築する
- その他多数…
Heroku では自社プラットフォームの Heroku Cedar 世代向けに公式にサポートされているクラシック buildpack のコレクションと、Fir 世代向けに公式にサポートされている Heroku Cloud Native buildpack のコレクションを維持管理しています。
git push を使用してコードをデプロイする代わりに、Docker イメージを Heroku Cedar に直接デプロイすることもできます。
クラシック buildpack
Cedar では、Slug コンパイラがクラシック buildpack の出力を実行可能な Slug にアセンブルします。
プラットフォーム API を介して Slug を手動で作成およびデプロイすることもできます。
Fir ではクラシック buildpack を使用できません。
クラシック buildpack では、Heroku のベースイメージのバージョン (例: heroku-24) を heroku stacks:set で設定します。
Cloud Native buildpack
Fir では、Heroku が Cloud Native buildpack (CNB) の使用をサポートしています。CNB はコードから Open Container Initiative (OCI) イメージを構築します。CNB は Fir でのみ利用可能です。
こちらの短い紹介ビデオをご覧ください。Cloud Native buildpack の背後にある概念をより深く理解するには、buildpack.io の公式ドキュメントを参照してください。
Heroku Cloud Native buildpack
Heroku Cloud Native buildpack は、Cedar プラットフォームと同じエクスペリエンスを Fir やコンテナをサポートするその他の場所にも提供できるようにできている CNB です。Heroku CNB は Heroku Fir へのデプロイに適した本番環境対応イメージを生成します。
すべての Fir 世代の Heroku アプリがデフォルトで CNB を使用します。これらは CNB ビルダー heroku/builder:24 を通じて Fir に提供されます。このビルダーは、Pack CLI とローカルで併用することもできます。
CNB で使用される Heroku ベースイメージのバージョンはビルダーによって異なります。デフォルトとは異なるビルダーとベースイメージを使用する場合は、project.toml ファイルを変更します。
heroku stacks CLI コマンドはクラシック buildpack を使用するアプリを管理するためのものです。クラシック buildpack アプリの場合、stack の値は Heroku ベースイメージのバージョンですが、Cloud Native buildpack アプリの場合、stack は常に cnb になります。
クラシック buildpack とは異なり、Heroku Cloud Native buildpack には以下が備わっています。
- arm64 CPU アーキテクチャのサポート
- オープンスタンダードへの準拠
- クラウドネイティブツールとの互換性
- ローカルビルドのデバッグや検査などのオフプラットフォームユーザビリティ
「クラシック buildpack と Cloud Native Buildpack」の比較を参照してください。
サポート対象 buildpack
Heroku では、公式にサポートされているクラシック buildpack と Heroku CNB のコレクションを維持管理しています。詳細は、「公式にサポートされる buildpack」を参照してください。
サードパーティの buildpack
Heroku で公式にサポートされている buildpack の対象とならない言語またはフレームワークをサポートするために、カスタム buildpack を使用することができます。詳細は、「サードパーティの buildpack の使用」を参照してください。Heroku ではカスタム buildpack の公式サポートを提供していません。
buildpack の自動検出
コードをデプロイすると、可能な場合はアプリに使用する適切な buildpack が自動的に検出されます。検出基準は言語によって異なります。たとえば、Node buildpack は package.json ファイルを検索します。
クラシック buildpack を使用するアプリの場合、手動で buildpack を設定した場合と同様に、ビルドに成功すると検出された buildpack は今後のアプリケーションにプッシュするために永続的に設定されます。
CNB を使用するアプリの場合、buildpack が project.toml で明示的に指定されていない限り、デプロイするたびに自動検出が行われます。
検出の失敗
通常、Heroku ではアプリに使用する buildpack を検出できますが、検出が失敗する一般的な原因がいくつかあります。
- Rust や Elixir など、Heroku の公式 buildpack ではサポートされていない言語がアプリで使用されている。
- Node.js アプリの package.json や Go アプリの go.mod など、重要なファイルがアプリにない。
このような場合は buildpack を手動で設定できます。
buildpack の動作
Heroku のプラットフォーム上の各 buildpack の動作を説明する記事については、サポートされている各言語のドキュメントカテゴリを参照してください。「公式にサポートされる buildpack」に記載されている GitHub リンクをクリックして、各リポジトリの buildpack の詳細を読むこともできます。
buildpack の管理
多くのアプリでは、自動検出された buildpack のみを必要とします。
アプリの buildpack は手動で追加および削除できます。詳細は、「buildpack の管理」を参照してください。
1 つのアプリケーションに複数の buildpack が必要となるシナリオは数多くあります。手順については、「アプリの複数の buildpack の使用」を参照してください。典型的なシナリオとしては、PgBouncer を使用したデータベース接続プールや、Ruby、Python、または PHP アプリケーションと組み合わせた Node.js ライブラリを使用したアセット処理などがあります。
buildpack の作成
Heroku でまだサポートされていない言語またはフレームワークを使用する場合、カスタム buildpack を作成できます。
クラシック buildpack の使用を開始するには、「buildpack API」でその構造について確認してください。
独自の Cloud Native buildpack を作成する方法については、buildpack.io の公式ドキュメントを参照してください。
トラブルシューティング
「buildpack エラーのトラブルシューティング」を参照してください。
Cloud Native buildpack の制限
Heroku Fir 上の CNB ビルドではアプリの環境設定を使用できません。これらの環境変数がない場合、ビルド時に非公開の依存関係のインストールが回避されます。非公開の依存関係をリポジトリにベンダーするか、非公開の依存関係を回避します。
project.toml で環境変数を設定できますが、シークレットには使用しないでください。詳細は、「環境設定を設定する」を参照してください。