【Astro】Astroの環境変数設定

基本的な.envファイルの使い方

まず一番シンプルで一般的なのが、プロジェクトのルートディレクトリに.envファイルを作成する方法です。このファイルにキーと値を書くだけで、簡単に環境変数を設定できます。

# サーバーサイドでのみ利用可能
DB_PASSWORD="your-secret-password"

# PUBLIC_ を付けるとクライアントサイド（ブラウザ）でも利用可能
PUBLIC_API_ENDPOINT="https://api.example.com/v1"

ひとつ重要なルールとして、ブラウザ上で参照したい変数には、必ずPUBLIC_という接頭辞を付ける必要があります。 これを付け忘れると、クライアントサイドのJavaScriptから呼び出せず、少しハマることがあるので注意が必要です。

呼び出す際は、Astroファイル内で import.meta.env を使います。

---
// サーバーサイドでのみ使える
const password = import.meta.env.DB_PASSWORD;
console.log('DBパスワード(サーバーログにのみ表示):', password);

// PUBLIC_ が付いているのでクライアントサイドでも使える
const endpoint = import.meta.env.PUBLIC_API_ENDPOINT;
---
<script define:vars={{ endpoint }}>
  // ブラウザのコンソールに表示される
  console.log('APIエンドポイント:', endpoint);
</script>

忘れてはいけないのが、.envファイルを.gitignoreに追加することです。 これを忘れて秘密情報をリポジトリに公開してしまう事故は絶対に避けなければなりません。

型安全な環境変数の設定（おすすめ）

最近のAstroでは、型安全な環境変数の管理方法が推奨されています。私は新しいプロジェクトでは、基本的にこちらを使うようにしています。設定が少し増えますが、タイプミスを防げたり、補完が効いたりするメリットが大きいです。

まず、astro.config.mjsにenvスキーマを定義します。

import { defineConfig, envField } from 'astro/config';

export default defineConfig({
  env: {
    schema: {
      // サーバーサイドでのみ使える秘密のキー
      DB_PASSWORD: envField.string({
        context: 'server',
        access: 'secret',
      }),
      // クライアントサイドでも使える公開キー
      PUBLIC_API_ENDPOINT: envField.string({
        context: 'client',
        access: 'public',
      }),
    },
  },
});

contextでserverかclientか、accessでsecretかpublicかを指定することで、変数の公開範囲を厳密に管理できます。

この設定の後、astro devを起動するか、astro syncコマンドを実行すると、型定義が自動生成されます。

使うときは、import.meta.envの代わりに、特別なastro:envモジュールからインポートします。

---
// サーバー用の変数をインポート
import { DB_PASSWORD } from "astro:env/server";

// クライアント用の変数をインポート
import { PUBLIC_API_ENDPOINT } from "astro:env/client";

console.log('DBパスワード(サーバーログにのみ表示):', DB_PASSWORD);
---
<h1>APIエンドポイントは {PUBLIC_API_ENDPOINT} です</h1>

まとめ

Astroでの環境変数の設定方法を紹介しました。

• 手軽に始めるなら: .envファイルとimport.meta.env
• 安全性を重視するなら: astro.config.mjsでのスキーマ定義とastro:env

個人的には、新しいプロジェクトであれば最初から型安全な方法で設定するのがおすすめです。どちらの方法を使うにしても、.gitignoreの設定だけは忘れないようにしましょう。