はじめに

Next.jsとPrismaを使った開発で「なぜ.envと.env.localの2つのファイルがあるの？」「Prismaが違うデータベースに接続してしまった！」という経験はありませんか？

この記事では、環境変数ファイルの使い分けについて、初心者の方でも理解できるように解説します。

環境変数ファイルの種類と優先順位

Next.jsが読み込む環境変数ファイル

Next.jsは以下の優先順位で環境変数ファイルを読み込みます：

.env.local （最優先）
.env.development / .env.production （環境に応じて）
.env （最後）

プロジェクトルート/
├── .env              # デフォルト設定
├── .env.local        # ローカル開発用（.gitignoreに追加）
├── .env.development  # 開発環境用
├── .env.production   # 本番環境用
└── .gitignore        # .env.localを除外

各ファイルの役割

`.env`

役割：プロジェクトのデフォルト設定
Git管理：する（機密情報は入れない）
用途：APIのエンドポイントなど、環境に依存しない設定

# .env
NEXT_PUBLIC_API_ENDPOINT=https://api.example.com
NEXT_PUBLIC_APP_NAME=MyApp

`.env.local`

役割：ローカル開発用の設定
Git管理：しない（.gitignoreに追加）
用途：APIキー、データベース接続情報など

# .env.local
DATABASE_URL="postgresql://user:password@localhost:5432/myapp_dev"
API_SECRET_KEY="your-secret-key-here"

`.env.development` / `.env.production`

役割：環境別の設定
Git管理：する（機密情報は入れない）
用途：環境によって異なるが、機密ではない設定

# .env.development
NEXT_PUBLIC_API_URL=http://localhost:3001
NEXT_PUBLIC_DEBUG=true

# .env.production
NEXT_PUBLIC_API_URL=https://api.myapp.com
NEXT_PUBLIC_DEBUG=false

PrismaとNext.jsの違い

問題：Prismaは`.env`しか読まない

# Next.jsアプリ起動時
npm run dev  # → .env.localを優先的に読む ✅

# Prismaコマンド実行時
npx prisma db push  # → .envしか読まない ❌

この違いにより、予期しないデータベースに接続してしまうことがあります。

解決方法

方法1：環境変数を明示的に指定（推奨）

# データベースURLを指定してPrismaコマンドを実行
DATABASE_URL="postgresql://..." npx prisma db push
DATABASE_URL="postgresql://..." npx prisma migrate dev

方法2：package.jsonにスクリプトを追加

{
  "scripts": {
    "db:push:local": "dotenv -e .env.local -- prisma db push",
    "db:migrate:local": "dotenv -e .env.local -- prisma migrate dev",
    "db:studio:local": "dotenv -e .env.local -- prisma studio"
  }
}

必要なパッケージをインストール：

npm install --save-dev dotenv-cli

使い方：

npm run db:push:local  # .env.localを使ってDBにプッシュ

実践的なセットアップ例

1. 基本的なファイル構成

myapp/
├── .env                 # デフォルト設定（Git管理）
├── .env.local          # ローカル開発（Git管理外）
├── .env.development    # 開発環境設定（Git管理）
├── .env.production     # 本番環境設定（Git管理）
├── .env.local.example  # .env.localのテンプレート（Git管理）
├── .gitignore
└── package.json

2. .gitignoreの設定

# 環境変数
.env*.local

3. .env.local.exampleの作成

新しいメンバーが参加した時のために、テンプレートを用意：

# .env.local.example
# このファイルを.env.localにコピーして使用してください
# cp .env.local.example .env.local

# データベース接続
DATABASE_URL="postgresql://user:password@localhost:5432/myapp_dev"

# 認証関連
NEXTAUTH_SECRET="your-secret-here"
NEXTAUTH_URL="http://localhost:3000"

# 外部API
STRIPE_SECRET_KEY="sk_test_..."

4. 開発フローの確立

# 初回セットアップ
git clone https://github.com/yourname/myapp.git
cd myapp
npm install
cp .env.local.example .env.local
# .env.localを編集して正しい値を設定

# データベースセットアップ
npm run db:push:local

# 開発開始
npm run dev

複数環境での実践例

Neon DBでブランチを使う場合

# .env (メインブランチDB)
DATABASE_URL="postgresql://user:pass@main-branch.neon.tech/db"

# .env.local (開発ブランチDB)
DATABASE_URL="postgresql://user:pass@dev-branch.neon.tech/db"

ステージング環境を追加する場合

// package.json
{
  "scripts": {
    "dev": "next dev",
    "dev:staging": "dotenv -e .env.staging -- next dev",
    "build:staging": "dotenv -e .env.staging -- next build"
  }
}

トラブルシューティング

よくある問題と解決策

1. Prismaが違うDBに接続してしまう

# ❌ 間違い
npx prisma db push  # .envを読んでしまう

# ✅ 正解
DATABASE_URL="正しいURL" npx prisma db push

2. 環境変数が反映されない

# Next.jsを再起動
npm run dev を停止（Ctrl+C）して再実行

3. Vercelにデプロイ時の設定

Vercelのダッシュボードで環境変数を設定：

Project Settings → Environment Variables
環境ごとに変数を設定（Production/Preview/Development）

まとめ

覚えておくべきポイント

Next.jsは.env.localを優先的に読む
Prismaは.envしか読まない
機密情報は.env.localに入れて、Gitに含めない
環境別の設定は明確に分離する

ベストプラクティス

.env.local.exampleを作成して、チームメンバーが簡単にセットアップできるようにする
package.jsonにスクリプトを追加して、コマンドを簡略化する
環境変数の命名規則を統一する（例：NEXT_PUBLIC_プレフィックス）

環境変数の管理は最初は複雑に感じるかもしれませんが、この仕組みを理解することで、安全で効率的な開発環境を構築できます。

Happy Coding! 🚀