ACFのフィールドグループをJSONでエクスポート・インポートする方法｜ローカルJSONとWP-CLI

Advanced Custom Fields（ACF）のフィールドグループは、設定項目が多く、別のサイトで手作業で作り直すと抜けや食い違いが出やすくなります。ACFには、フィールドグループの設定をJSONファイルとして書き出し、別のサイトに読み込む機能があります。この記事では、管理画面での書き出しと読み込み、テーマに置いたJSONと同期する「ローカルJSON」、WP-CLIでの操作を順に説明します。画面の表記は2026年10月時点のACF 6系を前提にしています。

3つの方法の使い分け

どの方法でも、JSONに入るのはフィールドグループの「設定」だけです。投稿ごとに入力した値はデータベースの投稿メタなどに保存されているので、JSONには含まれません。値も移す場合は、データベースの移行やWordPressのエクスポート機能を別に使います。

ツール画面でJSONを書き出す

1. 管理画面のACFのメニューから「ツール」（英語表示では Tools）を開く
2. エクスポートの欄で、書き出すフィールドグループにチェックを入れる
3. 「Export As JSON」をクリックする

ボタン名はACFの英語表記で示しています。日本語表示の管理画面では訳語で表示されます。選んだフィールドグループが1つの .json ファイルとしてダウンロードされます。ACFのバージョンによっては、同じ画面で投稿タイプ、タクソノミー、オプションページ（ACF PRO）も選べます。

同じ画面の「Generate PHP」を使うと、JSONの代わりにフィールドグループを登録するPHPコードが表示されます。このコードをテーマや自作プラグインに貼ると、データベースに保存しなくてもフィールドグループが読み込まれます。ただし、PHPで登録したフィールドグループは管理画面から編集できないので、設定を固定したい場合に向いています。

ツール画面でJSONを読み込む

移行先のサイトで次の操作をします。

1. ACFの「ツール」を開く
2. インポートの欄で、書き出した .json ファイルを選ぶ
3. 「Import JSON」をクリックする

フィールドグループは group_ で始まるキーで識別されます。移行先に同じキーのフィールドグループがあると、読み込んだ内容で上書きされます。移行先で独自に変更していた場合に備えて、読み込む前に移行先のデータベースをバックアップしておきます。

wp db export before-acf-import.sql

読み込み後は、フィールドグループの一覧で件数と「位置」の条件（どの投稿タイプやテンプレートに表示するか）を確認し、投稿の編集画面でフィールドが表示されるかを見ます。

ローカルJSONで設定をファイル管理する

ローカルJSONは、フィールドグループを保存するたびに、その設定をテーマ内のJSONファイルにも書き出す機能です。ファイルをGitで管理したり、別の環境へ配置したりできます。ACFは起動時にこのファイルから設定を読み込むため、データベースへの問い合わせも減ります。

有効にする手順

有効にするには、使っているテーマ（子テーマを使っている場合は子テーマ）に acf-json というフォルダーを作り、Webサーバーが書き込めるようにします。

cd wp-content/themes/your-child-theme
mkdir acf-json
# PHPを実行しているユーザーが書き込めるようにする（例: www-data）
sudo chown www-data:www-data acf-json
chmod 755 acf-json

フォルダーを作ったあと、管理画面で各フィールドグループを開いて「更新」すると、group_xxxxxxxx.json のように、キーをファイル名にしたJSONが作られます。既存のフィールドグループは、更新するまでファイルになりません。ACFの公式ドキュメントでは、ディレクトリの中身を一覧表示されないよう、このフォルダーに空の index.php を置くことを勧めています。

別の環境で同期する

acf-json フォルダーのファイルを別の環境に配置すると、ACFのフィールドグループ一覧の上に、同期用のタブ（英語表示では Sync available）が表示されます。同期の対象になるのは、データベースにまだないフィールドグループと、JSONの modified の値がデータベースより新しいフィールドグループです。一覧で対象を選んで同期すると、データベースに反映されます。

JSONファイルを手で編集した場合、modified の値を更新しないと、同期の対象として扱われません。設定の変更は、なるべく管理画面で行い、書き出されたファイルを配布する流れにします。

保存先と読み込み先を変える

テーマではなく自作プラグインにJSONを置きたい場合は、フィルターで保存先と読み込み先を変えます。次の例は、プラグインのフォルダー内の acf-json を使う場合です。

<?php
/**
 * Plugin Name: My ACF JSON
 */

// 保存先を変更する
add_filter( 'acf/settings/save_json', function ( $path ) {
	return plugin_dir_path( __FILE__ ) . 'acf-json';
} );

// 読み込み先に追加する
add_filter( 'acf/settings/load_json', function ( $paths ) {
	$paths[] = plugin_dir_path( __FILE__ ) . 'acf-json';
	return $paths;
} );

保存先だけを変えて読み込み先に加えないと、ACFは保存したJSONを読み込みません。2つのフィルターは組にして使います。ACF 6.2以降では、acf/json/save_paths フィルターでフィールドグループごとに保存先を分けることもできます。

WP-CLIで書き出す・読み込む

ACFの公式ドキュメントによると、ACF 6.8以降には wp acf json コマンドが含まれています（WP-CLI 2.0以降が必要）。

# ACFのバージョンを確認（無料版のスラッグは advanced-custom-fields）
wp plugin get advanced-custom-fields --field=version

# 同期が必要な項目の状態を表示
wp acf json status

# ローカルJSONの変更をデータベースに同期
wp acf json sync

# すべての項目をディレクトリに書き出す
wp acf json export --dir=./exports/

# JSONファイルを読み込む
wp acf json import ./acf-export.json

ACF PROを使っている場合、プラグインのスラッグは advanced-custom-fields-pro です。書き出す対象を絞る引数などは、使っているバージョンの wp help acf json export で確認してください。

古い解説記事には wp acf export のようなコマンドが出てくることがありますが、これはACF本体ではなく、別途配布されていた拡張パッケージのコマンドです。ACF 6.8より前のバージョンには wp acf json コマンドはありません。

移行でつまずきやすい点

• フィールド名を変えると値が見えなくなる: 値は投稿メタにフィールド名（name）で保存されています。移行のついでにフィールド名を変えると、既存の値と結び付かなくなります。
• キーを変えない: フィールドグループとフィールドのキー（group_…、field_…）は、同期と上書きの判定に使われます。JSONを手で書き換えるときもキーは変えません。
• 位置の条件が移行先に合っているか: 特定の固定ページやカテゴリーを条件にしている場合、移行先ではIDが違うことがあります。読み込み後に条件を見直します。
• ACFのバージョンをそろえる: 移行元より古いACFで読み込むと、新しいバージョンで追加された設定が扱えないことがあります。

まとめ

• JSONに入るのはフィールドグループの設定だけで、投稿ごとの値は含まれない
• 一度だけ移すなら、ACFの「ツール」で「Export As JSON」と「Import JSON」を使う。同じキーのグループは上書きされるので、移行先のバックアップを先に取る
• 継続して同期するなら、テーマに acf-json フォルダーを作るローカルJSONを使い、一覧の同期用タブから反映する
• 保存先を変えるときは acf/settings/save_json と acf/settings/load_json を組にして使う
• ACF 6.8以降は wp acf json status / sync / export / import をWP-CLIで使える

関連記事:

• ACF（Advanced Custom Fields）の使い方
• ACFのフィールドが保存されないときの対処法
• WordPressの子テーマを作る方法