はじめに (対象読者・この記事でわかること)

この記事は、CakePHP 4/5をローカル環境（Windows/Mac）で動かそうとしているが、真っ白な画面や404エラーが出てしまうという方を対象にしています。
Composerでcomposer create-project cakephp/appまで完了したのに、ブラウザでhttp://localhost/を開いても「Welcome to CakePHP」が表示されない……そんな焦りと戸惑い、私も味わいました。

この記事を読むと、「mod_rewriteが効いていない」「DocumentRootの設定ミス」「tmp/cacheの権限不足」という3つの典型ケースを自分で診断し、最短で初期画面を表示できるようになります。環境構築で1日潰すことはもうありません。

前提知識

この記事を読み進める上で、以下の知識があるとスムーズです。

  • PHP 8.1以上がインストール済みであること
  • ApacheまたはNginxで仮想ホストを作成できること
  • Composerの基本的なコマンド操作
  • ターミナル（PowerShell、Terminal）でのファイル権限変更コマンドを打てること

CakePHPが表示されない最大の理由：mod_rewriteが効いていない

CakePHPは、.htaccessファイルを使ってwebroot/index.phpへのリライトを行います。
つまり、Apacheのmod_rewriteモジュールが無効だと、URLが正しくルーティングされず、白い画面や「404 Not Found」が返ってきます。

また、CakePHP 4以降はサーバーのDocumentRootを/app/webrootに向けるのが推奨です。
http://localhost/cakephp/app/webrootのように深いパスでアクセスすると、.htaccessのルールが混乱して、CSSもJSも404になり、「真っ白だけどソースを見るとHTMLはある」という謎現象が起きます。

さらに、tmpフォルダの書き込み権限がないと、CakePHPがキャッシュやログを書き込めず、エラーメッセージすら表示されないこともあります。
これら3つ（mod_rewrite・DocumentRoot・権限）をチェックすれば、9割は初期画面が表示されます。

具体的な手順とコマンドで初期画面を表示する

ここからは、Windows（XAMMP）＋ApacheとMac（Homebrew）＋Apacheの両方で動作確認した手順を紹介します。
すべてコマンド1発で済むものなので、順番にやっていきましょう。

ステップ1：mod_rewriteを有効にする

Windows（XAMMP）の場合

  1. C:\xampp\apache\conf\httpd.confを開く
  2. 以下の行の先頭の#（コメント）を外す
    apache LoadModule rewrite_module modules/mod_rewrite.so
  3. 同ファイル内でAllowOverride NoneをAllowOverride Allに書き換える
    apache <Directory "C:/xampp/htdocs"> AllowOverride All </Directory>
  4. XAMPPコントロールパネルからApacheを再起動

Mac（Homebrew）の場合

Bash

# 1. mod_rewriteはデフォルトで有効なので、無効化されてなければOK
httpd -M | grep rewrite
# rewrite_moduleが表示されればOK

# 2. /etc/apache2/httpd.confを開き、下記2行を確認
LoadModule rewrite_module lib/httpd/modules/mod_rewrite.so
AllowOverride All

ステップ2：DocumentRootを正しく設定する

CakePHPの推奨構成では、DocumentRootを/app/webrootに向けるのが鉄則です。
勘違いしやすいのが、「プロジェクトルートをDocumentRootにして、そこから相対パスでアクセスすればいいや」というアイデアです。これが失敗のもと。

仮想ホスト設定例（Mac）

/etc/apache2/extra/httpd-vhosts.confに以下を追記：

Apache

<VirtualHost *:80>
    ServerName cakephp.local
    DocumentRoot "/Users/yourname/Sites/cakephp/app/webroot"
    <Directory "/Users/yourname/Sites/cakephp/app/webroot">
        AllowOverride All
        Require all granted
    </Directory>
    ErrorLog "/var/log/apache2/cakephp-error.log"
    CustomLog "/var/log/apache2/cakephp-access.log" common
</VirtualHost>

その後、/etc/hostsに127.0.0.1 cakephp.localを追加して、
sudo apachectl restartで再起動。
ブラウザでhttp://cakephp.localを開けば、真っ白画面が「Welcome to CakePHP」に変わります。

ステップ3：tmp/cacheの権限を777にする（開発環境のみ）

CakePHPは実行時にlogs/やcache/に書き込むため、書き込み権限が必須です。

Bash

# プロジェクトルートで実行
chmod -R 777 tmp logs

本番環境では755やより厳格なACLに留めるべきですが、ローカル開発では777で問題ありません。

ハマった点：「mod_rewriteは有効だがCSSが404」

私はmod_rewriteが有効でも、CSSのパスが404になってしまいました。
原因は「ブラウザでhttp://localhost/cakephp/とディレクトリを掘ってアクセスしていた」こと。
ApacheのRewriteBaseが正しく解決できず、CSSへのパスがhttp://localhost/cakephp/css/base.cssのようにズレていたのです。

解決策

DocumentRootをwebrootに向けた上で、プロジェクトルートの.htaccessに

Apache

RewriteBase /cakephp/

を追記。
これでRewriteBaseが揃い、CSS・JSのパスが正しく解決されました。

まとめ

本記事では、CakePHPをインストールしたのに初期画面が表示されないという悩みを、
・mod_rewriteの有効化
・DocumentRootをwebrootに向ける
・tmp/logsの権限777

の3ステップで解決する方法を解説しました。

  • mod_rewriteが無効だと、CakePHPのルーティングが効かず404や白画面になる
  • DocumentRootをwebrootに向けなければ、CSS/JSが404になり「真っ白」に見える
  • tmp/logsに書き込めないと、キャッシュやログが書けず、エラーメッセージすら出ない

この記事を通して、環境構築で1日潰すことなく、最短15分でCakePHPの初期画面を表示できるようになりました。
次回は、「CakePHP 5でAPIモードを有効にして、Vue3のVite環境と連携する」方法を紹介します。

参考資料