トラブルシューティング
Kashiwazaki SEO Related Posts の使用中に発生しうる問題と対処法、動作要件、技術仕様について解説します。
よくある問題と対処法
関連記事が表示されない
| 考えられる原因 | 対処法 |
|---|---|
| プラグインが有効化されていない | 管理画面の「プラグイン」一覧で、本プラグインが有効になっていることを確認してください。 |
| OpenAI APIキーが未設定 | 設定画面でOpenAI APIキーが正しく入力されているか確認してください。 |
| AI分析がまだ実行されていない | 投稿に対するAI類似度分析が未実行の場合、関連記事は表示されません。設定画面から分析を実行してください。 |
| 投稿個別設定で非表示になっている | 投稿編集画面のメタボックスで「関連記事を非表示」が有効になっていないか確認してください。 |
| キャッシュプラグインが古い出力を表示している | キャッシュプラグインのキャッシュをクリアしてください。 |
OpenAI APIエラーが発生する
| 考えられる原因 | 対処法 |
|---|---|
| APIキーが無効または期限切れ | OpenAI Platform でAPIキーのステータスを確認してください。 |
| APIの利用上限に達している | OpenAIアカウントの利用上限を確認してください。必要に応じて上限を引き上げてください。 |
| サーバーの外部通信が制限されている | ホスティング環境で wp_remote_post による外部HTTPリクエストが許可されているか確認してください。 |
| OpenAIサービスが一時的にダウンしている | OpenAI Status でサービス状況を確認し、復旧後に再試行してください。 |
関連記事のスタイルが崩れる
| 考えられる原因 | 対処法 |
|---|---|
| テーマのCSSとの競合 | ブラウザの開発者ツールで、テーマのCSSが関連記事のスタイルを上書きしていないか確認してください。 |
| 他のプラグインのCSS/JSとの競合 | 他のプラグインを一時的に無効にして、競合の原因を特定してください。 |
| スライダーが正しく動作しない | JavaScriptエラーがないか確認してください。jQueryの競合が原因の場合があります。 |
AI分析の結果が不適切
| 考えられる原因 | 対処法 |
|---|---|
| 投稿数が少なすぎる | 関連記事の精度は投稿数に依存します。十分な数の投稿がサイトに存在することを確認してください。 |
| キャッシュが古い | 設定画面の「キャッシュクリア」ボタンでキャッシュを削除し、AI分析を再実行してください。 |
| 特定の投稿で不適切な結果 | 投稿個別設定のメタボックスから、手動で関連記事を選択してAI提案を上書きしてください。 |
ヒント
問題が解決しない場合は、一度プラグインを無効化してから再有効化してみてください。設定値はデータベースに保持されるため、再有効化後も設定は維持されます。
PHP 8.1 以降の互換性
本プラグインは PHP 8.1 以降での運用を想定し、以下の対策を v1.0.2 で実施しています。
解消した Deprecated 警告
| 警告内容 | v1.0.2 での対応 |
|---|---|
strpos(): Passing null to parameter #1 ($haystack)str_replace(): Passing null to parameter #3 ($subject) |
投稿タイプ別設定ページの登録時に親スラッグ null を空文字列 '' に変更。WordPress 公式パターン（Yoast SEO PR #19125、Jetpack issue #28108、Google Site Kit issue #5998）と同等の修正方式。 |
strip_tags(): Passing null to parameter #1 ($string) (admin-header.php:41) |
load-{$hook_suffix} アクションでページタイトルを $GLOBALS['title'] にセットし、admin ヘッダー読み込み時の strip_tags(null) を回避。 |
Undefined array key 'nonce' / 'post_id' / 'max_posts' (AJAX 経路) |
AJAX エンドポイント 4 箇所の nonce 検証および 5 箇所の $_POST 直接アクセスに isset() ガードと wp_unslash() を追加。 |
補足
WP_DEBUG および WP_DEBUG_LOG を有効化している環境で wp-content/debug.log に上記警告が記録されていた場合、v1.0.2 へのアップデートで解消します。アップデート後にも同種の警告が残る場合は、別プラグインまたはテーマが原因の可能性があります。
動作要件
| 項目 | 要件 |
|---|---|
| WordPress | 5.0 以上 |
| PHP | 7.4 以上 |
| OpenAI APIキー | AI関連記事機能を使用する場合は必須 |
| 対応ブラウザ | Chrome、Firefox、Safari、Edge（最新版） |
技術仕様
- データ保存: wp_options (kashiwazaki_seo_related_posts_options), post_meta, transient cache
- カスタムテーブル: なし
- 外部通信: OpenAI API (wp_remote_post)
- Cronイベント: なし
- メール送信: なし
- フロントエンド: CSS 24KB、JS 7.4KB
アーキテクチャ
Kashiwazaki SEO Related Posts は以下のコンポーネントで構成されています。
フロントエンド
- CSS（24KB）でリスト・グリッド・スライダーの3表示形式と6カラーテーマを実装
- JavaScript（7.4KB）でスライダー動作とAJAX処理を実行
- JSON-LDの出力は行わない
バックエンド
- グローバル設定は
wp_optionsテーブルにkashiwazaki_seo_related_posts_optionsキーで保存 - 投稿個別の関連記事データは
post_metaに保存 - AI分析結果は Transient API でキャッシュ
- OpenAI APIとの通信は
wp_remote_postで実行 - 6つのAJAXハンドラーで管理画面の非同期操作を実現
AI分析フロー
1
管理画面またはAJAXリクエストからAI分析が開始されます。
2
投稿のタイトル・本文・カテゴリ情報を収集し、OpenAI APIに wp_remote_post で送信します。
3
GPTが記事間の類似度をスコアリングし、関連度の高い記事を特定します。
4
分析結果をTransientキャッシュに保存し、次回以降のアクセスではキャッシュからデータを返します。
5
フロントエンドで設定に基づいた表示形式・カラーテーマで関連記事を描画します。
補足
カスタムテーブルやCronイベントは使用しないため、プラグインの削除時にデータベースに不要なデータが残ることはありません。wp_options の設定値、post_meta、Transient キャッシュのみが削除対象です。