craft-cloud

Craft Cloud — Craft CMS 向けサーバーレスホスティング

Craft CMS 向けの Pixel & Tonic のサーバーレスホスティングプラットフォーム、Craft Cloud のリファレンスです。craft-cloud.yaml 設定ファイル、Build → Migrate → Release のデプロイパイプライン、craftcms/cloud 拡張機能、エッジ画像変換と静的キャッシュ、Cloud ファイルシステム、プラグインの Cloud 互換要件、およびセルフホストから Cloud への移行について説明します。

このスキルは Craft Cloud のみに特化 しており、Forge、Servd、またはベアメタルで Craft を実行する場合と Cloud での違いを扱います。Servd については、servd スキルを参照してください。従来のホストでの一般的な Craft デプロイ（ビルド成果物、プロジェクト設定の同期、アトミックデプロイ）については、craftcms スキルの deployment.md を参照してください。

関連スキル — 必要に応じて読み込む

• craftcms — Cloud の話題がプラグインやモジュールの PHP 作業に関わる場合（例：サービスでの App::isEphemeral() ガード、アセットバンドルの制約、15 分の上限を考慮したキュージョブの設計）。
• craft-site — Cloud がフロントエンドのテンプレート作成に関わる場合（キャッシュされたページ内の ESI アイランド、エッジ画像変換の使用、静的キャッシュをオプトアウトする {% expires %}）。
• ddev — ローカル開発環境との同等性を確保する手順（PHP／DB バージョンの一致、ローカルでの一時ファイルシステムのシミュレーション）。
• craft-php-guidelines — Cloud 互換性チェックを追加するためにプラグインの PHP を編集する場合。

ドキュメント

このスキルの作成に使用した信頼できる情報源：

• Craft Cloud ドキュメントのトップページ：https://craftcms.com/docs/cloud/
• 設定リファレンス：https://craftcms.com/docs/cloud/config
• デプロイパイプライン：https://craftcms.com/docs/cloud/deployment
• ビルド：https://craftcms.com/docs/cloud/builds
• 互換性と制限事項：https://craftcms.com/docs/cloud/compatibility
• アセットと変換：https://craftcms.com/docs/cloud/assets
• 静的キャッシュ：https://craftcms.com/docs/cloud/static-caching
• ヘッドレスアプリ：https://craftcms.com/docs/cloud/headless-apps
• リクエスト署名：https://craftcms.com/docs/cloud/request-signing
• プラグイン開発：https://craftcms.com/docs/cloud/plugin-development
• Cloud 拡張機能のソース：https://github.com/craftcms/cloud

各主張の URL は各リファレンスファイルに記載されています。ドキュメントと craftcms/cloud-extension-yii2@main に照らして 2026-05-28 に最終確認済みです。ヘッドレス／リクエスト署名、成果物 URL、環境、クォータ、バックアップに関する内容は craftcms/docs@main に照らして 2026-09-02 に確認済みです。

Cloud とセルフホストの違い

概要をすばやく確認できる表です。各行には、セルフホストの慣習に従うと誤解しやすい点を示しています。

項目	セルフホスト	Cloud
設定ファイル	.env、config/general.php、config/db.php、お使いの Web サーバー設定	プラットフォーム設定はリポジトリのルートにある craft-cloud.yaml、実行時環境変数は Craft Console UI で設定（.env ではありません）
デプロイ	設定した方法（Forge、GitHub Actions、rsync）	Git push → 自動で ビルド → 移行 → リリース（ビルド上限 15 分）
ファイルシステム	ローカルディスク、または独自の S3/R2 設定	一時的な Lambda ファイルシステムです。書き込みを制御するには App::isEphemeral() を使用してください。ユーザーアセットには、Cloud にバンドルされた S3 ベースのファイルシステムタイプを使用する必要があります
データベース	インストールしたもの	MySQL 8.0 または Postgres 15 のみ — MariaDB、tablePrefix、db.php の変更、CRAFT_DB_* による上書きは不可
アプリ／コンポーネント設定	config/app.php でコンポーネントを自由に上書きできます	拡張機能が複数のコンポーネント（response、session、cache、mutex、queue、assetManager）と DB 接続を所有します。app.*.php でこれらを上書きすると設定が壊れ、ローカルでは再現できません（拡張機能は Cloud 上でしか動作しません）
ヘッドレス／API の利用者	GraphQL エンドポイント、独自のレート制限	ボット検出によって自動化されたトラフィックの優先度が下がります。リクエストに署名（RFC 9421、$CRAFT_CLOUD_SIGNING_KEY）を付けてバックオフ付きで再試行しない限り、SSG ビルド／ISR は 429/503 を受け取ります
キュージョブ	ワーカーを実行します（systemd、supervisor、cron）	Cloud が自動処理します。ランナーをスケジュールしないでください。各ジョブの上限は 15 分です
Cron	crontab -e、任意の頻度	Craft Console UI のみ。最短でも 1 時間に 1 回
画像変換	ImageOptimize／Imager-X／標準機能	Cloudflare Images によるエッジ変換 — テンプレートの変更は不要ですが、ImageOptimize には互換性がありません
ページキャッシュ	Blitz など	craft-cloud.yaml の cache.rules によるエッジ静的キャッシュ。タグベースの自動無効化
キャッシュされたページ内の動的アイランド	キャッシュドライバーごとの回避策	標準機能として cloud.esi(...) Twig ヘルパーを提供
ログ	storage/logs/ 内のファイル	Craft::info/warning/error() のみ — ファイルを追跡する UI はありません。Console コマンドの出力が事実上の確認手段です
メール	sendmail または任意のアダプター	組み込みのメール機能はありません — SMTP／Postmark／SES／Resend をご自身で用意してください
SSH	ssh user@server	なし — Console コマンドランナーのみ（255 文字上限、15 分上限）
サーバーのリライト	.htaccess／nginx 設定	craft-cloud.yaml の redirects: および rewrites: キー
カスタムドメイン	DNS プロバイダー＋証明書	DNS＋所有権確認用 TXT＋edge.craft.cloud への CNAME。Cloudflare による SSL の自動設定
プレビュー環境	独自の CI	ブランチごとのみ — PR ごとのプレビューについては記載がありません

よくある落とし穴（横断的な注意点）

• App::isEphemeral() ガードなしでディスクに書き込むこと。 Lambda のファイルシステムは一時的なもので、書き込みはリクエスト間で失われます。プラグイン、サービス、マイグレーションでは、一時的な書き込みを行う前に Path サービス（Craft::$app->getPath()->getTempPath()/getStoragePath()/getCachePath()）を確認して使用する必要があります。references/extension.md（App::isEphemeral）および references/plugin-development.md を参照してください。
• config/app.php / app.web.php / app.console.php で Cloud が所有するアプリコンポーネントを再設定すること。 craftcms/cloud 拡張機能は response コンポーネントを拡張し（ヘッダーの正規化、gzip、バイナリから S3 へのオフロードをすべて EVENT_AFTER_PREPARE に接続）、session、cache、mutex、queue、assetManager を置き換えます。また、データベース接続も自動的に配線します。アプリ設定でこれらを再定義または拡張すると、その配線と衝突し、すべてのリクエストで HTTP 500 が発生する可能性があります（また、エッジキャッシュが迂回される可能性もあります）。これには DB も含まれます。db.php を設定したり、CRAFT_DB_* 環境変数を設定したりしないでください。レスポンスロジック（たとえば Content-Language ヘッダー）を追加する場合は、モジュールから実行時にレスポンス インスタンス に接続してください。Craft::$app->getResponse()->on(\yii\web\Response::EVENT_AFTER_PREPARE, …) のように指定します。response コンポーネントを再定義してはいけません。また、これらの変更をローカルで検証してはいけません。 この拡張機能が実行されるのは Cloud 上だけです（DDEV では Helper::isCraftCloud() が false です）。そのため、ローカルで HTTP 200 が返っても何の証明にもなりません。app.*.php は本番環境でのみ検証可能なものとして扱ってください。references/database.md および references/extension.md を参照してください。
• tablePrefix を使用すること。 Cloud ではサポートされていません。マイグレーションの前に php craft db/drop-table-prefix を実行してください。references/migration.md を参照してください。
• MariaDB を選択すること。 Cloud がサポートするのは MySQL 8.0 と Postgres 15 のみです。
• 独自のキューランナーをスケジュールすること。 Cloud はキュージョブを自動処理するため、キューランナー用のスケジュールコマンドを追加しても重複し、競合する可能性があります。
• マイグレーションからキャッシュ全体をフラッシュすること。 Migrate フェーズ中に Craft::$app->getCache()->flush()（または全体を消去する処理）を実行すると、共有キャッシュ上でまだ稼働中の旧バージョンと競合します。また、Redis/Valkey がプロビジョニングされていない場合、キャッシュは単一の MySQL テーブルとなるため、フラッシュによってデッドロック（MySQL 1205）が発生し、デプロイの CLI 上限を超える可能性があります。変更された項目だけを無効化してください。references/deploy-pipeline.md（マイグレーションからキャッシュ全体をフラッシュしない）および references/extension.md（キャッシュ、キュー、セッションの配線）を参照してください。
• エレメントの保存フックで外部 HTTP リクエストを同期的に実行すること。 保存のたびに処理がブロックされ、再保存時や cloud/up の実行時にはネットワーク遅延がデプロイの CLI 上限に加算されます。代わりに呼び出しをキューに入れてください。references/plugin-development.md を参照してください。
• cron を 1 時間より短い間隔でスケジュールしようとすること。 Cloud の UI では最短間隔が 1 時間に設定されています。この制限を前提に定期タスクを設計するか、ほかのイベントをトリガーとしてキュージョブ内で処理してください。
• キャッシュ可能なテンプレートで {{ csrfInput() }} を使用すること。 Cookie が強制され、エッジの静的キャッシュが無効になります。代わりに csrfInput() 関数を使用してください。asyncCsrfInputs と互換性のある非同期入力がレンダリングされます（Cloud では強制的に有効になります）。
• キャッシュされたルートで、ログインユーザーに currentUser によって制御される UI が表示されると期待すること。 Cloud はログインリクエストに対してエッジキャッシュを自動的にバイパスしません。URL のゲスト向けコピーがキャッシュされると、エディターにも同じコピーが提供され（cf-cache-status: HIT）、サーバー側でレンダリングされた編集リンクや会員限定ブロックが気付かないうちに表示されなくなります。ネストされた cache: → rules: キーの下で、session: ではなくセッション Cookie（cookies: [CraftSessionId]）をキャッシュキーに含めてください。references/caching-and-edge.md を参照してください。
• リポジトリ内の .htaccess ルールや nginx 設定を使用すること。 適用されません。craft-cloud.yaml の redirects: / rewrites: に移してください。references/config-file.md を参照してください。
• ログファイルに書き込むこと。 永続ファイルシステムはありません。Craft::info/warning/error() を使用すると、ロガーが Cloud のログターゲットに自動的にルーティングします。references/extension.md を参照してください。
• SSH アクセスがあると思い込むこと。 SSH アクセスはありません。コマンドを実行する唯一の方法は Console コマンドランナーで、引数の上限は 255 文字、タイムアウトは 15 分です。
• フォークした Git リポジトリを使用すること。 Cloud はフォークからデプロイできません。アップストリームのリポジトリである必要があります。
• PR ごとのプレビュー環境があると期待すること。 Cloud がサポートするのはブランチごとの環境のみで、プルリクエストごとに一時環境が自動作成されることはありません。
• デフォルトの sendmail アダプターを使用すること。 メールは配信されません。SMTP/Postmark/SES/Resend を明示的に設定してください。references/limitations.md（メール）を参照してください。
• Cloud で ImageOptimize を使用すること。 Cloud は Cloudflare Images を通じてエッジで変換を処理します。ImageOptimize は処理を重複させ、競合する可能性があります。references/assets-and-transforms.md を参照してください。
• 署名されていない自動トラフィック（SSG ビルド、ISR の再検証、CI）が 429/503 を受け取ること。 Cloud のボット検出は、ヘッドレスでのコンテンツ取得をボットトラフィックとして正しく判定します。環境の $CRAFT_CLOUD_SIGNING_KEY（RFC 9421）を使用してサーバー側のリクエストに署名し、Retry-After を考慮したバックオフで 429/503 を再試行してください。署名はボットポリシーを回避しますが、容量制限は回避しません。キーをクライアント側に公開してはいけません。references/headless.md を参照してください。
• 本番環境以外で、すべてをブロックする robots.txt や初回リクエストの遅延が発生すること。 Cloud は、本番環境としてマークされていないすべての環境に Disallow: / を挿入し、非本番環境の関数を約 15 分間アイドル状態が続いた後にスリープさせます。どちらも仕様です。デバッグの前に、本番環境の設定を確認してください。references/limitations.md（環境）を参照してください。
• Console の環境変数を変更すればすぐに反映されると思い込むこと。 変数の変更は次回のデプロイでのみ有効になります。references/deploy-pipeline.md を参照してください。

参考ファイル

タスクに関連する参考ファイルを読み込んでください。複数のファイルが該当することもよくあります。

タスクの例：

• 「Cloud で新しい Craft プロジェクトをセットアップする」→ config-file.md + deploy-pipeline.md + extension.md
• 「PHP と Node のバージョンに合わせて craft-cloud.yaml を設定する」→ config-file.md
• 「craft-cloud.yaml にリダイレクトを追加する」→ config-file.md（リダイレクトとリライト）
• 「デプロイ中に何が起きるか」→ deploy-pipeline.md
• 「ビルド時の環境変数を設定する」→ deploy-pipeline.md（ビルド時と実行時の変数）
• 「Cloud で予約済みの環境変数、または設定すべきでない環境変数はどれか」→ deploy-pipeline.md（予約済みの実行時変数）
• 「php craft cloud/up は何をするか」→ extension.md（cloud/up の内部処理）
• 「キャッシュされたページ内に ESI アイランドを追加する」→ caching-and-edge.md
• 「エッジの静的キャッシュルール」→ caching-and-edge.md
• 「セルフホスト環境から Cloud にユーザーアセットを移行する」→ assets-and-transforms.md + migration.md
• 「このプラグインを Cloud 対応にする」→ plugin-development.md
• 「プラグインのファイル書き込みが Cloud で何も表示せずに失敗する理由」→ plugin-development.md（一時ファイルシステム）+ extension.md（App::isEphemeral）
• 「カスタムドメインをセットアップする」→ domains.md
• 「定期的なコマンドをスケジュールする」→ commands-and-cron.md（最小間隔は1時間）
• 「Cloud で単発のコマンドを実行する」→ commands-and-cron.md（コンソールコマンドランナー）
• 「Cloud で SMTP を設定する」→ limitations.md（メール）+ craftcms/email.md
• 「Cloud に合わせてローカルの DDEV をセットアップする」→ local-dev.md
• 「セルフホストの Craft サイトを Cloud に移行する」→ migration.md
• 「Cloud で使えるプラグインはどれか」→ limitations.md（プラグインの互換性 — コミュニティの知見）
• 「Next.js／Nuxt／Astro のビルドで Cloud から 429 が返る」→ headless.md
• 「Cloud へのプログラムによるリクエストに署名する」→ headless.md（リクエスト署名）
• 「テンプレートからビルド済みの JS／CSS にリンクする」→ deploy-pipeline.md（アーティファクト URL）
• 「Cloud でプライベートな Composer パッケージを使う」→ deploy-pipeline.md（プライベート Composer パッケージ）
• 「robots.txt がサイトをブロックしている」→ limitations.md（環境）

タスクに必要な参考ファイルのみを読み込んでください。

参照	範囲	約行数
references/config-file.md	craft-cloud.yaml のキー全般に関するリファレンス：php-version、node-version、node-path、npm-script、artifact-path（webroot の非公開化に関する注意）、app-path、webroot、cache: → rules:、redirects、rewrites	156
references/deploy-pipeline.md	ビルド → マイグレーション → リリースの流れ、On Push と Manual のトリガー、ビルド上限 15 分、ビルド時のシステム変数（CRAFT_CLOUD_*、GIT_SHA）、Console の実行時環境変数（変更後は再デプロイが必要）、設定してはならない予約済み／注入変数（CRAFT_SECURITY_KEY、CRAFT_APP_ID、CRAFT_OMIT_SCRIPT_NAME_IN_URLS、CRAFT_DB_*、REDIS_*、…）、アーティファクト URL（cloud.artifactUrl()、@artifactBaseUrl、キャッシュバスティングなし、manifest／svg() による CDN 読み込み、ホワイトラベル CDN の書き換え）、プライベート Composer パッケージ（Composer Auth）、マイグレーション失敗時のロールバックの仕様	210
references/headless.md	ヘッドレスアプリとリクエスト署名：SSG／ISR トラフィックに対するボット検出と 429／503、$CRAFT_CLOUD_SIGNING_KEY を使った RFC 9421 HMAC 署名（有効期間 5 分、URL の完全一致、ゲートウェイ検証に失敗した場合は通知なくフォールバック）、Retry-After とバックオフ再試行の契約（読み取りのみ、再試行を使い切った場合は例外をスロー）、Next.js／Nuxt／Astro との統合、getRequestSigner() による Craft からの署名	107
references/extension.md	craftcms/cloud パッケージ：Yii2 モジュールのブートストラップ、App::isEphemeral()、Path サービスの使用、cloud.esi() Twig ヘルパー、cloud/up の内部処理（ソースで確認済み）、アセットバンドルの CDN パブリッシャー、バイナリレスポンスの自動アップロード、ログターゲット	201
references/assets-and-transforms.md	Cloud ファイルシステムの種類（assets/ サブパスが必須）、aws s3 sync による移行、エッジでの画像変換（70MB／100MP／12,000px の上限、AVIF は 1,600px が上限、stretch モードの制約）、テンプレート側の変更は不要	87
references/database.md	MySQL 8.0／Postgres 15 のみ（MariaDB は不可）、tablePrefix の禁止、php craft db/drop-table-prefix、自動接続設定、夜間およびオンデマンドのバックアップ（保持期間 30 日、上限 200GB、Cloud の耐久性アーキテクチャには含まれない）、復元コマンド	111
references/caching-and-edge.md	静的キャッシュルール（cache: の入れ子を rules: に変更、pattern + query-string + cookies、最初に一致したルールを適用）、デフォルトで無視されるトラッキングパラメーター（カスタムルールを設定するとリストが置き換わる）、ログインユーザーとキャッシュされたゲスト向けコピー（cookies: [CraftSessionId]）、キャッシュを無効にする方法（{% expires %}、setNoCacheHeaders()）、flash-guard パターン、Commerce のカートに関する注意、asyncCsrfInputs は常に有効、動的なアイランドに使う cloud.esi(...)（スカラー変数のみ、入れ子不可）、タグベースの自動無効化	347
references/domains.md	DNS 設定（_cf-custom-hostname TXT、edge.craft.cloud への CNAME、apex A レコード、Cloudflare のオレンジからオレンジ）、プレビュー URL の形式、自動 SSL、www は自動追加されないこと、追加ドメインの料金	104
references/commands-and-cron.md	Console コマンドランナー（SSH なし、255 文字上限、15 分上限、シェル補間なし）、スケジュール済みコマンド（最短 1 時間ごと、環境ごとに最大 5 個）、キュージョブは自動処理される（ランナーをスケジュールしないこと）、ジョブごとの上限 15 分、長時間処理にはバッチ化したジョブを使用	143
references/plugin-development.md	Cloud 対応プラグインのチェックリスト：アセットバンドルの制約、App::isEphemeral() によるゲーティング、Path サービス、ログには Craft::info() を使用、キュージョブの実行時間予算、Cookie に依存しない設計、csrfInput() 関数（CSRF トークン漏えいに関する警告）、sendContentAsFile() の自動処理、アセット選択の優先、Craft 4.6 以降が必須	234
references/migration.md	セルフホスト環境から Cloud への切り替え：監査（テーブルプレフィックス、MariaDB、ファイル書き込み、.htaccess、サードパーティの S3 プラグイン）、php craft db/drop-table-prefix、aws s3 sync によるアセット移行、DNS 切り替えの手順、プロジェクト設定の同期	132
references/local-dev.md	Cloud と同等の環境を再現する DDEV の設定例：craft-cloud.yaml に合わせた PHP、DB エンジンとバージョン、Cloud 拡張機能の自動検出とローカルでの no-op、ガードのテスト用に必要に応じて設定する CRAFT_EPHEMERAL、S3 エミュレーションの参考情報	145
references/limitations.md	ドキュメント化された非対応機能（MariaDB、tablePrefix、.htaccess、SSH、sendmail、本番環境での devMode、フロントエンドからのアップロードを含むレスポンス上限 6MB、ヘッダー上限 16KB、リクエストタイムアウト 60 秒、アップロード上限 200MB、環境の複製不可、リージョン変更不可、PR ごとのプレビュー不可、CP の DB バックアップユーティリティは無効、フォークしたリポジトリからはデプロイ不可）＋環境に関する事実（非本番環境では robots.txt が Disallow を指定、関数はスリープ、アセットバケットを共有、削除は完全削除）＋平坦化された重複ヘッダー、機能しない resourceBase* ＋コミュニティの知見に基づくプラグイン互換性一覧（ImageOptimize、Imager-X、Blitz、Typesense など。Pixel & Tonic が推奨するものではないと明記）＋メール送信戦略＋ロギングの不足	239