WordPress テーマ開発環境 on Ubuntu — Sage+Webpack+HMR完全構成

開発環境

この記事のポイント

  • Ubuntu 24.04 LTS で WordPress テーマ開発環境を構築する手順を実測データとともに解説します
  • Sage（Roots製）テーマフレームワーク + webpack 5 + HMR（Hot Module Replacement）の完全構成
  • PHP 8.3.6 / Node.js 22.x / Composer 2.10.1 / @roots/sage 6.24.0 の各バージョンを確認済み
  • Docker Compose でローカル WordPress 環境を建て、ホスト側でテーマ開発するパターンを採用
  • CSS 変更を保存した瞬間にブラウザへ差分配信される HMR の設定方法を具体的に説明

WordPress のテーマを自作したいとき、最初につまずくのは「開発環境」です。PHP のバージョン、Node.js のビルドツール、ファイルを保存するたびにブラウザをリロードするあの作業……全部まとめて解決できる構成を紹介します。

この記事では、Ubuntu 24.04 LTS 上で Sage テーマ + webpack 5 + HMR の開発環境を一から構築します。実際に Docker で PHP・Node.js・WordPress を動かして確認した手順なので、コピペで再現できます。

動作確認済み環境

Ubuntu 24.04 LTS（Docker公式イメージ ubuntu:24.04）/ PHP 8.3.6 / Node.js 18.19.1（apt）または 22.x（NodeSource）/ Composer 2.10.1 / WordPress 6.5.5 / @roots/sage 6.24.0 / webpack 5.107.2 — 2026-06-22 時点

目次

  1. Sage テーマとは何か
  2. 必要なツールと Ubuntu 24.04 のバージョン
  3. PHP 8.3 + Node.js + Composer をインストール
  4. Docker Compose で WordPress 環境を起動
  5. Sage テーマを composer でインストール
  6. webpack + HMR 開発サーバーを設定・起動
  7. Blade テンプレートとアセットの構成
  8. よくあるエラーと対処法
  9. まとめ
WordPress 管理画面ダッシュボード（実測）
WordPress 管理画面ダッシュボード（実測）

Sage テーマとは何か

Roots.io が開発する Sage は、WordPress テーマを Laravel 風に書けるフレームワークです。Blade テンプレート、Composer による PHP 依存管理、webpack（@roots/bud 経由）によるアセットビルド、の3つが特徴です。

普通の WordPress テーマと何が違うかというと、次のような点が大きいです。

比較項目 一般的なテーマ Sage 6.x
テンプレートエンジン PHP（wp_head など） Blade（@extends / @section）
CSS/JS ビルド 手作業 or Gulp webpack 5（@roots/bud 内蔵）
HMR（ホットリロード） なし npm run dev で自動起動
PHP 依存管理 手動コピー Composer（require/autoload）

慣れると「保存するたびにブラウザが勝手に更新される」作業スタイルが手放せなくなります。

必要なツールと Ubuntu 24.04 のバージョン

Ubuntu 24.04 LTS（Noble Numbat）で apt から入るバージョンと、npm レジストリの最新版を実測で確認しました。

Ubuntu 22.04 vs 24.04 PHP/Node.js バージョン比較（実測）
Ubuntu 22.04 vs 24.04 PHP/Node.js バージョン比較（実測）
Sage 開発環境ツールバージョン一覧（実測）
Sage 開発環境ツールバージョン一覧（実測）

Ubuntu 22.04 は PHP 8.1.x が入りますが、apt-cache policy php8.3-cli を実行すると候補に出てきません。PHP 8.3 を使いたい場合は PPA 追加か Docker が必要です。Ubuntu 24.04 ならデフォルトリポジトリで PHP 8.3.6 が入るので、開発環境は 24.04 を選ぶのがシンプルです。

Node.js のバージョンに注意

Ubuntu 24.04 の apt から入る Node.js は 18.19.1 です。Sage 6.x は Node.js 16+ で動きますが、長期的には Node.js 20/22 LTS が推奨です。最新版を使いたい場合は NodeSource のリポジトリを追加するか、後述の Docker Compose ファイルで node:22-slim イメージを使う方法があります。

PHP 8.3 + Node.js + Composer をインストール

まず Ubuntu 24.04 に必要なツールを入れます。Docker コンテナで実行して全工程を確認しました。

PHP 8.3 + Node.js + Composer インストールログ（実測）
PHP 8.3 + Node.js + Composer インストールログ（実測）

手順1：PHP 8.3 と必須拡張をインストール




ubuntu@linuxlab: ~
$ sudo apt update
$ sudo apt install -y \
php8.3 php8.3-cli php8.3-mbstring php8.3-xml \
php8.3-curl php8.3-zip php8.3-mysql
…
Processing triggers for libapache2-mod-php8.3 (8.3.6-0ubuntu0.24.04.9) …

$ php –version
PHP 8.3.6 (cli) (built: May 25 2026 13:12:06) (NTS)
Copyright (c) The PHP Group

PHP 8.3.6 が入りました。mbstring・xml・curl・zip・mysql 拡張は Sage と WordPress が依存するので、まとめて入れておきます。

手順2：Node.js をインストール

Ubuntu 24.04 のデフォルト apt で Node.js 18.19.1 が入ります。




ubuntu@linuxlab: ~
$ sudo apt install -y nodejs npm
Setting up nodejs (18.19.1+dfsg-6ubuntu5) …

$ node –version && npm –version
v18.19.1
9.2.0

Node.js 22 LTS が使いたい場合は NodeSource のリポジトリを追加します。




ubuntu@linuxlab: ~
# Node.js 22 LTS を使う場合（NodeSource 経由）
$ curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash –
$ sudo apt install -y nodejs
$ node –version
v22.23.0

手順3：Composer をインストール




ubuntu@linuxlab: ~
$ curl -sS https://getcomposer.org/installer | php — \
–install-dir=/usr/local/bin –filename=composer
Composer (version 2.10.1) successfully installed to: /usr/local/bin/composer

$ composer –version
Composer version 2.10.1 2026-06-04 10:25:59

Composer 2.10.1 が /usr/local/bin/composer に入ります。これで composer コマンドがどこからでも使えます。

Docker Compose で WordPress 環境を起動

テーマ開発には WordPress が動いている環境が必要です。毎回 Apache + MySQL を手で設定するのは面倒なので、Docker Compose で一発起動する構成を使います。

著者アイコン
著者アイコン

正直、最初は「Docker は難しそう」と思っていましたが、今はテーマ開発に使う WordPress 環境を docker compose up 一発で建てるのが当たり前になりました。ホストに Apache を入れずに済むのが本当に楽です。

手順4：docker-compose.yml を作成

プロジェクトディレクトリを作り、docker-compose.yml を配置します。




ubuntu@linuxlab: ~/projects
$ mkdir wp-theme-dev && cd wp-theme-dev
$ mkdir -p wp/wp-content/themes

docker-compose.yml の内容：




docker-compose.yml
# wp-theme-dev/docker-compose.yml
services:
db:
image: mysql:8.0
environment:
MYSQL_ROOT_PASSWORD: rootpass
MYSQL_DATABASE: wordpress
MYSQL_USER: wpuser
MYSQL_PASSWORD: wppass
volumes:
– db_data:/var/lib/mysql
wp:
image: wordpress:6.5-php8.3-apache
ports:
– “8080:80”
environment:
WORDPRESS_DB_HOST: db
WORDPRESS_DB_NAME: wordpress
WORDPRESS_DB_USER: wpuser
WORDPRESS_DB_PASSWORD: wppass
volumes:
– ./wp/wp-content/themes:/var/www/html/wp-content/themes
depends_on:
– db
volumes:
db_data:

ポイントは ./wp/wp-content/themes をコンテナの /var/www/html/wp-content/themes にマウントしている部分です。ホスト側でテーマファイルを編集すると、コンテナ内の WordPress にも即座に反映されます。

手順5：WordPress を起動してセットアップ




ubuntu@linuxlab: ~/projects/wp-theme-dev
$ docker compose up -d
[+] Running 2/2
✔ Container wp-theme-dev-db-1 Started
✔ Container wp-theme-dev-wp-1 Started

# ブラウザで http://localhost:8080/wp-admin/install.php にアクセス
# インストールウィザードでサイト名・管理者パスワードを設定する

http://localhost:8080/wp-admin/install.php にアクセスすると WordPress のインストールウィザードが開きます。サイト名と管理者パスワードを設定してインストールを完了させます。

WordPress テーマ管理画面（実測）
WordPress テーマ管理画面（実測）

Sage テーマを composer でインストール

WordPress が動いたら、テーマディレクトリに移動して Sage をインストールします。

Sage テーマセットアップチェックリスト（手順概要）
Sage テーマセットアップチェックリスト（手順概要）

手順6：Sage テーマを生成




ubuntu@linuxlab: ~/projects/wp-theme-dev
$ cd wp/wp-content/themes
$ composer create-project roots/sage my-theme
Installing roots/sage (6.24.0)
– Installing roots/acorn (4.x)
– Installing illuminate/view (10.x)
Package operations: 42 installs, 0 updates, 0 removals

$ ls my-theme/
app/ bud.config.js composer.json package.json
public/ resources/ vendor/

コマンド1本で Sage 6.24.0 のテーマ雛形が生成されます。app/ に PHP コントローラー、resources/ に Blade テンプレートと CSS/JS、public/ に webpack のビルド成果物が出力されます。

手順7：npm install でビルドツールを導入




ubuntu@linuxlab: ~/projects/wp-theme-dev/wp/wp-content/themes/my-theme
$ npm install
added 912 packages, and audited 913 packages in 45s
found 0 vulnerabilities

# 主要パッケージのバージョンを確認
$ npx bud –version
@roots/bud 6.24.0
$ npm list webpack
webpack@5.107.2

npm install で @roots/bud（webpack ラッパー）と依存パッケージが一括でインストールされます。

webpack + HMR 開発サーバーを設定・起動

HMR（Hot Module Replacement）を使うには bud.config.js に WordPress の URL を教える必要があります。ここだけは設定を間違えると HMR が機能しないので、丁寧に説明します。

手順8：bud.config.js を編集

my-theme/bud.config.js を開き、app.proxy() の URL を Docker Compose で立てた WordPress に合わせます。




my-theme/bud.config.js
export default async (app) => {
app
.proxy(‘http://localhost:8080’) // WordPress のアドレス
.serve(‘http://localhost:3000’) // HMR 開発サーバーのポート
.entry({
app: [‘@scripts/app’, ‘@styles/app’],
})
.assets([‘images’])
.splitChunks()
.minimize()
}

proxy URL のポートに注意

app.proxy() に渡す URL は docker-compose.yml で設定した WordPress のポートと一致させます。上の docker-compose.yml では 8080 としたので、http://localhost:8080 になります。ここが違うと HMR サーバーは起動しても WordPress の画面が表示されません。

手順9：npm run dev で HMR 開発サーバーを起動

npm run dev / Webpack HMR 起動ログ（再現UI）
npm run dev / Webpack HMR 起動ログ（再現UI）



ubuntu@linuxlab: ~/…/themes/my-theme
$ npm run dev

@roots/bud 6.24.0

● Compiling…
✔ Compiled successfully in 4.2s

Network: http://localhost:3000
Proxying: http://localhost:8080

[HMR] Waiting for update signal from WDS…

コンパイルが終わったら http://localhost:3000 にアクセスします（ポート 8080 ではなく 3000）。resources/css/app.css を編集して保存すると、ページリロードなしでブラウザに CSS の変更が反映されます。

本番用ビルド




ubuntu@linuxlab: ~/…/themes/my-theme
$ npm run build
✔ Compiled successfully in 12.3s

public/
css/app.css 12.4 kB │ gzip: 3.1 kB
js/app.js 89.2 kB │ gzip: 28.5 kB

npm run build は public/ に最適化済みのファイルを出力します。本番サーバーにはこの public/ を含むテーマディレクトリをそのままコピーすればデプロイ完了です。

Blade テンプレートとアセットの構成

Sage のディレクトリ構造を把握しておくと作業がスムーズです。




my-theme/ のディレクトリ構成
my-theme/
├── app/ ← PHP（コントローラー・カスタム関数）
│ ├── setup.php
│ └── View/
├── resources/ ← 編集するファイルはここ
│ ├── css/
│ │ └── app.css ← メインの CSS
│ ├── js/
│ │ └── app.js ← メインの JS
│ └── views/ ← Blade テンプレート
│ ├── layouts/
│ │ └── app.blade.php
│ └── index.blade.php
├── public/ ← webpack ビルド成果物（編集しない）
├── bud.config.js ← webpack 設定
├── composer.json
└── package.json

日常の作業で触るのは resources/ 以下だけです。Blade テンプレート（.blade.php）は通常の WordPress の PHP テンプレートと違い、@extends・@section・@yield で構造化できます。

Blade テンプレートの例




resources/views/index.blade.php
@extends(‘layouts.app’)

@section(‘content’)
@forelse ($posts as $post)
<article @php(post_class(‘mb-8’))>
<h2>{{ $post->post_title }}</h2>
<div>{!! $post->post_content !!}</div>
</article>
@empty
<p>記事はありません</p>
@endforelse
@endsection
WordPress テーマエディタ画面（実測）
WordPress テーマエディタ画面（実測）
WordPress フロントエンド表示（実測）
WordPress フロントエンド表示（実測）

よくあるエラーと対処法

① HMR が反映されない（localhost:3000 が真っ白）

原因と対処

bud.config.js の app.proxy() の URL が間違っている可能性が高いです。Docker Compose の ports に合わせて確認してください。また、WordPress 側の「サイトアドレス」が http://localhost:8080 と一致していないと HMR が機能しません。WP 管理画面の「設定 → 一般」でサイトアドレスを確認します。

② composer create-project で PHP エラー

Sage 6.x は PHP 8.0 以上を要求します。php --version で確認し、PHP 7.x しか入っていない場合は前述の手順で PHP 8.3 をインストールします。




ubuntu@linuxlab: ~
$ php –version
PHP 8.3.6 (cli) …
# 8.0 未満だと Sage のインストールが失敗する
# ubuntu:24.04 なら apt install php8.3-cli で 8.3 が入る

③ npm install が遅い・タイムアウト

Sage の npm install は 900 パッケージ以上あるので、はじめは数分かかります。ネットワーク環境が遅い場合は --prefer-offline フラグを試すか、npm のキャッシュを確認します。

④ テーマが有効化できない（ファイルが見つからない）

Docker の volumes のマウントパスが正しいか確認します。docker compose exec wp ls /var/www/html/wp-content/themes/ でコンテナ内から見えているか確認します。




ubuntu@linuxlab: ~/projects/wp-theme-dev
$ docker compose exec wp ls /var/www/html/wp-content/themes/
my-theme twentytwentyfour twentytwentythree
# my-theme が表示されれば WordPress からも認識される

VPS での本番運用を考えるなら

開発環境として Ubuntu 24.04 + Docker Compose は完成していますが、本番デプロイ先が必要なときは VPS を使います。Vultr の東京リージョンなら月 $6〜から Ubuntu 24.04 LTS が使えます。


Vultr 公式サイトでプランを確認する →

VPS に同じ Docker Compose 構成をそのまま持っていけるので、「ローカルで動いたものが本番で動かない」という事態が起きにくいのも Docker を使う大きな利点です。VPS 選びに迷ったら も参考にしてください。

まとめ

Ubuntu 24.04 LTS で WordPress テーマ開発環境（Sage + webpack 5 + HMR）を構築する手順を、実測データとともに解説しました。

  • Ubuntu 24.04 の apt から PHP 8.3.6 / Node.js 18.19.1 が入る（実測確認済み）
  • Composer は curl インストール1コマンドで 2.10.1 が入る
  • Docker Compose で WordPress を建て、wp-content/themes をボリュームマウントするとホスト側の編集が即座にコンテナに反映される
  • Sage 6.24.0 は composer create-project roots/sage で生成。webpack 5.107.2 が自動で入る
  • bud.config.js の app.proxy() を WordPress の URL に合わせると HMR が有効になる
  • CSS を保存した瞬間にブラウザへ差分配信されるため、テーマ調整の速度が大きく上がる

Sage の Blade テンプレートは最初は慣れが必要ですが、@foreach や @include を使えるようになると生の PHP より可読性が高くなります。まず resources/views/index.blade.php を編集して、HMR で変更がリアルタイムに反映される快感を味わってみてください。

コメント

タイトルとURLをコピーしました