【Vue】環境ごとの環境変数管理（.env）

JavaScript
2023.09.20

こんにちは、かつコーチです。

前回はNetlifyを使ったVueアプリのデプロイ手順を解説しました。

デプロイができるようになると次に出てくるのが、「開発中と本番で、APIの向き先やキーを切り替えたい」という悩みです。

今回は、Vueアプリで環境変数を扱う.envファイルの使い方と、開発・本番で値を切り替える方法を解説します。

環境変数とは？なぜコードに直接書いてはいけないのか

環境変数の定義

環境変数とは、プログラムの外側で管理し、実行環境ごとに値を切り替えられる設定値のことです。

APIのエンドポイントURL、外部サービスのAPIキー、機能フラグなど、「環境によって変えたいけれど、コード自体は変えたくない」情報を扱うのに使います。

コードに直接書いた場合のリスク

APIキーのような秘匿情報をソースコードに直接書いてしまうと、GitHubなどにコードを公開したときや、ビルド後のファイルを誰かが調べたときに、値がそのまま漏えいしてしまいます。

とくにVueのようなフロントエンドのコードは、ビルドしても最終的にブラウザ側で読み込まれるため、「サーバー専用の秘密鍵」のような情報を扱うのには本質的に向いていません。

環境変数の仕組みを正しく理解しておくことは、セキュリティ事故を防ぐうえでも欠かせない知識です。

.envファイルの基本

ファイルの命名ルール

Vite製のVueプロジェクトでは、プロジェクト直下に.envファイルを置くことで環境変数を定義できます。

# .env（すべての環境で共通の値）
VITE_APP_NAME=かつコーチ学習アプリ

# .env.development（開発環境専用）
VITE_API_BASE_URL=http://localhost:8000/api

# .env.production（本番環境専用）
VITE_API_BASE_URL=https://api.example.com/api

npm run devを実行すると.env.developmentが、npm run buildを実行すると.env.productionが、それぞれ.envと合わせて読み込まれます。

ファイル名だけで自動的に環境が切り替わるので、コード側でif文を使って向き先を出し分ける必要がありません。

VITE_プレフィックスが必要な理由

Viteでは、VITE_から始まる名前の変数だけが、ビルド後のフロントエンドコードに埋め込まれる仕組みになっています。

<script setup lang="ts">
const apiUrl: string = import.meta.env.VITE_API_BASE_URL
const appName: string = import.meta.env.VITE_APP_NAME

console.log(apiUrl) // 開発中なら http://localhost:8000/api
</script>

逆に言うと、VITE_が付いていない変数はビルド時に自動で除外され、import.meta.envからはundefinedしか取得できません。

これは事故ではなく、サーバー専用の秘密情報を誤ってフロントエンドに埋め込まないための、意図的な安全装置です。

.envファイルをGit管理から除外する

.gitignoreへの追加

.envファイルは、開発者ごとに異なる値を持つことが多いうえ、うっかり秘匿情報を書いてしまうリスクもあるため、基本的にGitの管理対象から外します。

# .gitignore
.env
.env.local
.env.*.local

代わりに、値の名前だけを共有するための.env.exampleをリポジトリに含めておくのが定番の運用です。

# .env.example（値は空、または仮の値にしておく）
VITE_API_BASE_URL=
VITE_APP_NAME=

新しくプロジェクトに参加したメンバーは、.env.exampleをコピーして.envを作り、自分の環境に合わせて値を埋めるだけで開発を始められます。

型定義でimport.meta.envを補完する

環境変数に型を付ける

TypeScriptを使っていると、import.meta.env.VITE_API_BASE_URLのように書いても、初期状態ではエディタの補完が効きません。

src/env.d.tsのようなファイルに型定義を追加しておくと、タイプミスにも気づきやすくなります。

// src/env.d.ts
interface ImportMetaEnv {
  readonly VITE_API_BASE_URL: string
  readonly VITE_APP_NAME: string
}

interface ImportMeta {
  readonly env: ImportMetaEnv
}

この定義を用意しておくと、import.meta.env.と入力した時点でエディタが候補を出してくれるようになり、存在しない変数名を参照してしまうミスも防げます。

つまずきやすいポイント：VITE_プレフィックスの付け忘れ

かつコーチが実際にハマった「値が読めない」トラブル

私が最初にViteで環境変数を扱ったとき、外部APIのキーを.envに書いたのに、コード側でundefinedしか取得できず、原因が分からず1時間ほど悩んだことがあります。

原因は単純で、VITE_のプレフィックスを付け忘れていたことでした。

❌ Before：VITE_プレフィックスを付けずに定義してしまう

# .env
API_KEY=abcdefg12345

<script setup lang="ts">
const fetchData = () => {
  // ビルド時に除外され、常にundefinedになる
  const apiKey = import.meta.env.API_KEY

  console.log(apiKey) // undefined
}
</script>

Node.js（サーバーサイド）のprocess.envに慣れていると、プレフィックスなしで書く癖がついていて、Viteでも同じ感覚で書いてしまいがちです。

エラーメッセージが出るわけではなく、静かにundefinedが返るだけなので、しばらく気づけませんでした。

✅ After：VITE_プレフィックスを付けて定義する

# .env
VITE_API_KEY=abcdefg12345

<script setup lang="ts">
const fetchData = () => {
  const apiKey: string = import.meta.env.VITE_API_KEY

  console.log(apiKey) // abcdefg12345
}
</script>

Viteで環境変数がうまく読めないときは、まずVITE_が付いているかを確認する、という順番で調べると、原因にたどり着くのが早くなります。

なお、サーバー専用の秘密鍵などフロントエンドに出したくない値は、そもそもVITE_を付けずにビルドプロセス側（サーバーサイドの処理）だけで扱うのが正しい使い方です。

Netlify側での環境変数設定

ダッシュボードからの設定

.env.productionをGit管理から外している場合、本番用の値はNetlifyダッシュボードの「Site settings」→「Environment variables」から個別に登録します。

  • Key：VITE_API_BASE_URL
  • Value：https://api.example.com/api
  • Scopes：Production / Deploy previews / Branch deploysから適用範囲を選択

環境ごとにチェックボックスで適用範囲を選べるため、「本番だけ本物のAPI、プレビュー環境はステージング用のAPI」といった細かい出し分けも可能です。

設定変更後は再デプロイが必要

環境変数を追加・変更した場合、すでにデプロイ済みのビルドには反映されません。

Netlifyダッシュボードから「Trigger deploy」を手動で実行するか、新しいコミットをプッシュして再ビルドを走らせる必要があります。

私も「値を変えたのに反映されない」と焦った経験がありますが、たいていはこの再デプロイ忘れが原因でした。

まとめ

この記事のポイント

  • 環境変数は「環境によって変えたい値」をコードから切り離して管理する仕組み
  • Viteでは.env / .env.development / .env.productionでファイルを使い分ける
  • フロントエンドに埋め込みたい値には必ずVITE_プレフィックスを付ける
  • .envはGit管理から除外し、代わりに.env.exampleで共有する
  • Netlifyでは本番用の値をダッシュボードから設定し、変更後は再デプロイが必要

次に読むべき記事

次回は「Vueでよく出るエラーと解決法まとめ」を解説します。

→ 次の記事：Vueでよく出るエラーと解決法まとめ

タイトルとURLをコピーしました