Netlifyの環境変数(Environment Variables)設定ガイド完全版

こんにちは、Hodaです。

Netlifyでサイトを運用していると、必ずと言っていいほど直面するのが「APIキーをどこに書けばいいのか」「本番とプレビューで値を分けたい」といった環境変数まわりの悩みです。

ソースコードに直接キーを書き込んでしまい、GitHubにpushした後で青ざめた経験がある方も少なくないはずです。

この記事では、Netlifyの環境変数の基本的な設定方法から、ビルド時に自動で使える読み取り専用の変数、デプロイコンテキストごとに値を切り替える実践テクニックまで、順を追って解説します。

Netlifyの環境変数とは

Netlifyの環境変数は、ビルド時や実行時にアプリケーションから参照できる「サイトのコードには含めない設定値」です。代表的な用途は次のとおりです。

• APIキーやシークレットトークンなどの機密情報
• NODE_VERSIONのようなビルド環境そのものの設定
• 本番・プレビュー・ブランチデプロイなど、環境ごとに変えたい値(フィーチャーフラグなど)

Netlify側で用意されているビルド用の設定変数(後述)を除けば、環境変数は基本的に「宣言(値を登録すること)」と「参照(コードから読み込むこと)」の2ステップで使えるようになります。

環境変数を設定する4つの方法

Netlifyでは環境変数を次の4つの方法で登録できます。

1. 管理画面(UI) — 一番手軽で、Netlifyを使い始めたばかりの人にもおすすめ
2. Netlify CLI — netlify env:set などのコマンドで登録
3. API — CI/CDパイプラインなどから自動で登録したい場合
4. netlify.tomlファイル — リポジトリ内で設定を管理したい場合(※機密情報の登録には不向き)

管理画面(UI)から設定する手順

もっとも一般的なのがこの方法です。

1. app.netlify.comにログインし、対象のプロジェクト(サイト)を開く
2. 左サイドバーの「Project configuration(プロジェクト設定)」を開く
3. 「Environment variables(環境変数)」を選択
4. 「Add a variable」ボタンをクリック
5. キー名と値を入力し、必要であれば「Different value for each deploy context」を選んで、本番・デプロイプレビュー・ブランチデプロイごとに異なる値を設定
6. 「Scopes」で、この変数をどこで使うか(Builds / Functions / Runtime / Post processingなど)を選択
7. 保存すれば完了

補足:環境変数を追加・変更しても、既存のビルドやFunctionには自動で反映されません。次回のデプロイ(再ビルド)以降で有効になる点は覚えておいてください。

例えば僕のとあるプロジェクトでは以下のように外部APIやGoogleシートの webhhok URLを設定しています

.env から一括インポートも可能

ちなみにですが、環境変数が多い場合、 env の内容をそのままコピペで追加することもできます。 Import from a .env file というオプションがあるので、ここにそのまま env の内容を貼り付ければ各行が自動的にそれぞれの値として認識されます。

例） 以下のような形式だと思うので、そのまま貼り付ければOKです

OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx
STRIPE_SECRET_KEY=sk_test_xxxxxxxxxxxxxxxxxxxxxxxx
SENDGRID_API_KEY=SG.xxxxxxxxxxxxxxxxxxxxxxxxx
NOTION_API_KEY=secret_xxxxxxxxxxxxxxxxxxxxx

CLIから設定する

ローカルのターミナルから素早く登録したい場合はCLIが便利です。netlify linkで対象サイトと連携した状態で、次のようなコマンドを使います。

# 変数を1つ設定
netlify env:set API_KEY "sk_test_xxxxxxxxxxxx"

# 現在設定されている変数を一覧表示
netlify env:list

# .envファイルの内容をまとめてインポート
netlify env:import .env

netlify.tomlで設定する場合の注意点

netlify.tomlにも環境変数を書けますが、これはリポジトリにコミットされるファイルです。トークンやAPIキーなどの機密情報は絶対に書かないでください。 「ビルドに使うNode.jsのバージョン」のような、公開されても問題のない設定値に限定して使うのが安全です。

スコープ(Scope)の設定を忘れずに

環境変数にスコープを設定できる場合、そのスコープに必ず「Builds」を含めてください。これが含まれていないと、せっかく登録した変数がビルドプロセスから読み込まれません。「値は設定したのにビルドで使えない」というトラブルの多くは、このスコープ設定の見落としが原因です。

ビルドの挙動を変える設定用環境変数

Netlifyには、値を設定するだけでビルド環境そのものを変更できる予約された環境変数があります。よく使うものを抜粋します。

これらはあくまで一部で、フレームワークごとの細かい変数(Next.jsのNETLIFY_NEXT_PLUGIN_SKIPなど)も用意されています。使っているフレームワークに応じて公式ドキュメントを確認するのがおすすめです。

Netlifyが自動で用意する読み取り専用の変数

自分で登録しなくても、ビルド中は次のような変数が自動的に使えます。値は変更できませんが、ビルドスクリプトやFunctionsの中で条件分岐に使うと便利です。

特にCONTEXTは、後述する「環境ごとに値を切り替えるテクニック」の要になる変数です。

ビルド中に環境変数を使う方法

登録した変数は、場面に応じて次のように参照します。

netlify.tomlのビルドコマンド内

[build]
  command = "npm run build && echo $GREETING"

Node.jsのスクリプトファイル内

const greeting = process.env.GREETING;
console.log(`Hello: ${greeting}`);

Build Plugins内

process.env.VARIABLE_NAME、またはnetlifyConfig経由でアクセスできます。

ビルド後のサイト自体で値を使いたい場合

ビルド用の環境変数は、そのままではビルド後のフロントエンドから参照できません。実行時に値を使いたい場合は、Serverless FunctionsやEdge Functionsを経由するのが安全な方法です。非機密の値であれば、ビルドスクリプトでファイルに値を埋め込む方法もあります。

実践例:「JavaScript heap out of memory」エラーの対処

規模の大きいサイト(ブログの記事数が多い、画像処理が重いなど)をNetlifyでビルドしていると、Allocation failed - JavaScript heap out of memoryというエラーでビルドが失敗することがあります。これはNode.jsのガベージコレクションがメモリの上限に達し、プロセスが強制終了されることで起きる現象です。

Netlifyコミュニティフォーラムでの議論によると、Enterpriseプラン以外のビルド環境ではメモリの上限を大きく超えないよう注意が必要とされています。対処法として、Node.jsに割り当てるメモリの上限を引き上げる環境変数(NODE_OPTIONSに--max-old-space-sizeを指定するなど)を追加する方法が有効です。設定手順自体は先述の「管理画面から設定する手順」と同じで、キーと値を登録して再デプロイするだけです。

大量の記事や画像を扱うサイト運営者にとっては、覚えておいて損のないテクニックです。

環境ごとに値を切り替えるテクニック

本番・デプロイプレビュー・ブランチデプロイのそれぞれで異なるAPIキーを使いたいケースはよくあります。現在のNetlifyでは、環境変数を登録する際に「デプロイコンテキストごとに異なる値を設定する」機能が標準で用意されているため、まずはこの方法を使うのが最もシンプルです。

一方で、この機能が広く使われる前から実践されてきた方法として、CONTEXT変数を使って自前でロジックを組む方法もあります。考え方はシンプルで、CONTEXTの値(productionなど)を変数名の一部として組み込み、実行時に該当する値を動的に取得するというものです。

チーム開発でミスを絶対に防ぎたい場合は後者の考え方を部分的に取り入れるのもありですが、個人サイトや小規模プロジェクトであれば、標準機能で十分なケースがほとんどです。

セキュリティ面で気をつけたいこと

• .envファイルは.gitignoreに入れ、リポジトリにコミットしない
• 機密情報はnetlify.tomlではなく管理画面かCLIで登録する
• スコープは必要最小限に絞る(全部の権限を安易に付与しない)
• 一度リポジトリに履歴として残ってしまったキーは、削除しても意味がないため必ず再発行する

Netlifyのビルドは.envファイルを直接は読み込まない仕様になっているため、ローカルの.envをそのまま本番ビルドに使う設計にしてしまうと、後から思わぬ形で値が食い違うことがあります。ローカル開発用の値と本番用の値は別物として管理する意識を持っておくと安心です。

まとめ

Netlifyの環境変数は、一見地味な機能に見えて、セキュリティとビルドの安定性を左右する重要な設定です。

• 機密情報は管理画面かCLIで登録し、netlify.tomlには書かない
• スコープには必ず「Builds」を含める
• 環境ごとに値を切り替えたい場合は、まず標準機能を試す
• ビルドが重いサイトはメモリ関連の環境変数も選択肢に入れる

Netlify自体の料金体系や基本機能については、Netlifyの特徴と料金を徹底解説の記事も合わせてご覧ください。