UbuntuでLaravelのパーミッション設定（権限エラー対策）

LaravelをUbuntu環境で動かすとき、初心者が最もつまずきやすいのがパーミッション設定。Laravelは単にPHPファイルを読み込むだけではなく、ログ出力、キャッシュ生成、セッション保存、ビューキャッシュ、アップロードファイル保存などでディレクトリへの書き込みを行う。そのため、Webサーバー実行ユーザーとファイル所有者の関係が崩れていると、見た目は同じ500エラーでも、実際には権限不足が原因というケースが非常に多い。この記事では、Ubuntu上でLaravelの権限エラーが起きる理由、確認方法、よく使う修正コマンド、安全な設定方針、やってはいけない対応までをまとめる。

Laravelで権限エラーが起きる理由

Laravelは実行中に複数のファイルやディレクトリへ書き込みを行う。代表的なのは次の通り。
・storage/logs へのログ出力
・storage/framework 配下へのセッション、キャッシュ、compiled view の保存
・bootstrap/cache への設定キャッシュやルートキャッシュの保存
・storage/app へのアップロードファイル保存
これらに書き込めないと、アプリケーションは正常に動作できない。しかも、書き込み失敗時は画面上では単なる500エラーに見えることも多いため、Laravelを始めたばかりだと原因が分かりづらい。

よくある症状

権限が原因のときは、次のような症状が出やすい。
・500 Internal Server Error が出る
・ログが出ないので原因調査が進まない
・Permission denied や Failed to open stream がログに出る
・The stream or file ... could not be opened のような例外が出る
・画像アップロードやキャッシュ生成のタイミングだけ落ちる
・デプロイ直後だけ動かない
このあたりの症状が出たら、まず権限を疑う方が早い。

最初に確認する場所

Laravelで権限エラーを疑うときは、まず次のディレクトリを見る。
・storage
・bootstrap/cache
この2つが最重要。
現在の状態は次のコマンドで確認できる。

ls -la storage
ls -la bootstrap/cache

さらに、サブディレクトリまで詳しく見たい場合は次でもよい。

ls -la storage/logs
ls -la storage/framework

ここで見るポイントは、
・所有者（owner）
・グループ（group）
・パーミッション（rwx）
の3つ。
UbuntuでApacheやNginx + PHP-FPMを使う場合、実行ユーザーは www-data であることが多い。

まず試すべき基本設定

Laravelで最も基本になる権限設定は、storage と bootstrap/cache をWebサーバーが書き込める状態にすること。
応急処置として最もよく使われるのは次の2つ。

sudo chown -R www-data:www-data storage bootstrap/cache
sudo chmod -R 775 storage bootstrap/cache

これで、www-data ユーザーおよびグループが読み書きできる状態になる。
特に「今すぐ動かしたい」「まず原因が権限か確認したい」という場面では、最初にここを通して様子を見ると切り分けしやすい。

chown と chmod の違いを理解する

初心者が混乱しやすいのが、chown と chmod の違い。
・chown は所有者とグループを変える
・chmod は誰がどこまで読める・書ける・実行できるかを変える
たとえば次のコマンドは、storage と bootstrap/cache の所有者を www-data に変えている。

sudo chown -R www-data:www-data storage bootstrap/cache

一方、次のコマンドは読み書き権限を広げている。

sudo chmod -R 775 storage bootstrap/cache

つまり、所有者が合っていても権限が足りなければ失敗するし、権限が緩くても所有関係が崩れていて運用しづらいこともある。両方を見る必要がある。

775 と 777 の違い

Laravelの記事でありがちなのが「とりあえず777にする」という対処。確かに一時的には動くことが多いが、本番では推奨しにくい。
・775 は所有者とグループに書き込みを許可し、その他には読み取りと実行のみ
・777 は全員に書き込みを許可
777は切り分け用の一時対応としては動作確認に使えることがあるが、そのまま運用すると不要に権限を広げすぎる。
そのため、通常は 775 を基本にし、必要に応じて所有者・グループを整える方が安全。

# 一時確認用（本番常用は非推奨）
sudo chmod -R 777 storage bootstrap/cache

# 基本はこちら
sudo chmod -R 775 storage bootstrap/cache

プロジェクト全体の所有者を整理する考え方

storage と bootstrap/cache だけでなく、プロジェクト全体の所有者をどうするかも大事。
開発者自身が編集しつつ、Webサーバーも書き込めるようにしたい場合は、ユーザーとグループの設計を先に決めた方が良い。
たとえば、所有者はログインユーザー、グループは www-data に寄せる方法がある。

sudo chown -R $USER:www-data /var/www/myapp

その上で、書き込みが必要なディレクトリだけ 775 にする。

sudo chmod -R 775 /var/www/myapp/storage /var/www/myapp/bootstrap/cache

この形だと、開発者も編集しやすく、Webサーバー側もグループ経由で書き込みしやすい。
ただし、チーム開発やデプロイ方式によって正解は変わるので、全体所有者と実行ユーザーの関係は最初に整理する方が後で楽になる。

Apache と Nginx + PHP-FPM で見るべきユーザー

Ubuntuでは、ApacheでもNginx + PHP-FPMでも www-data が実行ユーザーになっていることが多い。
ただし、環境によっては違う場合もあるので、思い込みで設定せず確認した方が安全。
Apacheなら次のように確認できることが多い。

ps aux | grep apache2

NginxやPHP-FPMなら次のように見る。

ps aux | grep nginx
ps aux | grep php-fpm

ここで実際にどのユーザーで動いているか確認し、そのユーザーが storage や bootstrap/cache に書けるようにする。

Laravelが書き込む場所ごとの確認ポイント

Laravelの書き込み先は一律ではないため、場所ごとに確認する視点も大切。
・ログが出ない → storage/logs
・セッションがおかしい → storage/framework/sessions
・ビュー更新が反映されない、ビュー生成で落ちる → storage/framework/views
・キャッシュ系コマンドで失敗 → bootstrap/cache
・ファイルアップロード失敗 → storage/app
つまり、「何が失敗しているか」によって見るべきディレクトリも少し変わる。全部を一括で見るより、症状に対応した場所を見る方が切り分けやすい。

デプロイ後に権限エラーが出やすい理由

本番やステージングで特に多いのが、デプロイ直後だけ権限エラーが出るケース。
原因として多いのは次の通り。
・rootやCIユーザーでファイルを配置した
・以前のリリースと所有者が混在している
・storage や bootstrap/cache を上書きした
・キャッシュ生成を別ユーザーで実行した
・symlink切り替え型デプロイで共有ディレクトリの権限がズレた
つまり、コードそのものではなく「誰が配置したか」「誰が artisan コマンドを実行したか」が原因になることが多い。
デプロイ手順に chown や chmod を含めるかどうかは、プロジェクトごとに決めておいた方がよい。

権限エラーの切り分けに使うコマンド

権限が怪しいときは、次のコマンドを順番に使うと整理しやすい。

whoami
pwd
ls -la
ls -la storage
ls -la bootstrap/cache
php artisan optimize:clear
tail -n 100 storage/logs/laravel.log

これで、
・今どのユーザーで操作しているか
・どのディレクトリにいるか
・対象ディレクトリの所有者と権限はどうなっているか
・Laravelログに何が残っているか
が分かる。
権限エラーでは「コマンドは通るがWebだけ落ちる」ということも多いので、CLI実行ユーザーとWebサーバー実行ユーザーが違う点も意識する必要がある。

よくある誤った対処

権限まわりでやりがちな誤りも多い。
・プロジェクト全体を全部777にする
・rootでartisanコマンドを実行し続ける
・storage だけ見て bootstrap/cache を見ない
・権限だけ直して、所有者のズレを放置する
・エラーが直ったあとに設定を戻さない
特に、sudo php artisan ... を何度も実行すると、生成ファイルの所有者がroot寄りになり、そのあとWebサーバーから書けなくなることがある。
「sudoが通るから安心」ではなく、「どのユーザーで何を実行したか」を意識する必要がある。

本番で比較的安全に運用しやすい形

本番寄りで比較的扱いやすい考え方は、次のような形。
・プロジェクト本体はデプロイユーザー所有
・Webサーバーのグループを www-data にする
・storage と bootstrap/cache は www-data が書ける
・権限は基本775、ファイルは664程度を目安にする
たとえば次のような流れ。

sudo chown -R deploy:www-data /var/www/myapp
sudo find /var/www/myapp -type f -exec chmod 664 {} \;
sudo find /var/www/myapp -type d -exec chmod 775 {} \;

ただし、これは運用方針次第なので、チームのデプロイ設計に合わせて調整する必要がある。

権限修正後に確認したいLaravelコマンド

権限を直したら、Laravel側で実際に動くか確認した方が良い。
確認しやすいコマンドは次の通り。

php artisan about
php artisan optimize:clear
php artisan config:cache
php artisan route:cache
php artisan view:cache

これらが正常に通るなら、bootstrap/cache や storage の書き込みが概ね成立している可能性が高い。
逆に、この段階で失敗するなら、まだ権限か所有者が不整合のまま残っていることが多い。

まとめ

UbuntuでLaravelの権限エラーを防ぐうえで最も重要なのは、storage と bootstrap/cache をWebサーバー実行ユーザーが書き込める状態にすること。
そのために見るべきポイントは、
・所有者
・グループ
・パーミッション
の3つ。
基本の対処としては、
・chown で所有者やグループを整える
・chmod で 775 を基準に書き込み可能にする
・www-data など実行ユーザーを確認する
・rootでのartisan実行を乱用しない
この流れを押さえると、Laravelで頻発するPermission denied系のトラブルはかなり減らしやすい。
単に動かすだけではなく、「誰が書き込むのか」を意識して設計すると、デプロイ後や運用中の事故も防ぎやすくなる。