BLOG /

.envの設定ミス4選|改行・変数名・grep・環境リーク

.envの追記で値が壊れる、キーが子プロセスに渡らない、grepで空に見える、.env.localが効かない。4つの症状の原因と回避コマンドを、確かめ方つきで整理します。

.env の事故は、エラーが出ないまま値だけが壊れる。追記した行が前の行にくっつく。キー名が不正でも source は先へ進む。grep で見ると全キーが空に見える。.env.local を直しても別の値が使われる。この4つに共通する確かめ方を、コマンドつきで整理する。

追記すると2つのキーが壊れる:末尾の改行がないファイルへの >>

症状は、追記したキーが読めないうえに、元からあったキーまで壊れること。

printf 'NEW_API_KEY=%s\n' "$KEY" >> ~/.secrets/api-keys.env

原因は >> が改行を補わないこと。ファイル末尾に改行がないと、新しい行は最終行の続きに書かれる。結果は OLD_API_KEY=既存値NEW_API_KEY=新値 という1行になる。

source はこの行でエラーを出さない。変数が1つ増えるだけで、値が「既存値+新キー名+新値」になる。発覚が遅れ、MCP(Model Context Protocol)のようにキーを使うツールの接続失敗として、ずっと先で表に出る。

回避策は、追記の前に末尾を確かめること。

tail -c1 file | od -c
grep -q . file && [ -n "$(tail -c1 file)" ] && echo >> file

1行目は末尾1バイトを表示する。\n なら安全だ。2行目は、末尾に改行がなければ補う。$(...) は末尾の改行を落とすため、中身が残れば「改行なし」と判定できる。

追記後は grep -nE '^NEW_API_KEY=' file で確認する。行頭から独立して出れば成功だ。

ハイフン入りの変数名は source でエラーになり、子プロセスに渡らない

症状は、キーを書いたはずなのにツールが「未設定」と言うこと。原因を探ると、MY-API-KEY= のような行が見つかる。export も付いていない。

シェルの識別子にハイフンは使えない。source はその行で command not found を出す。しかも export がないので、子プロセスには何も渡らない。MCP やスクリプトから見れば、キー未設定と同じだ。

確かめ方には落とし穴がある。

grep -nE '^(export )?[A-Za-z_][A-Za-z0-9_]*=' file

この正規表現は正しい名前だけを拾う。不正な名前の行は、結果から黙って消える。見つけたいものが出力に現れない。

そこで全行を数えて突き合わせる。

grep -cE '^[^=]+=' file
grep -cE '^(export )?[A-Za-z_][A-Za-z0-9_]*=' file

2つの数が合わなければ、不正名が混じっている。追記するときは export KEY= の形にする。名前は英数字とアンダースコアだけで書く。

grep -o で確認すると全キーが空に見える:値の有無を残す確認方法

秘密情報を画面に出したくなくて、こう確認することがある。

grep -o '^[A-Z_]*=' .env.local

-o はマッチした部分だけを出す。つまりキーと = だけだ。値は消える。すると全キーが空に見える。

ここから「CMS は未接続で、モックで動いている」と誤認しやすい。すると、モックの編集がビルドに反映されない理由を、.next キャッシュや同期ドライブのせいにしたくなる。真因は逆のことがある。実 API が使われていて、モックが読まれていない。

出力を絞る意図は正しい。問題は、絞った結果「値の有無」まで落ちたことだ。

値は隠し、有無だけを出す方法がある。

sed -E 's/=.+$/=[値あり]/; s/=$/=[空]/' .env.local
grep -cE '^[^=]+=.+' .env.local

1行目はキーごとに「値あり」か「空」を表示する。2行目は、値が入っている行の数を返す。

編集が反映されないときは、キャッシュより先に「本番データ経路が有効になっていないか」を疑う。

Next.js で .env.local が効かない:親プロセスの環境変数が優先される

症状は少し紛らわしい。dev サーバーがヘッドレス CMS への fetch で 404 を返す。.env.local の中身は正しい。それなのに、実際には別プロジェクトのサービスドメインを叩いている。

原因は優先順位にある。Next.js は、すでに process.env にある値を .env.local より優先する。プレビュー用の常駐ハーネスの環境に、別案件の CMS_SERVICE_DOMAIN と CMS_API_KEY が残っていると、子の dev サーバー全部に継承される。

典型症状はこうだ。curl や単体の node では 200 が返る。dev サーバーだけが 404 になる。

診断の定石は2つある。

  • lib 側に console.error(process.env.XXX) を一時的に入れ、サーバーが見ている実値を出す
  • globalThis.fetch をラップして、実際の fetch URL を出す

遮断は launch.json のコマンドで行う。

bash -lc "unset CMS_SERVICE_DOMAIN CMS_API_KEY; cd '...' && npm run dev"

dev も build も汚染される:env | grep と env -u での切り分け

汚染は dev だけでは済まない。Bash ツールから叩く npm run build も同じ影響を受ける。

症状は Error: fetch API response status: 404。厄介なのは、失敗するページが実行のたびに /news から /artists へと変わることだ。レート制限を疑いたくなる。ビルドログには - Environments: .env.local と出る。つまり、.env.local が効いていないことは、ログから読み取れない。

切り分けは手早い順に進める。

env | grep -i CMS_

この1コマンドで確定する。値が別案件のものなら、curl で同じエンドポイントを叩く。200 が返れば env リークだ。

回避は、変数を外して実行すること。

env -u CMS_SERVICE_DOMAIN -u CMS_API_KEY npm run build

ホスティング側の CI は無関係だ。クリーンな環境で動くので、本番ビルドは通る。ローカルだけの偽の失敗を追っても、時間は戻らない。

4つの事故は、どれも静かに起きる。追記前は末尾を見る。名前は列挙して突き合わせる。確認は値の有無を残す。効かないときは env を見る。

あなたの .env は、いま何行目まで正しく読めているだろうか。他の制作メモは /blog にまとめている。制作の相談は /contact へどうぞ。