@wordpress/scripts や @wordpress/create-block で作った自作ブロックが、npm run build の失敗や、ビルド後にエディターへ表示されないといった理由で使えなくなることがあります。原因は「ビルドそのものが失敗している」「ビルドは成功したがWordPressが読み込めていない」「読み込めたが保存済みの内容と合わない」の3段階に分けると見つけやすくなります。この記事では、それぞれの段階でエラーの読み方と、可能性の高い順の確認・修正方法を説明します。
どの段階で止まっているかを確認する
最初に、症状がどれに当てはまるかを確認します。
- **ターミナルで
npm run buildがエラーで終わる**: ビルドの段階です。「段階1」へ進みます。 - ビルドは成功するが、ブロックの挿入メニューに出てこない、または「お使いのサイトはこのブロックに対応していません」と表示される: 登録の段階です。「段階2」へ進みます。
- ブロックは出るが、既存の投稿で「想定されていないか無効なコンテンツが含まれています」と表示される: 保存内容の検証の段階です。「段階3」へ進みます。
エディターでの問題は、ブラウザのデベロッパーツールのコンソールにヒントが出ることが多いので、開いた状態で再読み込みしてください。
段階1：ビルドが失敗する
エラーメッセージは最初の1件を読む
webpackのエラーは、1つの原因から連鎖して大量に表示されることがあります。末尾ではなく、最初に出た ERROR in の行と、その直後に示されるファイル名・行番号を確認します。
Node.jsのバージョンが合っていない
もっとも多い原因です。@wordpress/scripts は対応するNode.jsのバージョンを決めており、古すぎても新しすぎてもビルドが失敗することがあります。対応範囲はパッケージの package.json にある engines の項目で確認できます。
node -v
npm -v
# 使っている @wordpress/scripts の対応バージョンを確認
npm view @wordpress/scripts enginesチームや複数の環境で作業する場合は、プロジェクト直下に .nvmrc を置き、nvmなどのバージョン管理ツールで同じNode.jsを使うようにすると再発を防げます。
依存パッケージの不整合
Node.jsを切り替えたあとや、別のPCでリポジトリを取得したあとに起きやすい問題です。node_modules を作り直します。
rm -rf node_modules
npm ci
npm run buildnpm ci は package-lock.json のとおりに依存関係を入れ直すコマンドです。lockファイルが無い場合は npm install を使います。
「Module not found」と表示される
import しているファイルのパスの誤り、またはパッケージの入れ忘れです。@wordpress/block-editor などのWordPressパッケージは、ビルド時に外部依存として扱われ、実行時はWordPress本体が提供するものが使われます。それでもエディターでの補完や型のために package.json へ追加しておくのが一般的です。自作ファイルの場合は、拡張子や大文字・小文字の違い（WindowsとLinuxで挙動が変わります）を確認してください。
JSXやSCSSの構文エラー
エラー行に SyntaxError とあれば、閉じタグの漏れや括弧の対応の誤りです。SCSSのエラーは、変数や @use のパスが正しいかを確認します。開発中は npm run start で監視ビルドを動かしておくと、保存のたびにエラーを確認できます。
段階2：ビルドは成功したのにブロックが出ない
PHPの登録先が build フォルダを指しているか
ブロックは、PHP側で block.json を読み込んで登録します。指定するのはソースの src ではなく、ビルド後のフォルダです。
<?php
/**
* Plugin Name: My Blocks
*/
add_action( 'init', function () {
register_block_type( __DIR__ . '/build/my-block' );
} );create-block のテンプレートは、バージョンによって build/ 直下に1つのブロックを出力する形と、build/ブロック名/ に分ける形があります。実際に build フォルダの中を開き、block.json がどこにあるかを確かめて、そのフォルダを指定してください。
block.json の参照先とアセットファイル
block.json の editorScript には "file:./index.js" のようにビルド後のファイルを指定します。あわせて、ビルド時に生成される index.asset.php が同じフォルダにあるかを確認します。このファイルにはスクリプトの依存関係とバージョンが入っており、無いと依存関係が正しく読み込まれず、コンソールに wp.blocks などが未定義というエラーが出ることがあります。
動的ブロックで "render": "file:./render.php" を使っている場合は、render.php が build にコピーされているかも確認します。wp-scripts build にはPHPファイルをコピーするオプション（--webpack-copy-php）があり、テンプレートの package.json に含まれているかどうかはバージョンによって異なります。
ブロック名の不一致
JavaScript側の registerBlockType() に渡す名前と、block.json の name が一致していないと登録に失敗します。block.json を読み込んで名前を渡す形にしておくと、食い違いが起きません。
import { registerBlockType } from '@wordpress/blocks';
import metadata from './block.json';
import Edit from './edit';
import save from './save';
registerBlockType( metadata.name, {
edit: Edit,
save,
} );コンソールに「Block "my-plugin/my-block" is already registered」と出る場合は、同じブロックを二重に登録しています。PHPとJavaScriptの両方で別々の設定を登録していないか、古いビルドのファイルが別の場所から読み込まれていないかを確認します。
本番に build フォルダが配置されていない
ローカルでは動くのに本番で使えない場合に多い原因です。build フォルダを .gitignore に入れていると、Gitでデプロイしたときに本番へ届きません。本番でビルドを実行する仕組みを用意するか、配布用のZIPにビルド済みファイルを含めます。wp-scripts plugin-zip を使うと配布用のZIPを作れます。
段階3：「想定されていないか無効なコンテンツ」と表示される
ブロックエディターは、投稿を開くときに save 関数の出力と保存済みのHTMLを比較します。ビルドし直して save の出力（クラス名、要素の構造、属性の出し方）が変わると、過去に保存したブロックが一致しなくなり、この警告が出ます。
対処は次のどちらかです。
- **
deprecatedを定義する**: 変更前のsave関数と属性をregisterBlockType()のdeprecatedに残しておくと、エディターが古い形式を認識し、新しい形式へ移行できます。 - 動的ブロックにする: 表示をPHPの
render.phpで出力し、saveはnullを返す形にすると、マークアップを変えても保存済みデータと衝突しません。表示を頻繁に変えるブロックに向いています。
警告の画面で「ブロックのリカバリーを試行」を選ぶと、その投稿だけは新しい形式で保存し直されますが、投稿が多い場合は deprecated で対応するのが現実的です（ボタンの表記はバージョンで変わることがあります）。
作業時の注意
- 本番サイトでビルドや差し替えを試さず、ローカルかステージング環境で確認してから反映する
- 既存の投稿に影響する
saveの変更は、データベースのバックアップを取ってから行う @wordpress/scriptsを大きく更新すると、設定ファイルやNode.jsの要件が変わることがあるため、変更履歴を確認してから上げる
まとめ
- まず「ビルドの失敗」「登録の失敗」「保存内容の検証エラー」のどれかを見極める
- ビルドの失敗は、Node.jsのバージョン、依存パッケージ、最初のエラーメッセージの順に確認する
- ブロックが出ないときは、
register_block_type()が build 内のblock.jsonを指しているか、index.asset.phpがあるか、名前が一致しているかを確認する saveの出力を変えたらdeprecatedを用意するか、動的ブロックに切り替える
ツールの既定の設定や画面の表記はバージョンにより変わります（2026年10月現在の構成で説明しています）。