drupal-config-mgmt

Drupal Configuration Management

Drupal の構成管理に関する包括的なガイドです。インポート、エクスポート、Config Split、環境間の同期を扱います。

リモート CLI — ホストを問いません

以下の例では Pantheon の Terminus（terminus drush <site>.<env> -- <cmd>）を使用しています。コマンドはどのホストでも同じです。お使いのプラットフォームのリモート Drush の形式に置き換えてください。プラットフォームが Drush サイトエイリアスを提供している場合は、汎用の drush @<alias> <cmd> がどこでも使えます。

タスク	Acquia（acli）	Pantheon（Terminus）	Platform.sh / Upsun	Lagoon（amazee.io）	汎用（Drush エイリアス）
リモート Drush	acli remote:drush -- <cmd>	terminus drush <site>.<env> -- <cmd>	platform drush -e <env> -- <cmd>（Upsun：upsun drush …）	lagoon ssh -p <project> -e <env> -C "drush <cmd>"	drush @<alias> <cmd>
構成の取得／確認	acli remote:drush -- config:get <name>	terminus drush <site>.<env> -- config:get <name>	platform drush -e <env> -- config:get <name>	lagoon ssh -p <project> -e <env> -C "drush config:get <name>"	drush @<alias> config:get <name>

以下の自動確認に関する警告は、すべてのホストに当てはまります — 適用するのではなくプレビューするには、cim／config:import に --no を追加してください。Drush は非対話的に実行された場合、デフォルトで --yes を指定します（すべてのリモート CLI ラッパーは非対話的に実行します）。

問題：意図しない構成インポートを避ける

重要：Terminus の Drush コマンドは、明示的に --no を指定しない限り、デフォルトで --yes を指定します。つまり、config:import や cim のようなコマンドは、差分を確認したいだけの場合でも自動的に確認して構成をインポートします。

危険なパターンと安全なパターン

❌ 危険 - 確認なしで自動インポートします：

terminus drush {site}.{env} -- cim --diff  # DON'T DO THIS!

✅ 安全 - インポートせずに差分を表示します：

terminus drush {site}.{env} -- cim --no --diff

✅ 最も安全 - 読み取り専用コマンドです：

terminus drush {site}.{env} -- config:get config.name
terminus drush {site}.{env} -- config:status

目次

1. 推奨する本番構成のマージワークフロー
2. 構成のインポートとエクスポートの基本
3. Config Split の概要
4. 完全分割と部分分割
5. Config Split コマンド
6. 安全な確認ワークフロー
7. 上流環境からの構成同期

---

構成のインポートとエクスポートの基本

一度に名前付きオブジェクトを1つだけ扱うことを基本としてください。 一括の cex は、アクティブ構成と同期構成のすべての差分をディスクに書き込み、一括の cim は、すべての差分をインポート（および削除）します。そのため、自分が作成していない差分があるツリーでは、それらまでコミットやデータベースに取り込んでしまいます。エージェントは config:get／config:set／config:delete、または1つのファイルの部分インポートで構成を変更し、全体のインポートはデプロイに任せます（詳細は drupal-deploy-safety スキルを参照）。一括エクスポートは、全体のエクスポートが目的の場合（本番構成のマージ、分割の変更など）に限り、クリーンでコミット済みのツリーから実行し、その後 git status config/ を確認してください。詳細なルールは surgical-config.md を参照してください。

構成のエクスポート

すべての構成をエクスポート（アクティブ構成から YAML ファイルへ。前述のとおり、クリーンなツリーでのみ実行してください）：

# Local
ddev drush config:export
ddev drush cex

# Remote
terminus drush {site}.{env} -- config:export

単一の構成オブジェクトをエクスポート：

# Get config and save to file
ddev drush config:get config.name --format=yaml > config/default/config.name.yml

# Example: Export a specific view
ddev drush config:get views.view.content --format=yaml > config/default/views.view.content.yml

構成のインポート

すべての構成をインポート（YAML ファイルからアクティブ構成へ。デプロイ時に実行される処理なので、ローカルでプレビューし、リモートでのインポートはデプロイの最後の処理に任せてください）：

# Local
ddev drush config:import
ddev drush cim

# Remote (DANGEROUS - auto-confirms with terminus!)
terminus drush {site}.{env} -- config:import --no  # Use --no to preview only

単一の構成オブジェクトをインポート（そのファイルだけを含むディレクトリから部分インポートします。DDEV では、このディレクトリはプロジェクト内に置く必要があります。surgical-config.md を参照してください）：

mkdir -p .config-one && cp config/default/config.name.yml .config-one/
ddev drush config:import --partial --source=/var/www/html/.config-one -y
rm -rf .config-one

# Or use config:set for specific values
ddev drush config:set config.name key.subkey value

ベストプラクティス：変更を適用する前に、必ずプレビューしてください：

ddev drush config:import --no --diff  # Show what would change
ddev drush cim --no --diff            # Alias

---

Config Split コマンド

重要：アクティブな設定とエクスポートされた設定

⚠️ 重要：設定スプリットの定義を更新するときは、変更をエクスポートされたファイルだけでなく、アクティブな設定（データベース）に反映する必要があります！

ワークフロー：

1. config/default/config_split.config_split.{name}.yml を編集します
2. インポートしてアクティブにします：単一ファイルの部分インポート（上記を参照）、または PHP を使用します（以下を参照）
3. エクスポートします：ddev drush cex。これがフルエクスポートを必要とする唯一の定例ケースです。cex の実行時に config_split がスプリットディレクトリとそのパッチファイルを書き込むためです。クリーンなツリーから開始し、意図していない git status config/ の変更はすべて元に戻してください。

簡易的な方法 - PHP でアクティブな設定を設定：

ddev drush php:eval "\$config = \Drupal::configFactory()->getEditable('config_split.config_split.local'); \$config->set('partial_list', ['config.name']); \$config->save();"

詳しい手順については、examples.md を参照してください。

スプリットを含む設定のエクスポート

アクティブなスプリットを含むすべての設定をエクスポート：

ddev drush config:export

次の設定がエクスポートされます：

• 基本設定は config/default/ に
• アクティブなスプリット設定は config/{split-name}/ に

特定のスプリットをエクスポート：

ddev drush config-split:export {split-name}
ddev drush csex {split-name}

スプリットを含む設定のインポート

アクティブなスプリットを含むすべての設定をインポート：

ddev drush config:import
ddev drush cim

次の設定がインポートされます：

• 基本設定は config/default/ から
• アクティブなスプリット設定は config/{split-name}/ から

特定のスプリットをインポート：

ddev drush config-split:import {split-name}
ddev drush csim {split-name}

基本設定のみをインポート（スプリットを無視）：Drush 13 の config:import にはこのためのオプションがありません（--skip-modules は Drush 8 のオプションでした）。drush config-split:deactivate <split> 自体が、スプリットなしで設定をインポートし、アクティブな設定に status: false を書き込みます。その後、同期された YAML の status: true によって、後続のフル config:import でスプリットが再度有効になります。インポート後も無効のままにするには、ステータスオーバーライドを設定します：drush config-split:status-override <split> inactive（state に保存されます。値は active|inactive|default、エイリアスは csso）。または、settings.php で次のように設定します：

ddev drush config-split:deactivate {split-name}                     # one-off
ddev drush config-split:status-override {split-name} inactive       # sticks across imports

$config['config_split.config_split.{split-name}']['status'] = FALSE;  // settings.php

--partial インポートでは設定変換がスキップされるため、スプリットは一切適用されません。

スプリットの有効化／無効化

スプリットを有効化：

ddev drush config-split:activate {split-name}

スプリットを無効化：

ddev drush config-split:deactivate {split-name}

スプリットのステータスを確認

すべてのスプリットとそのステータスを一覧表示：

ddev drush config-split:status
ddev drush css

出力例：

Split       Active  Configuration directory
local       Yes     ../config/local
dev         No      ../config/dev
test        No      ../config/test

---

安全な確認ワークフロー

読み取り専用の確認には config:get と config:status を使用するか、cim／cex に --no フラグを付けて自動確認を防いでください。

設定値を取得

# Get full config object
terminus drush {site}.{env} -- config:get config.name

# Get as YAML
terminus drush {site}.{env} -- config:get config.name --format=yaml

# Extract specific values
terminus drush {site}.{env} -- config:get config.name 2>&1 | grep "setting_name"

ローカルとリモートを比較

# View diffs without importing (SAFE with --no)
terminus drush {site}.{env} -- cim --no --diff

# Get remote and compare manually
terminus drush {site}.{env} -- config:get config.name --format=yaml > /tmp/remote.yml
diff -u config/default/config.name.yml /tmp/remote.yml

重要：terminus では常に --no フラグを使用してください。これを付けない場合、コマンドは自動的に確認します。

変更を適用

推奨：YAML を手動で作成しないでください。サイト上で変更を行い（UI、単純な設定には config:set、設定エンティティにはエンティティ API を使用）、そのオブジェクトだけをエクスポートするか、あるいは環境の値を取得する場合は、その環境の config:get の出力を1つのオブジェクトに書き込みます（surgical-config.md を参照）：

ddev drush config:get config.name --format=yaml > config/default/config.name.yml
# or: terminus drush {site}.{env} -- config:get config.name --format=yaml > config/default/config.name.yml
git diff config/default/config.name.yml
git add config/default/config.name.yml
git commit -m "Update config from {env}"

---

上流環境から設定を同期

簡易的な方法

単一の設定オブジェクト：

terminus drush {site}.{env} -- config:get config.name --format=yaml > config/default/config.name.yml
git add config/default/config.name.yml && git commit -m "Update from {env}"
# Then apply that one file locally with a single-file partial import (see above)

rsync による設定全体の同期：

注意： リモートで cex を実行すると、その環境で差異のある設定オブジェクトがすべて書き込まれ、ローカルで cim を実行すると、差異のある設定がすべてインポート（および削除）されます。共有環境やリモート環境に対する一括エクスポート／インポートを、軽い手順として実行しないでください。上記の単一設定の方法を優先し、インポート前に差分全体を確認してください。surgical-config.md を参照してください。

terminus drush {site}.{env} -- cex
terminus rsync {site}.{env}:code/config/default /tmp/remote
diff -r config/default /tmp/remote  # Review
cp /tmp/remote/*.yml config/default/
git add config/default/ && git commit -m "Sync from {env}"
ddev drush cim

データベースのプル経由（DDEV + Pantheon）。これは意図的なフルエクスポートです。まず自分の作業をコミットし、prod-config-merge.md の説明に従って、エクスポートによって削除された自分のファイルを復元してください：

ddev pull pantheon --environment={env}  # Warning: Overwrites local DB!
ddev drush cex
git diff config/ && git add config/ && git commit -m "Config from {env}"

詳しいワークフローについては、examples.md を参照してください。

ベストプラクティス：差分を確認し、個別にコミットし、ローカルでテストし、ソースを記録し、環境固有の設定の同期は避けてください。

---

詳細なリファレンス

包括的な技術ドキュメントについては、以下を参照してください。

• config-split-deep-dive.md - Config Split 2.0、パッチファイル、エクスポート／インポートのプロセス、依存関係の処理に関する完全な技術リファレンス
• surgical-config.md - エージェント向けの一度に1つの設定だけをエクスポート／設定／削除する方法、core.extension.yml の例外、dependencies を削除する未加工の設定書き込み、組み込み（PHP で計算される）設定、config:status によるインポートの確認
• examples.md - 実践的な例とワークフロー

リファレンス

ファイル	参照するタイミング
references/surgical-config.md	エージェントが設定を変更する前：名前を指定した設定オブジェクトを1つだけエクスポート、設定、削除する方法、core.extension.yml の例外、dependencies を削除する未加工の設定書き込み、組み込み（PHP で計算される）設定、config:status によるインポートの確認、設定のみの変更のコミット
references/prod-config-merge.md	ローカル機能設定を含むブランチに本番環境の設定変更をマージする場合（本番 DB を取得し、エクスポートして、削除または上書きしたファイルを復元する）
references/config-splits.md	スプリットを使用するかどうかを決める場合、または完全スプリットと部分スプリットのどちらかを選ぶ場合
references/config-split-deep-dive.md	Config Split 2.0 の内部仕様が必要な場合：パッチファイル、ファイル名、エクスポート／インポートのプロセス、依存関係の処理、ローカルとリモートの Solr の詳細例（自動生成インデックスパッチを含む完全スプリットのサーバーなど）
references/examples.md	詳細な例が必要な場合：開発環境から1つの設定を同期する、Search API 設定を同期する、環境を比較する、スプリット定義を更新する

設定ステータスの確認

インポートされる設定を確認します（読み取り専用）。

# Local environment
ddev drush config:status

# Remote environment
terminus drush {site}.{env} -- config:status

ベストプラクティス

1. インポート前に必ず確認する - config:get と --no --diff フラグを使用します
2. サイトで設定を変更し、オブジェクトを1つエクスポートする - UI／config:set／エンティティ API を使い、その後 config:get --format=yaml を実行します。エクスポートした YAML を手作業で編集するのは例外的な方法です（依存関係の計算が省略されます）。手作業で編集した場合は、そのファイルだけをインポートし、config:status で確認します
3. コミットごとに設定タイプを1つにする - 履歴を整理するため、変更内容を分けます
4. 明確なコミットメッセージを付ける - 変更元の環境を記載します
5. 一時ファイルを削除する - 一時的な YAML ファイルを削除します
6. コミット前に確認する - git diff の出力を必ず確認します
7. まずローカルでテストする - デプロイ前にインポートしてテストします
8. 設定スプリットを使用する - 環境固有の設定を分離して管理します

---

トラブルシューティング

作業ディレクトリから設定ファイルが削除された

git status でファイルが削除済みと表示される場合：

git checkout HEAD -- config/default/*.yml

drush コマンドが予期せず実行された場合に発生することがあります。

スプリットが有効にならない

スプリットのステータスを確認します。

ddev drush config-split:status

手動で有効にします。

ddev drush config-split:activate {split-name}
# Save the activation state: export only the split definition
ddev drush config:get config_split.config_split.{split-name} --format=yaml > config/default/config_split.config_split.{split-name}.yml

エクスポート時に config/default から設定が削除される

よくある問題：drush cex を実行すると、search_api.server.my_search_server などの設定が config/default/ から削除されます。

根本原因（99% のケース）：設定が partial_list ではなく complete_list に含まれています。

完全スプリット = 設定が config/default/ から削除され、スプリットディレクトリに完全に移動されます 部分スプリット = 設定は config/default/ に残り、差分のみがパッチとして適用されます

診断：

# Check if config is in complete_list (will be deleted from config/default)
grep -A10 "complete_list:" config/default/config_split.config_split.local.yml

# Check if config is in partial_list (will stay in config/default)
grep -A10 "partial_list:" config/default/config_split.config_split.local.yml

解決策：complete_list から partial_list に移動します

# Edit the split definition
# Move: search_api.server.my_search_server
# FROM: complete_list
# TO: partial_list

ddev drush cex  # Re-export
# Check that config/default/search_api.server.my_search_server.yml exists
# Check that config/local/config_split.patch.search_api.server.my_search_server.yml exists

詳しい技術的な説明については、config-split-deep-dive.md を参照してください。

設定をインポートできない

よくある問題：

• 依存関係が不足しています：まず必要なモジュールをインストールします
• サイト UUID の不一致（「ソースストレージのサイト UUID がターゲットストレージと一致しません」）：データベースがエクスポート済みの設定とは別にインストールされています。drush site:install --existing-config を使って設定からインストールするか、drush config:set system.site uuid <uuid> を使って system.site:uuid をエクスポート済みの値に設定します
• 設定エンティティの UUID が異なります：エラーではありませんが、インポート時にそのエンティティが削除されて再作成されます（フィールドストレージの場合、それに関連するデータも削除されます）。drupal-config-reconcile スキルを参照してください

Drush 13 の config:import には --skip-config オプションがありません。インポート対象から特定のオブジェクトを除外するには、config_ignore モジュールまたは単一ファイルの部分インポート（上記）を使用します。

関連コマンド

読み取り専用：config:get、config:status エクスポート：config:export（エイリアス：cex） インポート：config:import（エイリアス：cim）- プレビューするには --no --diff を指定します スプリット：config-split:status、csex、csim、config-split:activate