トラブルシューティング

よくあるトラブルと解決策、動作要件、技術仕様をまとめています。表示されない・古い動画が出る・API エラーが出る等の場合はまずこのページを確認してください。

よくある問題と解決策

1. 何も表示されない / 「YouTube Data API キーが設定されていません」

原因: API キーが未保存、または空文字。訪問者には何も表示されず、編集権限を持つユーザー (edit_posts 以上) にのみエラーメッセージが見えます。

1

管理画面「Kashiwazaki SEO TubeList Shortcode」→「設定」タブを開き、API キー欄に AIzaSy... で始まるキーを入力して「変更を保存」

2

「API キーをテスト」ボタンで疎通確認 (成功すると「API 接続に成功しました」と表示)

2. 「チャンネルが見つかりませんでした」

原因: channel 属性に指定したチャンネル ID が存在しない、または形式不正。

正しいチャンネル ID は UC で始まる 24 文字前後の文字列です。YouTube のチャンネルページで URL が /channel/UCxxxxxxxxxxxxxxxxxxxx 形式の場合は最後の部分を使ってください。@ハンドル形式の URL の場合は handle="@..." 属性で指定するのが確実です。

3. 「プレイリスト ID の形式が不正です」

原因: playlist 属性に指定した ID が、許可されたプレフィックス (PL / UU / FL / RD / OL / LL) で始まっていない。

YouTube のプレイリスト URL https://www.youtube.com/playlist?list=PLxxxxxxxx の list= 以降をそのまま指定してください。

4. 動画が更新されない (新しい動画がアップされても表示が古いまま)

原因: transient キャッシュが保持されている。デフォルトは 3600 秒 (1 時間) で自動更新されます。

1

管理画面の「設定」タブ下部「キャッシュ管理」→「キャッシュをすべてクリア」をクリック

キャッシュクリア完了の通知
図: キャッシュクリア成功時の admin_notice

キャッシュ秒数を短くしたい場合はショートコード属性 cache で個別指定できます (例: cache="600" で 10 分)。cache="0" でキャッシュを完全に無効化できますが、表示のたびに API クォータを消費するため非推奨です。

5. 「YouTube API リクエストに失敗しました」 / quotaExceeded

原因: YouTube Data API v3 の 1 日あたりクォータ (デフォルト 10,000 ユニット) を消費し切った。

6. リンク文字色がオレンジで下線になる (テーマと衝突)

原因: テーマの a 要素 CSS が本プラグインのスタイルを上書き。本プラグインは specificity を高めたセレクタで対応していますが、テーマが !important を多用している場合に発生します。

子テーマの追加 CSS に以下を加えてください。

.kstls-tubelist a.kstls-link,
.kstls-tubelist a.kstls-link:link,
.kstls-tubelist a.kstls-link:visited {
    color: inherit !important;
    text-decoration: none !important;
}

7. ページネーション・カルーセル・もっと見るが動かない

原因: JavaScript が読み込まれていない、または他プラグイン / テーマの JS とコンフリクト。

8. CDN (Cloudflare 等) で古い CSS / JS が返る

原因: CDN 側で長期キャッシュされている。

本プラグインは filemtime() を使った自動 cache busting に対応しています (URL に ?ver=1.0.1.<数値> が付く)。プラグインのファイルを更新すると filemtime() が変わり、CDN は新しい URL として再取得します。

それでも更新されない場合は、CDN 側で手動 purge してください。

9. ハンドル (@xxx) を指定しても動画が出ない

原因: handle 属性に指定したハンドルが YouTube で実在しない、または別のチャンネル設定。

動作要件

項目要件
WordPress5.0 以上 (Tested up to 6.7)
PHP7.2 以上 (推奨: 8.0+)
PHP 拡張mbstring (description 文字数カウント用、未インストール時は strlen フォールバック)
外部通信https://www.googleapis.com/ への HTTPS 通信 (timeout 15 秒)
API キーYouTube Data API v3 のキー (Google Cloud Console)
ブラウザChrome / Edge / Firefox / Safari の最新 2 バージョン (CSS :has() フォールバック JS あり)

技術仕様

アンインストール時の挙動

プラグインを WordPress 管理画面から「削除」した場合、uninstall.php が自動実行されて以下を削除します。

単に「無効化」した場合は transient キャッシュのみ削除され、オプション (API キー等) は保持されます。後で再有効化したときに設定をやり直さなくて済みます。

サポート

本マニュアルで解決しない場合や、機能追加のご相談は作者まで。