Claude Codeを利用してReact/VueのフロントエンドとPythonバックエンドを横断的に開発している際、環境変数が反映されずにハマったので備忘録として残します。
目次
この記事でわかること
- Claude Codeの/runコマンドにおける環境変数の継承問題
- PythonでのKeyError: ‘API_CONFIG_TOKEN’の回避方法
- React/Vue.js混在環境での適切な環境変数ロード手順
[現象] /run実行時にKeyErrorが発生
Claude CodeのターミナルインターフェースからPythonスクリプトを実行した際、以下のようなエラーに遭遇しました。
Command failed with exit code 1: python script.py
- KeyError: 'API_CONFIG_TOKEN'ホストマシンのターミナルでは正常に動作するのに、Claude Codeのコンテキスト内では環境変数が参照できていない状態です。
[環境] フルスタック開発構成
- AI Agent: Claude Code
- Backend: Python 3.x (dotenv利用)
- Frontend: React / Vue.js
- Config: .envファイルによる環境変数管理
[原因] サブプロセスのシェル環境継承の不備
Claude Codeが /run を実行する際に生成するサブプロセスは、ホストマシンのシェル環境（特にIDEが自動ロードする.envファイルやシェル関数のエイリアス）を完全に継承しない仕様になっています。そのため、ViteやPythonのdotenvが期待する実行コンテキストと乖離が生じ、環境変数が未定義となってしまいます。
[解決策] 環境変数を明示的にロードする
この問題を解決するには、コマンド実行時に明示的に環境変数を渡すか、コード側でパスを厳密に指定する必要があります。
1. コマンドラインでの対策
実行時に .env をロードしてからスクリプトを連結実行します。
# Before
/run python scripts/sync_data.py
# After
/run export $(grep -v '^#' .env | xargs) && python3 scripts/sync_data.py2. Pythonコード内での対策
相対パスではなく、絶対パスで .env を指定することで、Claude Codeの実行ディレクトリに左右されないようにします。
import os
from pathlib import Path
from dotenv import load_dotenv
# プロジェクトルートの.envを絶対パスで指定
env_path = Path(__file__).resolve().parent.parent / '.env'
load_dotenv(dotenv_path=env_path)
api_token = os.environ.get('API_CONFIG_TOKEN')| 解決策 | メリット | デメリット |
|---|---|---|
| コマンド連結 | 既存コードを汚さない | 実行の度に入力が長い |
| python-dotenv修正 | 常に安定して動作する | 絶対パスの指定が必要 |
[まとめ]
Claude Codeでのフルスタック開発において、/run コマンド時の環境変数エラーは避けて通れない道です。「サブプロセスは環境を引き継がない」という前提に立ち、明示的なexportや絶対パスでのdotenvロードを実装しましょう。これでReactやVueとPythonバックエンドを跨いだデバッグもスムーズになります。
