環境変数

環境変数は、アプリケーションコードに直接含めるべきではない構成値や機密データを格納する方法です。これらの変数は通常、APIキー、データベース接続文字列、またはその他の環境固有の設定などのために使用されます。

環境変数の種類

ビルド時

PUBLIC_ という接頭辞が付いた環境変数は、client と server の両方で利用できます。

サーバーサイド

server でのみアクセス可能な環境変数。

重要！ 機密情報（APIキー、シークレット、パスワードなど）を保存するために、build-time 環境変数（つまり、PUBLIC_ で始まる変数）を使用しないでください。これらの変数はブラウザでアクセス可能であり、パブリックデータのみです。

.env.local

# This will only be available when run on the server
API_KEY=secretApiKeyHere
# This will be available everywhere
PUBLIC_API_URL=https://api.example.com

デフォルトの環境変数

QwikCity には、いくつかの環境変数がすぐに使用できるように含まれています。

BASE_URL: string - ページのベース URL を返します。
MODE: string - レンダリングモードを返します。
DEV: boolean - 開発モードであるかどうかを返します。
PROD: boolean - 本番モードであるかどうかを返します。
SSR: boolean - これが SSR でレンダリングされたかどうかを返します。

QwikCity で環境変数にアクセスする推奨方法は、import.meta.env.*（クライアント側）を使用するか、サーバー側で実行する場合は Request オブジェクトを介してアクセスすることです。

process.env は Node.js のみの API であり、できる限り避ける必要があります。

ビルド時変数

ビルド時変数は、Vite によって提供されます。これらは .env ファイルで定義され、ブラウザとサーバー側のコードで使用できます。

ビルド時変数は、ブラウザビルドにハードコードされるため、誰でも簡単に読めるため、パブリックと見なす必要があることに注意してください。

ビルド時変数は、デフォルトで PUBLIC_ という接頭辞が付いており、import.meta.env.PUBLIC_* でアクセスできます。

変数の定義

.env.local

PUBLIC_API_URL=https://api.example.com

使用法

src/routes/index.tsx

import { component$ } from '@builder.io/qwik';
 
export default component$(() => {
  // `import.meta.env.PUBLIC_*` variables can be read anywhere, including browser
  return <div>PUBLIC_API_URL: {import.meta.env.PUBLIC_API_URL}</div>
})

import.meta.env.PUBLIC_* 変数はどこでも読み取ることができますが、クライアントに表示されるため、機密情報を入れないでください。

サーバーサイド変数

サーバーサイド変数は、基本的にサーバーサイドコードでのみ利用可能なランタイム変数です。

これらはビルド時には不明であり、ブラウザでは利用できないため、プライベートと見なすことができます。

本番環境では、サーバーサイド変数の設定はプラットフォームに大きく依存します。ほとんどのプラットフォームでは、ダッシュボードまたは CLI から環境変数を設定できます。詳細については、プラットフォーム (cloudflare, vercel, netlify) のドキュメントを参照してください。

Docker と Fastify の特別な考慮事項:

Docker： Docker では Dockerfile に環境変数を直接含めることができますが、この方法では機密データが公開される可能性があります。より安全な方法は、Docker Compose を使用してこれらの変数をランタイムで管理することです。例：
docker-compose.yml
version: '3.8'
services:
 your-service:
   image: your-image-name
   environment:
     - FOO=BAR
Docker 内の Fastify： .env または .env.local ファイルに配置された環境変数は、Fastify を使用している場合、本番環境で自動的に認識されない場合があります。これらの設定を有効にするには、Fastify アプリケーション内で明示的にロードするか、上記のように Docker の環境管理システム (Docker Compose) を介して渡す必要がある場合があります。

変数の定義

.env.local

DB_PRIVATE_KEY=123456789

.env.local ファイルを git にコミットしないようにしてください。

使用例

サーバーサイド変数には、routeLoader$()、routeAction$()、server$()、および onGet、onPost、onRequest などのエンドポイントハンドラーなど、RequestEvent オブジェクトを公開するサーバー専用 API でのみアクセスできます。

src/routes/index.tsx

import {
  routeLoader$,
  routeAction$,
  server$,
  type RequestEvent,
} from '@builder.io/qwik-city';
 
export const onGet = (requestEvent: RequestEvent) => {
  console.log(requestEvent.env.get('DB_PRIVATE_KEY'));
};
 
export const onPost = (requestEvent: RequestEvent) => {
  console.log(requestEvent.env.get('DB_PRIVATE_KEY'));
};
 
export const useAction = routeAction$(async (_, requestEvent) => {
  console.log(requestEvent.env.get('DB_PRIVATE_KEY'));
});
 
export const useLoader = routeLoader$(async (requestEvent) => {
  console.log(requestEvent.env.get('DB_PRIVATE_KEY'));
});
 
export const serverFunction = server$(function () {
  // `this` is the `RequestEvent` object
  console.log(this.env.get('DB_PRIVATE_KEY'));
});

サーバーフルアーキテクチャでの使用（例：Express）

サーバーフルアーキテクチャで .env 変数にアクセスするには、シングルトンデザインパターンを使用し、プラグインで db を初期化し、必要な場所で getDB を使用してアクセスする必要があります。

src/util/db.ts

let _db!: AppDatabase;
 
export function getDB() {
  // eslint-disable-next-line
  if (!_db) {
    throw new Error('DB not set');
  }
  return _db;
}
 
export async function initializeDbIfNeeded(factory: () => Promise<AppDatabase>) {
  // eslint-disable-next-line
  if (!_db) {
    _db = await factory();
  }
}

src/routes/[email protected]

export const onRequest: RequestHandler = async ({ env }) => {
  const url = env.get('PRIVATE_LIBSQL_DB_URL')!;
  const authToken = env.get('PRIVATE_LIBSQL_DB_API_TOKEN')!;
  await initializeDbIfNeeded(initLibSql(url, authToken));
};

アプリケーションライフサイクル全体での環境変数の管理

現代のアプリケーションでは、環境変数は、ソースコードに機密データをハードコードすることなく、さまざまな環境にわたってアプリケーションの設定と構成を管理する上で重要な役割を果たします。

Qwik Cityアダプターは以下を使用します。

Azure、Cloud Run、Netlify Edge、Node Serverは、ORIGINまたはURLを使用します。
Cloudflare Pagesは、CF_PAGES_URLまたはORIGINを使用します。
Vercelは、VERCEL_URLを使用します。

注：これは環境変数に関する包括的なガイドではなく、サードパーティのホスティングシナリオをすべて網羅しているわけでもありません。これは、さまざまな環境に適用できる洞察を提供することを目的としています。

詳細な説明については、このビデオをご覧ください：https://youtu.be/NPf39RWc8LM

貢献者

このドキュメントの改善にご協力いただいたすべての貢献者に感謝します！