Next.js 環境変数が undefined になる問題の解決方法
問題の概要
Next.js アプリケーションで環境変数を定義しているにもかかわらず、process.env.NEXT_PUBLIC_XXX が undefined になることがあります。この問題は、環境変数の設定方法や命名規則、サーバーの再起動などの要因によって発生します。
基本的な解決方法
1. 環境変数の命名規則
Next.js では、クライアントサイド（ブラウザ）で環境変数を利用するためには、変数名に NEXT_PUBLIC_ プレフィックスを付ける必要があります。
NEXT_PUBLIC_API_URL=http://localhost:3000/api
NEXT_PUBLIC_ANALYTICS_ID=your_analytics_idサーバーサイドのみで使用する機密情報（APIキー、データベース接続情報など）にはプレフィックスを付けないでください。
# サーバーサイドのみで使用（クライアントに公開されない）
DATABASE_URL=your_database_url
API_SECRET=your_secret_key2. ファイルの配置と種類
環境変数ファイルはプロジェクトのルートディレクトリに配置し、環境に応じて適切なファイルを使用します。
.env- すべての環境で使用.env.local- ローカル開発環境（.gitignoreに追加推奨）.env.development- 開発環境.env.production- 本番環境
重要
.env.local ファイルは必ず .gitignore に追加し、機密情報がリポジトリにコミットされないようにしてください。
3. サーバーの再起動
環境変数を追加または変更した後は、開発サーバーを再起動する必要があります。
# 現在のサーバーを停止して再起動
npm run dev再起動時にコンソールに Loaded env from [path]/.env.local のようなメッセージが表示され、環境変数が正しく読み込まれていることを確認できます。
高度な設定とトラブルシューティング
next.config.js での設定
Next.js 9.4より前のバージョンや、特定の設定が必要な場合は、next.config.js で環境変数を明示的に設定できます。
/** @type {import('next').NextConfig} */
const nextConfig = {
reactStrictMode: true,
env: {
// クライアントサイドで使用する環境変数
NEXT_PUBLIC_API_URL: process.env.NEXT_PUBLIC_API_URL,
},
// ランタイム設定（Next.js 12以降）
publicRuntimeConfig: {
staticFolder: '/static',
apiUrl: process.env.NEXT_PUBLIC_API_URL,
},
serverRuntimeConfig: {
// サーバーサイドのみで使用する機密情報
secretKey: process.env.SECRET_KEY,
},
};
module.exports = nextConfig;// クライアントサイドとサーバーサイドの両方で使用
import getConfig from 'next/config';
const { publicRuntimeConfig } = getConfig();
console.log(publicRuntimeConfig.apiUrl);// サーバーサイドでのみ使用
import getConfig from 'next/config';
const { serverRuntimeConfig } = getConfig();
console.log(serverRuntimeConfig.secretKey);ビルド時の注意点
Next.js の環境変数はビルド時に靜的に置き換えられます。つまり、本番環境ではビルド後に環境変数を変更しても反映されません。
重要
本番環境で環境変数を変更する場合は、アプリケーションを再ビルドする必要があります。Dockerを使用している場合、環境変数はビルド時に注入されるため、異なる環境ごとに別々のイメージをビルドする必要があります。
ランタイム環境変数の処理
ビルド後でも環境変数を変更したい場合は、以下の方法があります。
方法1: サーバーサイドからクライアントに渡す
export default function HomePage({ apiUrl }) {
return <ClientComponent apiUrl={apiUrl} />;
}
export async function getServerSideProps() {
return {
props: {
apiUrl: process.env.API_URL || 'default_url',
},
};
}方法2: next-runtime-env パッケージの使用
npm install next-runtime-envimport { PublicEnvScript } from 'next-runtime-env';
export default function RootLayout({ children }) {
return (
<html lang="ja">
<head>
<PublicEnvScript />
</head>
<body>{children}</body>
</html>
);
}'use client';
import { env } from 'next-runtime-env';
export default function ClientComponent() {
const apiUrl = env('NEXT_PUBLIC_API_URL');
return <div>API URL: {apiUrl}</div>;
}デバッグのコツ
環境変数が正しく設定されているか確認するには、以下のデバッグ方法が有効です。
// すべての環境変数をログ出力
console.log(process.env);
// 特定の環境変数を確認
console.log('API URL:', process.env.NEXT_PUBLIC_API_URL);TIP
環境変数名にタイプミスがないか確認してください。大文字と小文字は区別されます。
まとめ
Next.js で環境変数が正しく機能しない場合の主な原因と解決策は以下の通りです：
- プレフィックスの確認: クライアントサイドで使用する変数には
NEXT_PUBLIC_を付ける - ファイル配置: 環境変数ファイルはプロジェクトルートに配置する
- サーバー再起動: 環境変数を変更した後はサーバーを再起動する
- ビルド時の注意: 本番環境の変数はビルド時に設定される
- ランタイム変数: ビルド後も変更可能な変数が必要な場合は別の方法を検討する
これらのポイントを確認すれば、ほとんどの環境変数関連の問題を解決できるでしょう。