【PR】を含みます。

WordPress

Windows+WSL2でWordPressテーマ開発環境をDockerで構築する方法（BrowserSync/VS Code対応）

Windows WSL2でWordPressテーマ開発環境をDockerで構築する方法（BrowserSync/VS Code対応）

この記事では、WordPress・DB・phpMyAdminに加えて、BrowserSync（自動リロード）やVS Code（code .）まで含めた、快適なWordPressテーマ開発環境を一気に構築します。

さらにBrowserSyncを使うことで、PCだけでなくスマホ実機からの表示確認（同一ネットワーク内）も簡単に行えるようになります。

プロジェクトをWSLの/home配下に置いて、WSLからdocker composeを実行することで、Windows環境でも速くて壊れにくい環境を作成することができます。

想定読者
WindowsでWordPressのテーマ開発環境を作りたい人 / WSL2を使って快適に開発したい人
完成後のURL
WordPress（8080）/ phpMyAdmin（8081）/ BrowserSync（3000）

構成と前提

  • Windows + Docker Desktop
  • WSL2（Ubuntu）
  • WordPress / MariaDB（LTS）/ phpMyAdmin
  • BrowserSync（nodeコンテナで実行）
  • VS Code（Remote - WSL）
POINT

Windows側（/mnt/c）にプロジェクトを置くと、ファイル監視が重くなることがあります。

この記事では/home配下で作業する前提で解説します。

事前準備：WSL2（Ubuntu）とDocker Desktopのセットアップ

WSLとUbuntuのインストール

Docker DesktopはWSL2バックエンドで動かすのが一般的なので、まずWSL（Ubuntu）のセットアップを行います。

Docker Desktopは「特定のLinuxディストリ（Ubuntuなど）が必須」ではありませんが、開発体験を良くするために追加のディストリ（例：Ubuntu）を入れるのが推奨されています。

  1. PowerShellを管理者で起動

    検索窓に「PowerShell」と入力 →「管理者として実行する」をクリック
    ※スタート → PowerShell → 右クリック →「管理者として実行する」でも起動できます。

    WSLとUbuntuのインストール説明画像1
  2. パスワードが求められた場合は、入力してください。
  3. 「PowerShell」に「wsl --install -d Ubuntu」と入力し、「Enter」キーを押下

    これでWSL本体とUbuntuをインストールすることができます。

    Copyをクリックするとコピーできます。

    PowerShell
    Copy
    wsl --install -d Ubuntu
    WSLとUbuntuのインストール説明画像2
  4. 「Enter new UNIX username」と表示されたら、Ubuntuで使うユーザー名を入力して「Enter」キーを押下

    Ubuntuを初回起動すると次のようなメッセージが表示され、Linux側（Ubuntu）のユーザー作成を求められます。
    これは 最初の1回だけ表示されるセットアップ画面です（次回以降は基本的に表示されません）。

    WSLとUbuntuのインストール説明画像3
  5. 「New password」と表示されたら、Ubuntuで使うパスワードを入力して「Enter」キーを押下

    パスワード入力中、画面に文字は表示されません。

    WSLとUbuntuのインストール説明画像4
  6. 「Retype new password」と表示されたら、Ubuntuで使うパスワードを入力して「Enter」キーを押下

    確認のため、同じパスワードをもう一度入力します。

    WSLとUbuntuのインストール説明画像5
  7. パスワード設定が終わると「xxxx@xxxxxxxxxx:~$」のような表示になり、Ubuntuの初期セットアップが完了した状態になります。
    WSLとUbuntuのインストール説明画像6
  8. 「exit」と入力し、「Enter」キーを押下

    WSL（Ubuntu）の画面を終了させます。

    Copyをクリックするとコピーできます。

    Ubuntu
    Copy
    exit
    WSLとUbuntuのインストール説明画像7
  9. 「wsl --update」と入力し、「Enter」キーを押下

    WSLを最新にする（入れた直後でも推奨）
    ※WSLは最新を使うのが推奨で、古いWSLだとDocker Desktopが期待通り動かない場合があります。

    Copyをクリックするとコピーできます。

    PowerShell
    Copy
    wsl --update
    WSLとUbuntuのインストール説明画像8
  10. 「wsl -l -v」と入力し、「Enter」キーを押下

    Copyをクリックするとコピーできます。

    PowerShell
    Copy
    wsl -l -v
    WSLとUbuntuのインストール説明画像9
  11. WSLが「Version 2」になっているか確認
    WSLとUbuntuのインストール説明画像10

    VERSIONが1の場合、以下のコマンドで2に変更します。

    Copyをクリックするとコピーできます。

    PowerShell
    Copy
    wsl --set-version Ubuntu 2

Dockerのインストール

以下の記事でDockerのインストール方法をまとめています。

あわせて読む
Windows Dockerのインストール手順

【Windows】Dockerのインストール手順

Dockerは、開発環境を簡単に構築できるコンテナ型仮想化ツールです。 本記事では、WindowsでDockerをインストールする手順を解説します。 これからDockerを始める方はぜひ参考にしてくだ ...

Dockerのセットアップ

  1. Docker Desktopを開く
    Dockerのセットアップ説明画像1
  2. 「Settings（歯車）」をクリック
    Dockerのセットアップ説明画像2
  3. 「Resources」をクリック
    Dockerのセットアップ説明画像3
  4. 「WSL integration」をクリック
    Dockerのセットアップ説明画像4
  5. 「Enable integration with my default WSL distro」にチェック、「Ubuntu」をON、「Apply & restart」をクリック
    Dockerのセットアップ説明画像5
  6. スタートメニューから「Ubuntu」を起動

    検索窓に「Ubuntu」と入力 →「Ubuntu」をクリック

    Dockerのセットアップ説明画像6
  7. 「docker -v」と入力し、「Enter」キーを押下

    Copyをクリックするとコピーできます。

    Ubuntu
    Copy
    docker -v
    Dockerのセットアップ説明画像7
  8. バージョンが表示されることを確認
    Dockerのセットアップ説明画像8
  9. 「docker compose version」と入力し、「Enter」キーを押下

    Copyをクリックするとコピーできます。

    Ubuntu
    Copy
    docker compose version
    Dockerのセットアップ説明画像9
  10. バージョンが表示されることを確認
    Dockerのセットアップ説明画像10

よくあるつまずきポイントと解決方法

wsl --update 後に反映されない

wsl --shutdownでWSLを再起動。

Copyをクリックするとコピーできます。

command
Copy
wsl --shutdown

wsl -l -v で Ubuntu が出ない

Ubuntuが未インストールのため、wsl --install -d UbuntuでUbuntuをインストール。

Copyをクリックするとコピーできます。

command
Copy
wsl --install -d Ubuntu

DockerがWSLで使えない

Docker Desktop側のWSL Integration がOFFのことが多いです。

「Enable integration with my default WSL distro」にチェックを入れ、「Ubuntu」をONにする。

/home配下にプロジェクトを作成

Ubuntu起動後、以下コマンドを入力し、プロジェクトファイルを作成します。

Copyをクリックするとコピーできます。

Ubuntu
Copy
mkdir -p ~/projects/wp-theme-dev
cd ~/projects/wp-theme-dev
mkdir -p wp/wp-content/themes/my-theme
Ubuntuコマンド入力

.env / docker-compose.yml / テーマファイル作成

pwdと入力し、作業場所が~/projects/wp-theme-dev（例：/home/test/projects/wp-theme-dev）になっているか確認します。

Copyをクリックするとコピーできます。

Ubuntu
Copy
pwd
作業場所確認

.envを作成（DB設定）

以下を入力し、.envを作成します。

DB_NAME、DB_USER、DB_PASSWORD、DB_ROOT_PASSWORDは、適宜変更してください。

Copyをクリックするとコピーできます。

Ubuntu
Copy
cat > .env <<'EOF'
DB_NAME=wordpress
DB_USER=wpuser
DB_PASSWORD=wppassword
DB_ROOT_PASSWORD=rootpassword
EOF

docker-compose.ymlを作成（WordPress/DB/phpMyAdmin/BrowserSync）

以下を入力し、docker-compose.ymlを作成します。

※WordPressは再現性のためバージョン固定にしています。wordpress:php8.2-apacheは最新追従で挙動が変わる可能性があるため、この記事ではwordpress:6.8.2-php8.2-apacheを使用します。

Copyをクリックするとコピーできます。

Ubuntu
Copy
cat > docker-compose.yml <<'EOF'
services:
  db:
    image: mariadb:lts
    container_name: wp-db
    environment:
      MYSQL_DATABASE: ${DB_NAME}
      MYSQL_USER: ${DB_USER}
      MYSQL_PASSWORD: ${DB_PASSWORD}
      MYSQL_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
    volumes:
      - db-data:/var/lib/mysql
    command: --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci
  wordpress:
    image: wordpress:6.8.2-php8.2-apache
    container_name: wp-app
    depends_on:
      - db
    ports:
      - '8080:80'
    environment:
      WORDPRESS_DB_HOST: db:3306
      WORDPRESS_DB_NAME: ${DB_NAME}
      WORDPRESS_DB_USER: ${DB_USER}
      WORDPRESS_DB_PASSWORD: ${DB_PASSWORD}
      WORDPRESS_CONFIG_EXTRA: |
        define('WP_HOME', 'http://' . $$_SERVER['HTTP_HOST']);
        define('WP_SITEURL', 'http://' . $$_SERVER['HTTP_HOST']);
    volumes:
      - ./wp:/var/www/html
  phpmyadmin:
    image: phpmyadmin:5.2.3
    container_name: wp-phpmyadmin
    depends_on:
      - db
    ports:
      - '8081:80'
    environment:
      PMA_HOST: db
      PMA_USER: root
      PMA_PASSWORD: ${DB_ROOT_PASSWORD}
  node:
    image: node:20-alpine
    container_name: wp-node
    working_dir: /work
    volumes:
      - ./wp/wp-content/themes/my-theme:/work
      - /work/node_modules
    depends_on:
      - wordpress
    command: sh -c "npm install && npm run dev"
    ports:
      - '3000:3000'
      - '3001:3001'
volumes:
  db-data:
EOF

補足：- /work/node_modulesはコンテナ内にnode_modulesを保持するための設定です。

ホスト側が散らかりにくくなります。

テーマ開発に必要な最低限ファイルを作成

style.css はテーマとして認識させるために必須なので先に作成します。

また、テーマを有効化したときに表示が成立するように、最低限のテンプレートとして index.php も作成します。

Copyをクリックするとコピーできます。

Ubuntu
Copy
cat > wp/wp-content/themes/my-theme/style.css <<'EOF'
/*
Theme Name: My Theme
Version: 0.1.0
*/
EOF
cat > wp/wp-content/themes/my-theme/functions.php <<'EOF'
<?php
add_action('wp_enqueue_scripts', function () {
  wp_enqueue_style('my-theme-style', get_stylesheet_uri(), [], '0.1.0');
});
EOF
cat > wp/wp-content/themes/my-theme/index.php <<'EOF'
<?php
?>
<!doctype html>
<html <?php language_attributes(); ?>>
<head>
  <meta charset="<?php bloginfo('charset'); ?>">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title><?php bloginfo('name'); ?></title>
  <?php wp_head(); ?>
</head>
<body <?php body_class(); ?>>
  <?php wp_body_open(); ?>
  <main>
    <h1>Theme is working.</h1>
    <p>This is my-theme index.php.</p>
  </main>
  <?php wp_footer(); ?>
</body>
</html>
EOF

テーマ内にpackage.jsonを作成

Copyをクリックするとコピーできます。

Ubuntu
Copy
cat > wp/wp-content/themes/my-theme/package.json <<'EOF'
{
  "name": "my-theme",
  "private": true,
  "scripts": {
    "dev": "browser-sync start --config bs-config.js --host 0.0.0.0"
  },
  "devDependencies": {
    "browser-sync": "^3.0.3"
  }
}
EOF

BrowserSync設定（bs-config.js）

この記事の設定では、BrowserSyncはbs-config.jsを置いたディレクトリ配下のPHP/CSS/JSの変更を監視対象としています。

※投稿本文など「DB側の変更」は監視対象外です。

Copyをクリックするとコピーできます。

Ubuntu
Copy
cat > wp/wp-content/themes/my-theme/bs-config.js <<'EOF'
module.exports = {
  proxy: 'http://wordpress',
  host: '0.0.0.0',
  files: [
    '**/*.php',
    '**/*.css',
    '**/*.js'
  ],
  open: false,
  notify: false,
  port: 3000,
  ui: {
    port: 3001
  }
};
EOF

※proxyに指定するのはcontainer_nameではなく、docker-compose.ymlのservices名（ここではwordpress）です。

proxyの設定がポイント：BrowserSyncは「どのサイトを中継して表示するか」をproxyで指定します。

ここではhttp://wordpressを指定しますが、これはDockerの中でWordPressコンテナを指す名前（サービス名）です。

つまり、BrowserSync（nodeコンテナ）から見るとlocalhostは「nodeコンテナ自身」を意味してしまい、WordPressには繋がりません。

Docker内からWordPressに確実に繋げるために、サービス名wordpressを使用します。

起動と動作確認

POINT

docker compose up -dを実行する前に、テーマ内にpackage.jsonとbs-config.jsを作成しておいてください。

先に起動してしまうとnodeコンテナがpackage.json not foundで落ちることがあります。

起動

Copyをクリックするとコピーできます。

Ubuntu
Copy
docker compose pull
docker compose up -d
docker compose ps

pullでイメージを最新化し、up -dで起動、psで起動結果（状態・ポート・イメージ）を確認します。

アクセス先

  • WordPress：http://localhost:8080

  • phpMyAdmin：http://localhost:8081

  • BrowserSync（自動リロード）：http://localhost:3000

  • BrowserSync UI：http://localhost:3001

初回は http://localhost:8080でWordPressセットアップ → 管理画面の「外観」からテーマを有効化します。

以降はhttp://localhost:3000で確認すると保存で自動リロードされるようになります。

POINT

WordPressの初回セットアップ・管理画面操作（ログイン等）は、基本的に http://localhost:8080 側で行うのがおすすめです。

表示確認は http://localhost:3000（BrowserSync）でOKですが、ログインがループする等の挙動が出る場合は、8080でログインしてから3000で表示確認すると安定します。

VS CodeをWSLで開く（code .）

拡張機能のWSLをインストール

VS Codeの拡張機能でWSLを入れます。

VS Codeの拡張機能 WSL

WSLのプロジェクト直下でcode .を実行

WSL(Ubuntu)で以下を実行すると、WSLとしてVS Codeが開きます。

Copyをクリックするとコピーできます。

Ubuntu
Copy
cd ~/projects/wp-theme-dev
code .

code: command not foundが出る場合

  • VS Codeを起動（Windows側）
  • コマンドパレット（Ctrl+Shift+P）でWSL: Install 'code' command in PATHを実行
  • WSL(Ubuntu)を開き直して、再度 code .

よくあるトラブルと対処方法

docker compose psのIMAGEが古いまま（更新されない）

原因：docker-compose.yml を変更しても、コンテナが自動で作り直されていない場合があります。

まずは最新イメージを取得して、コンテナを強制的に作り直します。

Copyをクリックするとコピーできます。

Ubuntu
Copy
docker compose pull
docker compose up -d --force-recreate
docker compose ps

確認ポイント：docker compose psのIMAGE列が、意図したタグ（例：wordpress:6.8.2-php8.2-apache）になっていればOKです。

それでも変わらない場合（いったん削除して起動し直す）

まれに古いコンテナが残って切り替わらないことがあります。

いったん削除してから起動し直します。

※通常 docker compose down ではDBのデータ（volume）は残ります。

Copyをクリックするとコピーできます。

Ubuntu
Copy
docker compose down
docker compose up -d
docker compose ps

BrowserSync（node）が落ちる

原因がログに出るので以下コマンドで確認します。

Copyをクリックするとコピーできます。

Ubuntu
Copy
docker compose logs --tail=200 node

よくある原因は、npm installの失敗、ポート競合（3000/3001）、設定ファイルの不足（package.json / bs-config.js）です。

パーマリンクが404になる

WordPressの管理画面の「設定 → パーマリンク → 変更を保存」で直ることが多いです。

FAQ

なぜWSLの/home配下で作業するの？

Windows側（/mnt/c）よりもファイルI/Oや監視が安定しやすく、Docker開発が快適になるためです。

BrowserSyncはどのURLで見る？

http://localhost:3000 です。

WordPressは8080ですが、自動リロードしたい場合は3000側がおすすめです。

スマホからもアクセスできる？

PCとスマホが同一Wi-Fiに接続されている場合はアクセスできます。

http://PCのIPアドレス:8080（または:3000）にアクセスします。

※アクセスできないときはWindowsファイアウォールの許可を確認してください。

PCのIPアドレスの確認方法は？

Windowsの場合、コマンドプロンプトを開いてipconfigと入力すると確認できます。

表示結果の中にある「IPv4 アドレス」が、PCのIPアドレスです。

PCをシャットダウンした場合、BrowserSyncは自動で起動しますか？

はい、Dockerコンテナを起動すればBrowserSyncも自動で立ち上がります。

PCをシャットダウンしても設定が消えることはなく、次回起動時に以下の手順を行えばOKです。

  1. Docker Desktopを起動する

  2. docker compose up -dを実行する

これだけで、WordPress・DB・phpMyAdminとあわせてBrowserSyncも自動で起動し、ファイル保存時の自動リロードがすぐに利用できます。

Dockerの停止・再開・削除はどうする？

用途ごとにコマンドが違います。

迷ったら「downは削除」「-vはデータも削除」と覚えるとOKです。

一時停止（あとで同じ状態で再開したい）

Copyをクリックするとコピーできます。

command
Copy
docker compose stop

再開（停止したコンテナを起動）

Copyをクリックするとコピーできます。

command
Copy
docker compose start

削除（コンテナを消す／DBデータは基本残る）

コンテナを作り直したいときに使います。

通常はDBのデータ（volume）は残ります。

Copyをクリックするとコピーできます。

command
Copy
docker compose down

完全削除（DBデータも含めて初期化する）

-v を付けると、DBの保存データ（volume）も削除されるので注意してください。

Copyをクリックするとコピーできます。

command
Copy
docker compose down -v

-WordPress
-,