Zenn
🎉

Next.jsのenvファイルについて

に公開
Next.js
Next.js
React
env
tech

公式ドキュメントを読んだので、まとめる。

この記事の想定読了時間: 5分～10分程度

環境変数ってなに？

まず、環境変数とは何かをざっくり理解しておきましょう。
環境変数とは、アプリケーションの外部から設定を読み込むための仕組みです。これにより、コードを修正することなく、環境（開発、テスト、本番など）に応じてアプリケーションの振る舞いを変更できます。

開発中はテスト用のデータベースに接続し、本番では実際のユーザーが使うデータベースに接続するように、環境変数を切り替えることで簡単に対応できるわけです。また、パスワードやAPIキーなど、絶対に公開したくない秘密の情報も、環境変数として管理することで、ソースコードに直接書き込むリスクを避けられます。

Next.jsと.envファイルたち 📄

Next.jsでは、環境変数を扱うのがとっても簡単になっています。特別な設定をしなくても、プロジェクトのルートディレクトリに置かれた.envファイルから、自動的に環境変数を読み込んでくれます。これは、まるでNext.jsが気の利く秘書のように、必要な情報を自動で拾ってきてくれるイメージですね！💼

.envファイルの仲間たちと優先順位 🏆

.envファイルにはいくつか種類があり、それぞれ優先順位があります。Next.jsは、以下の順番で環境変数を探し、最初に見つかった値を採用します。

  1. process.env （すでに設定されている環境変数）
  2. .env.$(NODE_ENV).local
  3. .env.local （NODE_ENVがtestの時は除外されます）
  4. .env.$(NODE_ENV)
  5. .env

例えば、あなたが開発モード（NODE_ENVがdevelopment）で作業している場合、Next.jsはまず.env.development.localを探し、次に.env.local、そして.env.development、最後に.envの順で環境変数を読み込みます。

それぞれのファイルの使用例はこんな感じです。

  • .env: 開発環境と本番環境で共通のデフォルト値。
  • .env.development: 開発環境特有の設定。
  • .env.production: 本番環境特有の設定。
  • .env.local: Git管理されない個人ローカル環境の設定（ここに個人のAPIキーなどを書くと良いでしょう）。

💡ポイント:
NODE_ENVという環境変数が設定されていない場合、next devコマンドを実行すると自動的にdevelopmentに、それ以外のコマンドではproductionに設定されます。

.envファイルの中身はどう書くの？

使い方はとてもシンプルです。キーと値を = で繋いで記述します。

DB_HOST=localhost
DB_USER=myuser
DB_PASS=mypassword

これで、アプリケーションのどこからでも process.env.DB_HOST のようにアクセスできるようになります。

改行を含む値も扱えますよ！

PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nKh9NV...\n-----END DSA PRIVATE KEY-----\n"

他の環境変数を参照することも可能です！

TWITTER_USER=nextjs
TWITTER_URL=https://x.com/$TWITTER_USER

この場合、process.env.TWITTER_URLはhttps://x.com/nextjsになります。もし$を値として使いたい場合は、\$のようにエスケープしてくださいね。

クライアントサイド？サーバーサイド？それが問題だ！🤯

さて、ここが環境変数で一番つまづきやすいポイントかもしれません。Next.jsでは、環境変数がサーバーサイドでしか利用できないのがデフォルトの挙動なんです！

「え、どういうこと？フロントエンドのコードで使いたいんだけど…」と思ったあなた、大丈夫です。ちゃんと解決策があります。

NEXT_PUBLIC_でクライアントサイドへ公開！📢

もしクライアントサイド（ブラウザ）のJavaScriptコードで環境変数を使いたい場合は、その変数名の先頭に NEXT_PUBLIC_ を付ける必要があります。

NEXT_PUBLIC_ANALYTICS_ID=abcdefghijk

このようにすることで、Next.jsがビルド時に、この変数の値をJavaScriptバンドルの中に「埋め込んで」くれます。

// pages/index.js または app/page.js
// 'NEXT_PUBLIC_ANALYTICS_ID'は、'NEXT_PUBLIC_'プレフィックスがあるのでクライアントサイドでも利用可能です。
// ビルド時に `setupAnalyticsService('abcdefghijk')` のように変換されます。
import setupAnalyticsService from '../lib/my-analytics-service';

setupAnalyticsService(process.env.NEXT_PUBLIC_ANALYTICS_ID);

function HomePage() {
  return <h1>Hello World</h1>;
}

export default HomePage;

⚠️ 注意点:
NEXT_PUBLIC_を付けた環境変数は、ビルド時に値が決定され、JavaScriptバンドルに埋め込まれます。つまり、一度ビルドしてデプロイしてしまうと、その値を後から変更することはできません。まるで、お弁当を作るときに「このお肉は焼く！」と決めたら、後から「やっぱり揚げる！」とは変えられないのと同じです。もしデプロイ後に動的に値を変えたい場合は、独自のAPIを用意して、そこから情報を取得するなどの工夫が必要になります。

また、process.env[varName]のように動的に環境変数を参照しようとすると、ビルド時に値がインライン化されないので注意してくださいね。

// これはインライン化されません 🙅‍♀️
const varName = 'NEXT_PUBLIC_ANALYTICS_ID';
setupAnalyticsService(process.env[varName]);

サーバーサイドで動的に読み込む場合 ⚙️

Next.jsのServer ComponentsやRoute Handlersなど、サーバーサイドで実行される機能では、NEXT_PUBLIC_プレフィックスなしでprocess.envから環境変数を読み込むことができます。

// app/page.ts (Server Componentの例)
import { connection } from 'next/server'; // これはNext.jsのAPIではなく、単なる例示として使われているようです

export default async function Component() {
  await connection(); // 実際にはデータベース接続など、動的な処理が入ります
  // cookies, headers, およびその他のDynamic APIも、動的なレンダリングを選択します。
  // つまり、この環境変数は実行時に評価されます。
  const value = process.env.MY_VALUE; // MY_VALUEはNEXT_PUBLIC_なしでもサーバーで利用可能
  // ...
  return <p>Value from server: {value}</p>;
}

このようなサーバーサイドでの動的な値の読み込みは、Next.jsがダイナミックレンダリングを行う際に実行されます。これは、例えばDockerイメージを一つだけ作って複数の環境にデプロイし、それぞれの環境で異なる設定を使いたい場合に非常に便利です。

環境変数のデバッグ 🐛

開発中に環境変数が正しく読み込まれているか確認したい場合は、簡単なconsole.logデバッグが役立ちます。

// サーバーサイドの例 (Route Handlerなど)
console.log('DB_HOST:', process.env.DB_HOST);

// クライアントサイドの例 (React Component)
console.log('Analytics ID:', process.env.NEXT_PUBLIC_ANALYTICS_ID);

もちろん、VS CodeのデバッガーやChrome DevToolsなども利用できますよ。

安全な環境変数管理のヒント 🔐

環境変数は、機密情報を含むことが多いので、取り扱いには注意が必要です。

  • .gitignoreに追加する: .env*ファイルは、必ず.gitignoreファイルに追加して、Gitリポジトリにコミットされないようにしましょう。うっかり公開してしまったら大変なことになりますよ！

  • 本番環境での設定: デプロイ時には、Vercelなどのホスティングサービスが提供する環境変数設定機能を利用するか、Node.jsサーバーやDockerコンテナに直接環境変数を設定してください。

まとめ：環境変数でNext.jsアプリをもっと賢く！🚀

お疲れ様でした！Next.jsの環境変数について、深く掘り下げてきましたね。

この記事で学んだことをまとめると、次のようになります。

  • 環境変数は、アプリケーションの動作を環境に応じて切り替えたり、秘密の情報を安全に管理したりするための「裏設定」です。
  • Next.jsは、.envファイルから環境変数を自動で読み込んでくれます。
  • .envファイルには優先順位があり、特定の環境やローカル専用の設定も可能です。
  • NEXT_PUBLIC_プレフィックスを付けることで、クライアントサイドでも環境変数を利用できますが、これらはビルド時にインライン化されるため、デプロイ後の変更はできません。
  • サーバーサイドでは、NEXT_PUBLIC_なしで環境変数を直接読み込むことができ、これは動的なレンダリング時に活用されます。
  • セキュリティのために、.envファイルは必ず.gitignoreに追加しましょう！

これであなたも、Next.jsアプリケーションの環境変数をスマートに、そして安全に管理できるようになりましたね！🙌 実際に手を動かして、開発環境と本番環境で表示されるメッセージを変えてみたり、APIキーを環境変数に置き換えてみたりすると、さらに理解が深まるはずです。

Discussion