sijad/astro-wordpress

astro-wordpress は何をしますか？

静的なAstroテンプレートを、astro-wordpressを使用してWordPressテーマに変換します。src/pages/*.php.astroにあるページが実際のWordPressテンプレートファイル（index.php、page-template-*.phpなど）にコンパイルされ、npm run devは実際のローカルWordPressインスタンスをプロキシするため、テーマは常にライブでプレビューされます。

これはアダプターのREADMEを言い換えたものではなく、検証済みのレシピです。以下の手順は実際の静的なAstroテンプレートに適用され、エンドツーエンドで確認されています。開発サーバーがWordPressを介してライブプロキシされ、npm run buildが実際にアクティベート可能なテーマを生成し、wp theme activateが成功します。

前提条件

• HTTP経由でアクセス可能なローカルWordPressインストール。2つの検証済みオプション：
  • Docker Compose（推奨 — ローカルにPHP/MySQL/wp-cliは不要で、wp-cliがホストにインストールされていない可能性が高い）。手順0を参照。
  • すでに実行中のローカルWordPressインストール（devProxyTargetで指定する任意のPHPサーバー+MySQL/MariaDB）。このスキルはどちらの場合でもAstro側のみを変換します。
• Astroプロジェクト用のNode/npm。
• wp-cliはこのスキル全体を通してオプションです。以下のすべてのwp-cliコマンドには、wp-cliを使わない代替手段（ブラウザ/curlフォーム送信、またはDocker化されたwp-cliサイドカー）があります。必須要件として追加しないでください。

0. （Dockerオプション）Docker ComposeでWordPressを起動する

この正確なcompose.yaml（astro-wordpressスターターから）はそのままで動作します — 実際に実行して確認済み：

services:
  wordpress:
    image: wordpress
    restart: always
    ports:
      - 8088:80
    environment:
      WORDPRESS_DB_HOST: db
      WORDPRESS_DB_USER: exampleuser
      WORDPRESS_DB_PASSWORD: examplepass
      WORDPRESS_DB_NAME: exampledb
    volumes:
      - ./wp:/var/www/html
      - ./public/:/var/www/html/public

  db:
    image: mysql:8.0
    restart: always
    environment:
      MYSQL_DATABASE: exampledb
      MYSQL_USER: exampleuser
      MYSQL_PASSWORD: examplepass
      MYSQL_RANDOM_ROOT_PASSWORD: "1"
    volumes:
      - db:/var/lib/mysql

volumes:
  db:

docker compose up -d

wordpressイメージにはデフォルトでwp-cliは含まれていません。インストールとその他すべての操作は、ブラウザ（http://localhost:8088）を介して、または同じネットワーク+ボリュームを共有する使い捨てのDocker化されたwp-cliコンテナを使用して行います（「確認/落とし穴」を参照 — 以下の手順でwp ...と表示され、ローカルにwp-cliがインストールされていない場合に使用するパターンです）：

docker run --rm --network container:<wordpress-container-name> \
  --volumes-from <wordpress-container-name> -w /var/www/html \
  -e WORDPRESS_DB_HOST=db -e WORDPRESS_DB_USER=exampleuser \
  -e WORDPRESS_DB_PASSWORD=examplepass -e WORDPRESS_DB_NAME=exampledb \
  wordpress:cli <wp-cli-command>

（-e変数はwordpressサービスのenvと一致している必要があります。CLIコンテナは同じwp-config.phpを読み取り、getenv()を介して変数を解決しますが、他のコンテナの環境を継承しません。）

手順

1. アダプターをインストールする

npm install astro-wordpress

（後述のpassthroughImageServiceはAstroコアに同梱されています — 追加のパッケージは不要です。）

2. astro.config.mjsを設定する

ベアメタルWordPress（AstroとWordPressが同じホスト上、コンテナ境界なし）：

// @ts-check
import { defineConfig, fontProviders, passthroughImageService } from "astro/config";
import wordpress from "astro-wordpress";

export default defineConfig({
  server: {
    host: "127.0.0.1",
  },
  adapter: wordpress({
    devProxyTarget: "http://localhost:7001", // ローカルのWordPress URL
    outDir: "./wp/wp-content/themes/<theme-name>", // ビルドされたテーマの出力先
  }),
  image: {
    service: passthroughImageService(), // 必須 — WordPressが画像を配信/最適化します
  },
});

Docker Compose WordPress（上記compose.yamlを使用）には、さらに3つのオプションが必要です。それぞれ、実際に欠いた状態で動作させてみて確認済みです（「落とし穴」を参照）：

export default defineConfig({
  server: {
    host: "0.0.0.0", // すべてのインターフェースにバインドしてコンテナがアクセスできるようにする
    allowedHosts: ["host.docker.internal"],
  },
  adapter: wordpress({
    devProxyTarget: "http://localhost:8088",
    outDir: "./wp/wp-content/themes/<theme-name>",
    // WordPressコンテナ自身から見たバインドマウントされたpublic/ディレクトリのパス —
    // ホストパスではありません（「落とし穴」を参照）
    publicDirPath: "/var/www/html/public",
    // コンテナ*内部*で実行されているPHP開発テンプレートスタブが、
    // ホスト上で実行されているAstro開発サーバーにアクセスできるようにする
    devServerTarget: "http://host.docker.internal:4321",
  }),
  image: { service: passthroughImageService() },
});

devProxyTargetはWordPressが実際にリスンしている場所と一致している必要があります。outDirはnpm run buildが完成したテーマを書き込む場所です。Astroプロジェクト内にある必要はありません。もしある場合（例えば./wp/の下にある完全なローカルWordPressチェックアウト）、そのディレクトリを.gitignoreに追加してください。WordPressコアとそのアップロードはAstroプロジェクトのリポジトリに属しません。

3. テーマスタイルシートを追加する

WordPressは、テーマディレクトリが次のヘッダーを持つstyle.cssを持っている場合にのみ認識します。public/style.cssを作成します（アダプターによってoutDirに自動的にシンボリックリンク/コピーされます）：

/*!
Theme Name: <Theme Name>
Version: 0.0.1
*/

4. ページを.php.astroに変換する

WordPressで提供したい各src/pages/*.astroルートをsrc/pages/*.php.astroにリネームします。ファイルのデフォルトエクスポートは引き続きAstro/既存のレイアウトとコンポーネントを介してレンダリングされ、変更されません。拡張子と最終的な出力形式のみが変わります（index.astro → index.php）。ページが正しくビルドおよび配信されるために、他のコード変更は必要ありません。

非インデックスのWordPressテンプレートファイルも同じパターンに従います。page-template-プレフィックスは自動検出され、WordPressがカスタムページテンプレートとして認識する/* Template Name: ... */コメントに変換されます（例：src/pages/page-template-landing.php.astro → 選択可能な「ランディング」テンプレート）。（アダプターのREADMEに記載されています。このレシピではテストしていません。）

周囲にHTMLドキュメントがない生のPHPを出力する必要があるファイル（例：フック/フィールドを登録するために使用されるfunctions.php.astro — astro-wordpress-acfスキルを参照）の場合は、フロントマターにexport const partial = true;を追加します。これがないと、Astroは出力の先頭に自動的に<!DOCTYPE html>を付加し、PHPファイルを壊します。

5. テーマをアクティベートする

普遍的な方法：WP管理画面 → 外観 → テーマ → 有効化。wp-cli（ローカルまたはDocker化、手順0を参照）を使用する場合：

npm run build
wp theme activate <theme-name> --path=<wp-dir>

確認

# 1. 開発サーバーとWordPressの両方が起動しているか？すべてのリクエストはdevProxyTargetをプロキシするため、
#    WordPressに到達できないと静的アセットも502になります
npm run dev &
curl -o /dev/null -s -w "%{http_code}\n" http://127.0.0.1:4321/

# 2. WPプロキシをバイパスして、開発サーバーから直接AstroレンダリングされたPHPテイストの出力を表示する —
#    「これはAstroの問題かWordPressの問題か」を切り分けるのに便利です
curl -s -H "by-pass-proxy: 1" http://127.0.0.1:4321/index.php | head -c 300

# 3. プロダクションビルドがoutDirに実際のプレーンなPHPファイルを生成するか確認
npm run build
grep -c '<?php' wp/wp-content/themes/<theme-name>/index.php

# 4. テーマがアクティブかどうか — wp-cli経由、またはwp-cliが利用できない場合はフロントページをロードして
#    テーマ固有のマークアップを確認する
wp theme list --path=<wp-dir> | grep <theme-name>

まだテストするローカルWordPressインストールがなく、WordPressインストール自体がヘッドレスで動作することを確認したい場合（wp-cliなし、ブラウザなし）？ インストールウィザードは単純なフォームPOSTです。これは、このスキル用に新しいWordPressインストールが検証された方法そのものです：

curl "http://localhost:8088/wp-admin/install.php?step=2" \
  --data-urlencode "weblog_title=My Site" \
  --data-urlencode "user_name=admin" \
  --data-urlencode "admin_password=<password>" \
  --data-urlencode "admin_password2=<password>" \
  --data-urlencode "pw_weak=1" \
  --data-urlencode "[email protected]" \
  --data-urlencode "Submit=Install WordPress"
# その後、同じ方法でログインし（クッキージャーを使用）、後続の管理画面チェックを行います：
curl -c cookies.txt \
  --data-urlencode "log=admin" --data-urlencode "pwd=<password>" \
  --data-urlencode "wp-submit=Log In" \
  --data-urlencode "redirect_to=http://localhost:8088/wp-admin/" \
  --data-urlencode "testcookie=1" \
  "http://localhost:8088/wp-login.php"
curl -b cookies.txt "http://localhost:8088/wp-admin/" | grep -o "<title>[^<]*</title>"

落とし穴

• 開発モードのすべてのリクエストはdevProxyTargetをプロキシします。.phpページだけでなく、/src、/@、/node_modules、およびby-pass-proxyヘッダーを持つものだけがバイパスされます。WordPressが実行されていない場合、public/以下の画像/フォントを含むサイト全体が502になります。Astro側をデバッグする前に、WordPressが実際に起動していることを確認してください。
• Astro 7の開発サーバーは永続的なバックグラウンドデーモンです。 npm run devを2回目に実行しても、再バインドやエラーは発生せず、すでに実行中のインスタンスを報告するだけです（直接管理するにはnpx astro dev status / stop / logsを使用）。
• export const partial = true; — 手順4を参照。これはアダプター全体で最もわかりにくい要件です。障害モード（PHPファイルの先頭に無関係な<!DOCTYPE html>がある）はAstroとはまったく関係がないように見えます。
• publicDirPathはWPコンテナから見たパスでなければならず、ホストパスではありません。 アダプターは、指定されたpublicDirPathを文字通り使用して、各public/ファイルをテーマディレクトリにシンボリックリンクします。Dockerを使用する場合、コンテナパス（/var/www/html/public）を指定してください。これは、結果のシンボリックリンクを双方向で確認することで確認済みです。readlink wp-content/themes/<theme>/style.css → /var/www/html/public/style.css、これはdocker exec <container> cat wp-content/themes/<theme>/style.cssでは正常に解決されますが、ホストシェルからはNo such file or directoryになります。publicDirPathを省略すると、アダプターはホストパスにフォールバックしますが、これはコンテナ内では無効です。
• astro devのデーモンロックはプロジェクトディレクトリごとであり、設定/ポートごとではありません。 同じディレクトリで通常のastro devがすでに実行されている状態でastro dev --config other.config.mjs --port 4325を実行すると、元のポートで「Dev server already running」と報告されるだけで、2番目のインスタンスは起動しません。同じプロジェクトで設定（例：ベアメタル vs Docker）を切り替える必要がある場合は、最初にastro dev stopで既存のインスタンスを停止してください。
• この変換だけではwp_head()/wp_footer()をレイアウトに配線しません。そのため、プラグインによって注入される<script>/<style>タグ、SEOプラグインのメタタグなどは表示されません。astro-wordpressのREADMEには、そのためにレイアウトに<Fragment set:html={} /> / <?php wp_footer(); ?>を追加することが示されています。レイアウトが独自の<head>を独立して構築している場合（既存の静的テンプレートを移植するときによくある）、それらを配線することは、このスキルの手順で既に提供されているものではなく、意図的なフォローアップとして扱ってください。
• astro check（npm run buildの一部）はOOMクラッシュする可能性があります。コンテナが起動すると./wpに配置されるWordPressコアファイル（wp-includes/js/dist/以下の数千の.js/.phpファイルなど）の型チェックを試みるためです。Docker WPがすでに起動している状態でビルドを実行する前に、tsconfig.jsonに"exclude": ["dist", "wp"]を追加してください。そうしないと、WordPressアダプターとは無関係に見えるNodeヒープクラッシュとして障害が現れます。
• Biome（またはリポジトリ全体に対して実行されるリンター/フォーマッター）も./wpを処理しようとします。同じ理由で、プロジェクトのlint/formatコマンドを実行する前に、無視エントリ（例：biome.jsonの"files": { "ignore": ["wp/**"] }）を追加してください。
• 動的なrest-paramルートは変換されません。 src/pages/blog/[...slug].astro（または任意の[...x].astro）は[...x].php.astroにできません。Astroのルーターはこれを即座に拒否します（「rest parameter must be a standalone segment」）。.phpサフィックスがセグメント境界を壊すためです。これらのルートはそのままプレーンな.astroとして残し、WordPressテーマの外に置いてください。コンテンツ自体がWordPressに移行されている場合を除きます。

次のステップ

アダプターが配線されたら：

• astro-wordpress-acf — ACFを使用して、ページの特定のセクションをWordPress管理画面から編集可能にします。
• astro-wordpress-menus — ヘッダー/フッター/ナビコンポーネントを、ハードコードされたリンクではなく、WordPress管理のメニュー（外観 → メニュー）に接続します。
• astro-wordpress-global-settings — どのページにも限定されない値のためのサイト全体の「テーマオプションページ」を追加します（ACF ProまたはSecure Custom Fieldsが必要です）。