はじめに
WordPressの投稿エディタにYouTubeやTwitterのURLをそのまま貼り付けると、自動的に埋め込みプレビューに変換される「oEmbed」機能があります。この機能が動作しない場合、複数の原因が考えられます。
症状・原因
- URLがリンクのままで埋め込みに変換されない
- 埋め込みが表示されるが画面が真っ白になる
- 「このコンテンツは埋め込めません」と表示される
主な原因：
1. CSP（Content Security Policy）のframe-srcが未設定
2. oEmbedエンドポイントへのリクエストがタイムアウト
3. フィルターでoEmbedが無効化されている
4. X（旧Twitter）の埋め込みAPIの仕様変更
解決手順
ステップ1：oEmbedが有効か確認
// functions.php に誤ってこの記述がないか確認
// これがあるとoEmbedが無効になる
remove_filter('the_content', [WP_Embed, 'autoembed'], 8);
// ↑ この行がある場合は削除するステップ2：CSPのframe-srcを設定
// functions.php
add_action('send_headers', function() {
$csp = implode('; ', [
"default-src 'self'",
"frame-src 'self' https://www.youtube.com https://player.vimeo.com"
. " https://twitter.com https://www.instagram.com",
"script-src 'self' 'unsafe-inline' https://platform.twitter.com",
]);
header("Content-Security-Policy: $csp");
});ステップ3：特定サービスのoEmbed URLを手動登録
// プロバイダーを手動登録（X/旧Twitterなど仕様変更があったサービス向け）
add_filter('oembed_providers', function($providers) {
// Xの新エンドポイントに更新
$providers['#https?://twitter\.com/.*#i'] = [
'https://publish.twitter.com/oembed',
true,
];
return $providers;
});ステップ4：oEmbedキャッシュをクリア
oEmbedの結果はデータベースの post_meta にキャッシュされます。古いキャッシュが残っていると更新されません。
# oEmbedキャッシュを一括削除
wp post meta delete --all --meta-key=_oembed_*
wp post meta delete --all --meta-key=_oembed_time_*ステップ5：ブロックエディタで「埋め込み」ブロックを使う
URLを直接本文に貼るのではなく、ブロックエディタの「埋め込み」ブロックを追加し、URLを入力する方法が確実です。
ブロック追加 → 「埋め込み」→ サービスを選択（YouTube・Twitter等）→ URLを入力ステップ6：タイムアウトを延長
oEmbedリクエストのタイムアウトが短すぎる場合：
add_filter('http_request_timeout', function($timeout) {
return 30; // デフォルト5秒を30秒に延長
});注意事項
- X（旧Twitter）の埋め込みAPIは2023年以降に仕様変更があり、無料プランでは制限がある場合があります
- Instagramの埋め込みはFacebook Developer登録と審査が必要な場合があります
wp_oembed_get()でテストすると埋め込みHTMLを取得できるか確認できます
まとめ
oEmbedが動作しない最多原因はCSPのframe-src未設定とoEmbedキャッシュの問題です。CSPにサービスのドメインを追加し、wp post meta delete でキャッシュをクリアすれば多くのケースで解決します。