Astro の環境変数・秘密情報管理：.env とエッジ環境の安全設計

2025年10月25日

Astro

Astro でアプリケーションを開発する際、API キーやデータベース接続情報などの秘密情報を安全に管理することは非常に重要です。本記事では、Astro における環境変数の基本から、エッジ環境での安全な設計パターンまでを段階的に解説します。環境変数を正しく扱うことで、セキュリティリスクを最小限に抑えながら、開発からデプロイまでスムーズに進められるようになります。

本記事を読むことで、.env ファイルの使い方、クライアント・サーバー環境での変数の使い分け、エッジランタイムにおける注意点など、実践的な知識が身につくでしょう。

背景

環境変数が必要な理由

Web アプリケーション開発では、外部 API との連携やデータベースアクセスなど、さまざまな場面で認証情報や設定値が必要になります。これらの情報をソースコードに直接書き込むと、Git リポジトリに誤ってコミットしてしまい、情報漏洩のリスクが高まります。

環境変数を使うことで、以下のメリットが得られます。

セキュリティの向上: 秘密情報をコードから分離できる
環境ごとの設定切り替え: 開発、ステージング、本番で異なる値を使える
チーム開発の効率化: 各開発者が自分の環境に合わせた設定を持てる

Astro における環境変数の特徴

Astro は、ビルド時に静的サイトを生成する SSG（Static Site Generation）だけでなく、SSR（Server-Side Rendering）やエッジ環境でのレンダリングもサポートしています。この柔軟性により、環境変数の扱い方も実行環境によって変わってきます。

下図は Astro アプリケーションにおける環境変数の基本的な流れを示しています。

mermaidflowchart TB
  envFile[".env ファイル"] -->|読み込み| astro["Astro アプリ"]
  astro -->|ビルド時| build["ビルドプロセス"]
  build -->|PUBLIC_* 変数| client["クライアント<br/>(ブラウザ)"]
  build -->|通常変数| server["サーバー/エッジ<br/>(ランタイム)"]

  style client fill:#e1f5ff
  style server fill:#fff4e1
  style envFile fill:#f0f0f0

この図から、環境変数が .env ファイルから読み込まれ、ビルド時に適切な環境へ振り分けられることがわかります。

課題

セキュリティリスク

環境変数を扱う際、最も重要な課題はセキュリティです。以下のようなリスクが存在します。

クライアント側への露出: API キーなどの秘密情報がブラウザに送信されてしまう
環境変数の誤った公開: PUBLIC_ プレフィックスの誤用により機密情報が公開される
Git への誤コミット: .env ファイルをバージョン管理に含めてしまう

環境ごとの設定管理

開発環境、ステージング環境、本番環境でそれぞれ異なる設定が必要になります。これらを適切に管理しないと、以下の問題が発生します。

開発環境の API キーを本番で使ってしまう
環境ごとの設定ファイルが乱立し、管理が煩雑になる
デプロイ時に設定の切り替えを忘れる

エッジランタイムの制約

Cloudflare Workers や Vercel Edge Functions などのエッジ環境では、Node.js の全機能が使えないため、環境変数へのアクセス方法も制限されます。

下図は、エッジ環境での環境変数アクセスの課題を示しています。

mermaidflowchart LR
  traditional["従来の<br/>Node.js 環境"] -->|process.env| vars["環境変数"]
  edge["エッジ<br/>ランタイム"] -->|制限あり| limited["限定的な<br/>アクセス"]

  vars -.->|すべて利用可能| ok["✓ 完全アクセス"]
  limited -.->|一部制限| warning["⚠ プラットフォーム<br/>固有の方法が必要"]

  style traditional fill:#e8f5e9
  style edge fill:#fff3e0
  style warning fill:#ffebee

エッジ環境では、プラットフォームごとに異なる環境変数アクセス方法を理解する必要があります。

解決策

.env ファイルの基本設定

Astro は .env ファイルから環境変数を自動的に読み込みます。まずは基本的な .env ファイルの作成方法から始めましょう。

プロジェクトルートに .env ファイルを作成します。このファイルには秘密情報を記載するため、必ず .gitignore に含めてください。

env# サーバー側のみで使用する変数（秘密情報）
DATABASE_URL=mysql://user:password@localhost:3306/mydb
API_SECRET_KEY=your-secret-api-key-here

# クライアント側でも使用する変数（公開情報）
PUBLIC_API_ENDPOINT=https://api.example.com
PUBLIC_SITE_NAME=My Astro Site

このコードでは、2 種類の環境変数を定義しています。PUBLIC_ プレフィックスがない変数はサーバー側でのみ使用され、プレフィックス付きの変数はクライアント側でも利用できます。

次に、.gitignore ファイルに .env を追加して、Git リポジトリにコミットされないようにします。

gitignore# 環境変数ファイルを除外
.env
.env.local
.env.*.local

この設定により、秘密情報が誤ってリポジトリに含まれることを防げます。

環境変数の型安全な利用

TypeScript を使用している場合、環境変数に型定義を追加することで、より安全に扱えます。

src/env.d.ts ファイルを作成して、環境変数の型を定義します。

typescript/// <reference types="astro/client" />

interface ImportMetaEnv {
  readonly DATABASE_URL: string;
  readonly API_SECRET_KEY: string;
  readonly PUBLIC_API_ENDPOINT: string;
  readonly PUBLIC_SITE_NAME: string;
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}

この型定義により、存在しない環境変数にアクセスしようとした際に、TypeScript がエラーを検出してくれます。

実際に環境変数を使用する際は、import.meta.env を通じてアクセスします。

typescript// サーバー側コンポーネント（.astro ファイルの frontmatter 部分）での使用例
---
// データベース接続（サーバー側のみ）
const dbUrl = import.meta.env.DATABASE_URL;

// 公開 API エンドポイント（クライアント側でも使用可能）
const apiEndpoint = import.meta.env.PUBLIC_API_ENDPOINT;
---

<div>
  <p>API エンドポイント: {apiEndpoint}</p>
</div>

このコードでは、サーバー側の frontmatter 部分で環境変数にアクセスしています。PUBLIC_ プレフィックスがある変数は、テンプレート内でも安全に使用できます。

サーバーサイドでの秘密情報の扱い

秘密情報はサーバーサイドでのみ使用し、クライアント側に送信しないことが重要です。API Routes や Server Endpoints を活用しましょう。

src/pages/api/data.ts に API エンドポイントを作成します。

typescriptimport type { APIRoute } from 'astro';

export const GET: APIRoute = async ({ request }) => {
  // サーバー側のみで使用する秘密情報
  const apiKey = import.meta.env.API_SECRET_KEY;

  try {
    // 外部 API への安全なリクエスト
    const response = await fetch(
      'https://external-api.example.com/data',
      {
        headers: {
          Authorization: `Bearer ${apiKey}`,
          'Content-Type': 'application/json',
        },
      }
    );

    const data = await response.json();

    return new Response(JSON.stringify(data), {
      status: 200,
      headers: {
        'Content-Type': 'application/json',
      },
    });
  } catch (error) {
    return new Response(
      JSON.stringify({ error: 'データ取得に失敗しました' }),
      {
        status: 500,
        headers: {
          'Content-Type': 'application/json',
        },
      }
    );
  }
};

このコードでは、API キーをサーバー側で使用し、クライアントには結果のデータのみを返しています。秘密情報が外部に漏れることはありません。

クライアント側からは、この API エンドポイントを呼び出すだけで済みます。

typescript// クライアント側のコード（.astro ファイルの script 部分や React コンポーネント）
async function fetchData() {
  try {
    const response = await fetch('/api/data');
    const data = await response.json();
    return data;
  } catch (error) {
    console.error('データ取得エラー:', error);
    return null;
  }
}

このパターンにより、秘密情報を安全に保ちながら外部 API と連携できます。

環境ごとの設定ファイル管理

開発、ステージング、本番環境でそれぞれ異なる設定を使う場合、複数の .env ファイルを用意します。

Astro は以下の優先順位で環境変数ファイルを読み込みます。

#	ファイル名	用途	優先度
1	`.env.production.local`	本番環境のローカル設定	★★★★★
2	`.env.production`	本番環境の共通設定	★★★★
3	`.env.development.local`	開発環境のローカル設定	★★★
4	`.env.development`	開発環境の共通設定	★★
5	`.env.local`	すべての環境のローカル設定	★
6	`.env`	すべての環境の基本設定	-

実際のプロジェクトでは、以下のような構成をお勧めします。

.env.example ファイルを作成して、必要な環境変数のテンプレートを提供します。

env# .env.example (Git にコミット可能)
# 開発者はこのファイルをコピーして .env を作成してください

DATABASE_URL=
API_SECRET_KEY=
PUBLIC_API_ENDPOINT=
PUBLIC_SITE_NAME=

このファイルは秘密情報を含まないため、Git リポジトリにコミットしても安全です。新しい開発者がプロジェクトに参加した際の参考になります。

.env.development には開発環境用の設定を記載します。

env# .env.development (Git にコミット可能、開発環境用の公開設定)
PUBLIC_API_ENDPOINT=http://localhost:3000/api
PUBLIC_SITE_NAME=My Astro Site (Dev)
PUBLIC_DEBUG_MODE=true

.env.production には本番環境用の設定を記載します。

env# .env.production (Git にコミット可能、本番環境用の公開設定)
PUBLIC_API_ENDPOINT=https://api.mysite.com
PUBLIC_SITE_NAME=My Astro Site
PUBLIC_DEBUG_MODE=false

秘密情報は .env.local や環境固有の .local ファイルに記載します。

env# .env.local (Git にコミットしない、秘密情報を含む)
DATABASE_URL=mysql://user:password@localhost:3306/mydb
API_SECRET_KEY=your-secret-api-key-here

エッジ環境での安全な設計

エッジランタイムでは、環境変数へのアクセス方法がプラットフォームによって異なります。主要なプラットフォームでの対応方法を見ていきましょう。

Vercel Edge Functions

Vercel Edge Functions では、process.env が使用できます。ただし、環境変数は Vercel のダッシュボードから設定する必要があります。

typescript// src/middleware.ts (Vercel Edge Functions での例)
import type { MiddlewareHandler } from 'astro';

export const onRequest: MiddlewareHandler = async (
  { request, locals },
  next
) => {
  // Vercel Edge では process.env が使用可能
  const apiKey = process.env.API_SECRET_KEY;

  if (!apiKey) {
    return new Response('設定エラー', { status: 500 });
  }

  // locals に環境変数を格納して、他の場所で使用
  locals.apiKey = apiKey;

  return next();
};

このコードでは、ミドルウェアで環境変数を読み込み、locals オブジェクトに格納しています。これにより、ページやエンドポイントからアクセスできます。

Cloudflare Workers

Cloudflare Workers では、env オブジェクトを通じて環境変数にアクセスします。

Astro の設定ファイルで Cloudflare アダプターを使用します。

typescript// astro.config.mjs
import { defineConfig } from 'astro/config';
import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
  output: 'server',
  adapter: cloudflare({
    mode: 'directory',
  }),
});

この設定により、Cloudflare Workers 環境でのデプロイが可能になります。

API エンドポイントでは、context.env から環境変数にアクセスします。

typescript// src/pages/api/worker-data.ts
import type { APIRoute } from 'astro';

export const GET: APIRoute = async ({ locals }) => {
  // Cloudflare Workers では locals.runtime.env から環境変数にアクセス
  const runtime = locals.runtime as {
    env: {
      API_SECRET_KEY: string;
      DATABASE_URL: string;
    };
  };

  const apiKey = runtime.env.API_SECRET_KEY;

  try {
    const response = await fetch(
      'https://api.example.com/data',
      {
        headers: {
          Authorization: `Bearer ${apiKey}`,
        },
      }
    );

    const data = await response.json();
    return new Response(JSON.stringify(data), {
      status: 200,
      headers: { 'Content-Type': 'application/json' },
    });
  } catch (error) {
    return new Response(
      JSON.stringify({ error: 'エラーが発生しました' }),
      {
        status: 500,
        headers: { 'Content-Type': 'application/json' },
      }
    );
  }
};

Cloudflare Workers では、環境変数は Cloudflare ダッシュボードの「Workers & Pages」セクションから設定します。

バリデーションとエラーハンドリング

環境変数が正しく設定されているか確認するため、バリデーション処理を追加することをお勧めします。

src/utils/env.ts にバリデーション関数を作成します。

typescript// 必須環境変数のバリデーション
export function validateEnv() {
  const requiredEnvVars = [
    'DATABASE_URL',
    'API_SECRET_KEY',
    'PUBLIC_API_ENDPOINT',
  ];

  const missingVars: string[] = [];

  for (const varName of requiredEnvVars) {
    if (!import.meta.env[varName]) {
      missingVars.push(varName);
    }
  }

  if (missingVars.length > 0) {
    throw new Error(
      `必須の環境変数が設定されていません: ${missingVars.join(
        ', '
      )}`
    );
  }
}

このバリデーション関数は、必須の環境変数がすべて設定されているかチェックし、不足している場合はエラーを投げます。

型安全な環境変数アクセスのためのヘルパー関数も作成します。

typescript// 環境変数の安全な取得
export function getEnv(key: keyof ImportMetaEnv): string {
  const value = import.meta.env[key];

  if (value === undefined) {
    throw new Error(`環境変数 ${key} が設定されていません`);
  }

  return value;
}

// オプショナルな環境変数の取得（デフォルト値あり）
export function getEnvWithDefault(
  key: keyof ImportMetaEnv,
  defaultValue: string
): string {
  return import.meta.env[key] ?? defaultValue;
}

これらのヘルパー関数により、環境変数へのアクセスがより安全になります。

アプリケーションの起動時にバリデーションを実行します。

typescript// src/pages/index.astro
---
import { validateEnv } from '../utils/env';

// 開発環境でのみバリデーションを実行
if (import.meta.env.DEV) {
  try {
    validateEnv();
  } catch (error) {
    console.error('環境変数エラー:', error);
    throw error;
  }
}
---

<html>
  <head>
    <title>My Astro Site</title>
  </head>
  <body>
    <h1>Welcome</h1>
  </body>
</html>

このコードは、開発環境でアプリケーションを起動した際に、必須の環境変数がすべて設定されているか確認します。

具体例

実践的なプロジェクト構成

実際のプロジェクトで環境変数を管理する際の全体像を見ていきましょう。以下は、外部 API と連携する Astro プロジェクトの例です。

まず、プロジェクトの構成を整理します。

bashmy-astro-project/
├── .env.example          # 環境変数のテンプレート（Git にコミット）
├── .env                  # ローカル環境の秘密情報（Git 除外）
├── .env.development      # 開発環境の公開設定（Git にコミット可）
├── .env.production       # 本番環境の公開設定（Git にコミット可）
├── .gitignore            # Git 除外設定
├── astro.config.mjs      # Astro 設定
├── src/
│   ├── env.d.ts          # 環境変数の型定義
│   ├── utils/
│   │   └── env.ts        # 環境変数ユーティリティ
│   ├── pages/
│   │   ├── index.astro   # トップページ
│   │   └── api/
│   │       └── posts.ts  # API エンドポイント
│   └── components/
│       └── PostList.astro
└── package.json

この構成により、環境変数を体系的に管理できます。

ケーススタディ：ブログ記事取得システム

外部 CMS から記事を取得して表示するシステムを例に、実装の流れを見ていきます。

下図は、ブログ記事取得システムの全体フローを示しています。

mermaidsequenceDiagram
  participant Browser as ブラウザ
  participant Page as Astro ページ
  participant API as API Route
  participant CMS as 外部 CMS

  Browser->>Page: ページアクセス
  Page->>API: /api/posts にリクエスト
  API->>API: 環境変数から<br/>API キー取得
  API->>CMS: 認証付きリクエスト
  CMS-->>API: 記事データ (JSON)
  API-->>Page: 記事データ
  Page-->>Browser: HTML レンダリング

  Note over API,CMS: API キーはサーバー側のみで使用

このフローから、API キーがサーバー側でのみ使用され、クライアントには送信されないことがわかります。

ステップ 1: 環境変数の定義

.env.example に必要な変数のテンプレートを作成します。

env# CMS API 設定
CMS_API_URL=
CMS_API_KEY=

# 公開設定
PUBLIC_SITE_URL=
PUBLIC_POSTS_PER_PAGE=10

.env.development に開発環境用の設定を記載します。

env# 開発環境設定
PUBLIC_SITE_URL=http://localhost:4321
PUBLIC_POSTS_PER_PAGE=5
PUBLIC_ENABLE_DEBUG=true

.env.local に秘密情報を記載します（Git にコミットしない）。

env# ローカル環境の秘密情報
CMS_API_URL=https://cms.example.com/api
CMS_API_KEY=your-development-api-key-here

ステップ 2: 型定義の作成

src/env.d.ts に環境変数の型を定義します。

typescript/// <reference types="astro/client" />

interface ImportMetaEnv {
  readonly CMS_API_URL: string;
  readonly CMS_API_KEY: string;
  readonly PUBLIC_SITE_URL: string;
  readonly PUBLIC_POSTS_PER_PAGE: string;
  readonly PUBLIC_ENABLE_DEBUG?: string;
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}

この型定義により、TypeScript の補完とエラー検出が有効になります。

ステップ 3: ユーティリティ関数の作成

src/utils/env.ts に環境変数を扱うヘルパー関数を作成します。

typescript// 環境変数の取得と検証
export function getRequiredEnv(
  key: keyof ImportMetaEnv
): string {
  const value = import.meta.env[key];

  if (!value) {
    throw new Error(
      `環境変数 ${key} が設定されていません。.env ファイルを確認してください。`
    );
  }

  return value;
}

// 数値型の環境変数を取得
export function getEnvAsNumber(
  key: keyof ImportMetaEnv,
  defaultValue: number
): number {
  const value = import.meta.env[key];

  if (!value) {
    return defaultValue;
  }

  const parsed = parseInt(value, 10);

  if (isNaN(parsed)) {
    console.warn(
      `環境変数 ${key} の値 "${value}" を数値に変換できません。デフォルト値 ${defaultValue} を使用します。`
    );
    return defaultValue;
  }

  return parsed;
}

// ブール型の環境変数を取得
export function getEnvAsBoolean(
  key: keyof ImportMetaEnv,
  defaultValue: boolean = false
): boolean {
  const value = import.meta.env[key];

  if (!value) {
    return defaultValue;
  }

  return value.toLowerCase() === 'true' || value === '1';
}

これらの関数により、環境変数を型安全に扱えるようになります。

ステップ 4: CMS クライアントの実装

src/utils/cms-client.ts に CMS との通信を担当するクライアントを作成します。

typescriptimport { getRequiredEnv } from './env';

// 記事の型定義
export interface Post {
  id: string;
  title: string;
  content: string;
  publishedAt: string;
  author: string;
}

// CMS レスポンスの型
interface CMSResponse {
  posts: Post[];
  total: number;
}

CMS からデータを取得する関数を実装します。

typescript// CMS から記事を取得
export async function fetchPosts(
  limit: number = 10
): Promise<Post[]> {
  const apiUrl = getRequiredEnv('CMS_API_URL');
  const apiKey = getRequiredEnv('CMS_API_KEY');

  try {
    const response = await fetch(
      `${apiUrl}/posts?limit=${limit}`,
      {
        headers: {
          Authorization: `Bearer ${apiKey}`,
          'Content-Type': 'application/json',
        },
      }
    );

    if (!response.ok) {
      throw new Error(
        `CMS API エラー: ${response.status} ${response.statusText}`
      );
    }

    const data: CMSResponse = await response.json();
    return data.posts;
  } catch (error) {
    console.error('記事の取得に失敗しました:', error);
    throw error;
  }
}

このクライアントは、環境変数から API 情報を取得し、安全に外部 CMS と通信します。

特定の記事を取得する関数も追加します。

typescript// 単一記事の取得
export async function fetchPostById(
  id: string
): Promise<Post | null> {
  const apiUrl = getRequiredEnv('CMS_API_URL');
  const apiKey = getRequiredEnv('CMS_API_KEY');

  try {
    const response = await fetch(`${apiUrl}/posts/${id}`, {
      headers: {
        Authorization: `Bearer ${apiKey}`,
        'Content-Type': 'application/json',
      },
    });

    if (response.status === 404) {
      return null;
    }

    if (!response.ok) {
      throw new Error(`CMS API エラー: ${response.status}`);
    }

    const post: Post = await response.json();
    return post;
  } catch (error) {
    console.error(
      `記事 ID ${id} の取得に失敗しました:`,
      error
    );
    return null;
  }
}

ステップ 5: API エンドポイントの作成

src/pages/api/posts.ts に API ルートを作成します。

typescriptimport type { APIRoute } from 'astro';
import { fetchPosts } from '../../utils/cms-client';
import { getEnvAsNumber } from '../../utils/env';

export const GET: APIRoute = async ({ url }) => {
  try {
    // クエリパラメータから取得件数を決定
    const limitParam = url.searchParams.get('limit');
    const defaultLimit = getEnvAsNumber(
      'PUBLIC_POSTS_PER_PAGE',
      10
    );
    const limit = limitParam
      ? parseInt(limitParam, 10)
      : defaultLimit;

    // CMS から記事を取得
    const posts = await fetchPosts(limit);

    return new Response(JSON.stringify(posts), {
      status: 200,
      headers: {
        'Content-Type': 'application/json',
        'Cache-Control': 'public, max-age=300', // 5分間キャッシュ
      },
    });
  } catch (error) {
    return new Response(
      JSON.stringify({
        error: '記事の取得に失敗しました',
        message:
          error instanceof Error
            ? error.message
            : 'Unknown error',
      }),
      {
        status: 500,
        headers: {
          'Content-Type': 'application/json',
        },
      }
    );
  }
};

このエンドポイントは、CMS から記事を取得し、クライアントに JSON として返します。API キーはサーバー側でのみ使用されます。

ステップ 6: ページコンポーネントの実装

src/components/PostList.astro に記事一覧コンポーネントを作成します。

astro---
import type { Post } from '../utils/cms-client';

interface Props {
  posts: Post[];
}

const { posts } = Astro.props;
---

<div class="post-list">
  {posts.length === 0 ? (
    <p class="no-posts">記事が見つかりませんでした。</p>
  ) : (
    posts.map((post) => (
      <article class="post-card">
        <h2>{post.title}</h2>
        <p class="meta">
          {post.author} · {new Date(post.publishedAt).toLocaleDateString('ja-JP')}
        </p>
        <p class="excerpt">{post.content.slice(0, 150)}...</p>
        <a href={`/posts/${post.id}`} class="read-more">続きを読む</a>
      </article>
    ))
  )}
</div>

<style>
  .post-list {
    display: grid;
    gap: 2rem;
    max-width: 800px;
    margin: 0 auto;
  }

  .post-card {
    padding: 1.5rem;
    border: 1px solid #e0e0e0;
    border-radius: 8px;
  }

  .post-card h2 {
    margin: 0 0 0.5rem;
    color: #333;
  }

  .meta {
    color: #666;
    font-size: 0.9rem;
    margin-bottom: 1rem;
  }

  .excerpt {
    color: #444;
    line-height: 1.6;
  }

  .read-more {
    color: #0066cc;
    text-decoration: none;
  }

  .no-posts {
    text-align: center;
    color: #666;
  }
</style>

このコンポーネントは、記事データを受け取って一覧表示します。

src/pages/index.astro でトップページを作成します。

astro---
import PostList from '../components/PostList.astro';
import { fetchPosts } from '../utils/cms-client';
import { getEnvAsNumber } from '../utils/env';

// サーバーサイドで記事を取得
const postsPerPage = getEnvAsNumber('PUBLIC_POSTS_PER_PAGE', 10);

let posts;
let error;

try {
  posts = await fetchPosts(postsPerPage);
} catch (e) {
  error = e;
  posts = [];
}
---

<html lang="ja">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width" />
    <title>ブログ記事一覧</title>
  </head>
  <body>
    <main>
      <h1>最新記事</h1>

      {error && (
        <div class="error">
          記事の読み込みに失敗しました。しばらく経ってから再度お試しください。
        </div>
      )}

      <PostList posts={posts} />
    </main>
  </body>
</html>

<style>
  main {
    padding: 2rem;
    font-family: system-ui, sans-serif;
  }

  h1 {
    text-align: center;
    margin-bottom: 2rem;
    color: #222;
  }

  .error {
    background-color: #fee;
    border: 1px solid #fcc;
    padding: 1rem;
    border-radius: 4px;
    color: #c33;
    margin-bottom: 2rem;
  }
</style>

このページでは、サーバーサイドで記事を取得し、PostList コンポーネントに渡して表示します。

デバッグモードの実装

開発時に環境変数の値を確認できるデバッグモードを実装すると便利です。

src/components/EnvDebug.astro にデバッグコンポーネントを作成します。

astro---
import { getEnvAsBoolean } from '../utils/env';

// デバッグモードが有効な場合のみ表示
const isDebugMode = getEnvAsBoolean('PUBLIC_ENABLE_DEBUG', false);

// 公開可能な環境変数のみ表示
const publicEnvVars = {
  PUBLIC_SITE_URL: import.meta.env.PUBLIC_SITE_URL,
  PUBLIC_POSTS_PER_PAGE: import.meta.env.PUBLIC_POSTS_PER_PAGE,
  PUBLIC_ENABLE_DEBUG: import.meta.env.PUBLIC_ENABLE_DEBUG,
  MODE: import.meta.env.MODE,
  DEV: import.meta.env.DEV,
  PROD: import.meta.env.PROD
};
---

{isDebugMode && (
  <div class="env-debug">
    <h3>環境変数デバッグ情報</h3>
    <table>
      <thead>
        <tr>
          <th>変数名</th>
          <th>値</th>
        </tr>
      </thead>
      <tbody>
        {Object.entries(publicEnvVars).map(([key, value]) => (
          <tr>
            <td><code>{key}</code></td>
            <td>{value ?? '(未設定)'}</td>
          </tr>
        ))}
      </tbody>
    </table>
    <p class="warning">
      ⚠ このデバッグ情報は開発環境でのみ表示されます
    </p>
  </div>
)}

<style>
  .env-debug {
    position: fixed;
    bottom: 1rem;
    right: 1rem;
    background: #f9f9f9;
    border: 2px solid #333;
    padding: 1rem;
    border-radius: 4px;
    max-width: 400px;
    font-size: 0.85rem;
    box-shadow: 0 2px 8px rgba(0,0,0,0.1);
    z-index: 9999;
  }

  .env-debug h3 {
    margin: 0 0 0.5rem;
    font-size: 1rem;
  }

  .env-debug table {
    width: 100%;
    border-collapse: collapse;
    margin-bottom: 0.5rem;
  }

  .env-debug th,
  .env-debug td {
    padding: 0.25rem;
    text-align: left;
    border-bottom: 1px solid #ddd;
  }

  .env-debug code {
    background: #eee;
    padding: 2px 4px;
    border-radius: 2px;
  }

  .warning {
    margin: 0.5rem 0 0;
    color: #c60;
    font-size: 0.8rem;
  }
</style>

このデバッグコンポーネントを使用すると、開発環境で環境変数の値を簡単に確認できます。秘密情報は決して表示しないよう注意してください。

エラーハンドリングのベストプラクティス

環境変数に関連するエラーを適切にハンドリングすることで、問題の特定が容易になります。

src/utils/error-handler.ts にエラーハンドリング用のユーティリティを作成します。

typescript// 環境変数エラーの詳細な処理
export class EnvError extends Error {
  constructor(
    public readonly varName: string,
    public readonly reason: string
  ) {
    super(`環境変数エラー: ${varName} - ${reason}`);
    this.name = 'EnvError';
  }
}

// エラーの詳細情報を取得
export function getErrorDetails(error: unknown): {
  message: string;
  type: string;
  details?: string;
} {
  if (error instanceof EnvError) {
    return {
      message: error.message,
      type: 'EnvError',
      details: `変数名: ${error.varName}, 理由: ${error.reason}`,
    };
  }

  if (error instanceof Error) {
    return {
      message: error.message,
      type: error.name,
    };
  }

  return {
    message: '不明なエラーが発生しました',
    type: 'Unknown',
  };
}

このエラーハンドリング機構により、環境変数関連の問題を素早く特定できます。

実際のアプリケーションでエラーハンドリングを使用する例です。

typescript// src/pages/api/protected-data.ts
import type { APIRoute } from 'astro';
import { getRequiredEnv } from '../../utils/env';
import {
  EnvError,
  getErrorDetails,
} from '../../utils/error-handler';

export const GET: APIRoute = async () => {
  try {
    const apiKey = getRequiredEnv('CMS_API_KEY');

    // API 処理...

    return new Response(JSON.stringify({ success: true }), {
      status: 200,
      headers: { 'Content-Type': 'application/json' },
    });
  } catch (error) {
    const errorDetails = getErrorDetails(error);

    console.error('API エラー:', errorDetails);

    return new Response(
      JSON.stringify({
        error: errorDetails.message,
        type: errorDetails.type,
      }),
      {
        status: 500,
        headers: { 'Content-Type': 'application/json' },
      }
    );
  }
};