php artisan key:generate は、Laravel アプリケーションの暗号化基盤で使用される APP_KEY（アプリケーションキー）を自動生成し、.env ファイルに設定する Artisan コマンドです。構文は php artisan key:generate [--show] [--force] であり、新規プロジェクト作成時や環境構築時に必ず実行します。ただし、稼働中の本番環境で不用意に再実行するとセッションの切断や暗号化データの復号不能を引き起こすため、正しい仕様と運用の理解が不可欠です。
- カテゴリ: artisan（コマンドライン）
- 対応バージョン: Laravel 11 / Laravel 12（PHP 8.2〜8.4対応）
- コマンド:
php artisan key:generate - 関連コマンド / 設定:
config:clear,optimize:clear,.env,APP_KEY,APP_PREVIOUS_KEYS
要点（TL;DR）
php artisan key:generateは 32バイトのランダムな暗号化秘密鍵（APP_KEY）を生成して.envに書き込む コマンド。--showオプションで.envを書き換えずにキーのみを表示可能（DockerやCI、Secret Manager連携で重宝）。--forceオプションで本番環境（APP_ENV=production）での対話型確認プロンプトをスキップして上書き可能。- 本番環境での安易な再生成は厳禁。既存のセッション切断、Cookie無効化、データベース暗号化カラムの復号不能（データ破損）が発生します。
概要とLaravel 11/12における基本動作
key:generate は、Laravel の暗号化サービス（Illuminate\Encryption\Encrypter）が利用する共通鍵（APP_KEY）を安全な乱数生成器から生成するコマンドです。
Laravel 11 および Laravel 12 ではアプリケーション構造が大幅にスリム化されましたが、暗号化の基本設計は踏襲されています。デフォルトでは暗号化方式として AES-256-CBC が採用されており、32バイトのランダムな文字列が生成され、base64: プレフィックスを伴って .env の APP_KEY に保存されます。
構文 / シグネチャとオプション
php artisan key:generate [--show] [--force]利用可能なオプション一覧
| オプション | 必須 | 説明・実務での用途 |
|---|---|---|
--show | 任意 | 生成した暗号化キーを画面（コンソール）に出力する。.env ファイルは書き換えない。CI環境やSecret Managerへの登録時に使用。 |
--force | 任意 | 本番環境（APP_ENV=production）や既に APP_KEY が設定されている場合の確認プロンプトをスキップし、強制的に上書きする。CI/CDビルドで必須。 |
基本的な使い方と実行例
1. 通常実行（.env への直接反映）
ローカル環境の初回セットアップ時は、引数なしでコマンドを実行します。
php artisan key:generate
# 出力例: Application key set successfully.コマンドが完了すると、プロジェクトルートの .env ファイル内にある APP_KEY が更新されます。
APP_KEY=base64:4k8YVd1Vl93KqL7XJ3N5o8+x9a0b1c2d3e4f5g6h7i8=2. –show オプションでキーのみを取得する
.env ファイルを変更せず、キー文字列だけを取得したい場合は --show を使用します。
php artisan key:generate --show
# 出力例: base64:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3. –force オプションで強制上書きする
APP_ENV=production に設定された環境やスクリプト自動実行時、確認ダイアログ（Do you really wish to run this command?）で処理が停止しないように --force を付与します。
php artisan key:generate --forceDocker / CI環境での設定手順と自動化
DockerコンテナやCI/CDパイプラインにおいて、APP_KEY をどのように生成・管理すべきかはトラブルの多いポイントです。代表的なパターンを解説します。
Docker / Laravel Sail での環境構築手順
注意：Dockerイメージをビルドする際（Dockerfile内）で key:generate を実行してはいけません。イメージ内に固定のキーが焼き込まれてしまい、セキュリティ事故の原因になります。
Laravel Sail の場合:
# Sail コンテナ起動後、コンテナ内で実行
./vendor/bin/sail artisan key:generateカスタム Dockerfile / コンテナ初期起動エントリポイントの場合:
コンテナ起動時のシェルスクリプト（entrypoint.sh）で .env の存在と APP_KEY の未設定を検知して自動生成させる設計が標準的です。
#!/bin/sh
set -e
# .envが存在しない場合はコピー
if [ ! -f .env ]; then
cp .env.example .env
fi
# APP_KEYが空の場合は生成
if ! grep -q "^APP_KEY=base64:" .env; then
php artisan key:generate --force
fi
# 設定キャッシュのクリア
php artisan config:clear
exec "$@"CI/CD（GitHub Actions）でのテスト実行手順
GitHub Actions などのCI環境で自動テストを実行する場合、.env.ci や .env.example をコピーした上で key:generate --force を実行するか、ワークフローの環境変数に直接注入します。
name: Laravel Tests
on: [push, pull_request]
jobs:
laravel-tests:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup PHP
uses: shivammathur/setup-php@v2
with:
php-version: '8.3'
extensions: mbstring, pdo, pdo_sqlite
- name: Install Dependencies
run: composer install -q --no-ansi --no-interaction --no-scripts --no-progress --prefer-dist
- name: Prepare Environment
run: |
cp .env.example .env
php artisan key:generate --force
- name: Execute Tests
run: php artisan test本番環境での再生成リスクと重大な注意点
運用中の本番環境で php artisan key:generate を実行してキーを変更すると、旧キーで暗号化されていたすべてのデータが復号不能になります。
| 影響を受ける機能 | 発生する障害・現象 | 対処・予防策 |
|---|---|---|
| データベース暗号化カラム | Crypt::encrypt() や Eloquent の暗号化キャストで保存したデータが復号できず例外が発生する（実質的なデータ破損） | キー再生成前に旧キーで全件復号し、新キーで再暗号化するバッチスクリプトを実行する |
| ユーザーセッション | 保存されていた全ユーザーのセッションが無効化され、強制ログアウトが発生する | メンテナンス時間帯に実施し、再ログインを促す |
| Cookie・CSRFトークン | Cookie署名の不整合により 419 Page Expired エラーが多発する | ブラウザCookieのクリアまたは再アクセスで解消 |
| 署名付きURL / パスワードリセット | 送信済みのメール認証リンクやパスワード再設定リンクが無効になる | ユーザーにリンクの再発行を案内する |
本番環境でキーを変更する必要が生じた場合は、Laravel 11 / 12 で導入された APP_PREVIOUS_KEYS による安全なキーローテーション手法を活用してください。詳しい仕組みと移行手順はLaravelのAPP_KEYとは？暗号化の仕組み・変更時の影響と安全な生成・管理ガイドで詳しく解説しています。
設定が反映されない場合の対処（キャッシュクリア）
キーを手動で変更した場合や key:generate 実行後にエラーが解消しない場合、設定ファイルがキャッシュされている可能性があります。本番環境や最適化済みの環境では、必ず以下のコマンドで設定キャッシュをクリア・再生成してください。
# 設定キャッシュをクリア
php artisan config:clear
# または全キャッシュを一括クリア
php artisan optimize:clear
# （本番環境の場合）キャッシュを再作成
php artisan config:cacheテストコード例（Pest / PHPUnit）
CI環境などで APP_KEY が正常に設定されているかを検証するテストコードです。
// Pest でのテスト例
it('has a valid application encryption key', function () {
expect(config('app.key'))
->not->toBeEmpty()
->and(config('app.key'))->toStartWith('base64:');
});トラブルシューティング（エラー別解決策）
| エラーメッセージ / 症状 | 主な原因 | 解決策 |
|---|---|---|
RuntimeException: No application encryption key has been specified. | .env の APP_KEY が空、または .env ファイル自体が存在しない | cp .env.example .env を実行後、php artisan key:generate を実行する |
The MAC is invalid. / The payload is invalid. | 暗号化時と異なる APP_KEY で復号を試みた | 元の APP_KEY に戻すか、Laravel 11以降であれば APP_PREVIOUS_KEYS に旧キーを追加する |
Permission denied（.envへの書き込み失敗） | 実行ユーザーに .env の書き込み権限がない | chmod 644 .env または chown で権限を修正するか、--show でキーを取得して手動設定する |
| 本番環境で実行時に停止する | APP_ENV=production による確認プロンプト | スクリプトやCIからの実行時は --force オプションを付与する |
よくある質問（FAQ）
Q1. 誤って .env を Git にプッシュしてしまった場合はどうすればいいですか？
A. 公開されたキーは漏洩したものとみなし、直ちに php artisan key:generate --force で再発行してください。また、Git履歴から該当コミットを削除（git filter-repo や BFG Repo-Cleaner 等を使用）し、.gitignore に .env が指定されているか確認します。キー変更により既存セッションは切断されるため注意してください。
Q2. 開発環境・ステージング環境・本番環境で同じキーを使っても良いですか？
A. 絶対に避けてください。同じキーを使い回すと、開発環境のデータベースダンプが漏洩した場合に本番環境の暗号化データまで復号されてしまうリスクが生じます。環境ごとに必ず個別のキーを発行してください。
Q3. APP_KEY を紛失した場合、暗号化データは復元できますか？
A. 復元できません。AES-256 暗号は鍵がない状態での復号が数学的に極めて困難であるため、キーを紛失したデータは二度と取り出せなくなります。.env のバックアップや Secret Manager での保管を徹底してください。
まとめ・関連記事
php artisan key:generate は、Laravel アプリケーションの暗号化・セキュリティを担保するための最も基本的かつ重要なコマンドです。
- プロジェクト作成時や新規環境構築時には必ず一度実行する
- コンテナやCI/CD環境では
--showや--forceを適切に使い分ける - 本番環境での安易な再生成は避け、キー変更時は
APP_PREVIOUS_KEYSによるローテーションを行う
関連するおすすめ記事:
- LaravelのAPP_KEYとは？暗号化の仕組み・変更時の影響と安全な生成・管理ガイド
- config:clear — 設定キャッシュをクリアするコマンド
- config:cache — 設定をキャッシュするコマンド
- php artisanとは？使い方とコマンド一覧｜最速チートシート＆現場ノウハウ