From 3a652ab56c997d6c1248352f4fd373ac86ae45de Mon Sep 17 00:00:00 2001 From: Shinya Fujino Date: Sat, 20 Jun 2026 17:12:33 +0900 Subject: [PATCH] i18n(ja): update `environment-variables.mdx` and `integrations-guide/node.mdx` --- .../docs/ja/guides/environment-variables.mdx | 352 ++++++++++++++++++ .../ja/guides/integrations-guide/node.mdx | 68 ++-- src/content/docs/ja/guides/upgrade-to/v6.mdx | 2 +- 3 files changed, 385 insertions(+), 37 deletions(-) create mode 100644 src/content/docs/ja/guides/environment-variables.mdx diff --git a/src/content/docs/ja/guides/environment-variables.mdx b/src/content/docs/ja/guides/environment-variables.mdx new file mode 100644 index 0000000000000..7a5a6594f5cc1 --- /dev/null +++ b/src/content/docs/ja/guides/environment-variables.mdx @@ -0,0 +1,352 @@ +--- +title: 環境変数を使う +sidebar: + label: 環境変数 +description: Astroプロジェクトで環境変数を使う方法を学びます。 +i18nReady: true +--- +import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro' +import ReadMore from '~/components/ReadMore.astro'; + +Astroでは、[Viteに組み込まれた環境変数のサポート](#viteの組み込みサポート)を利用できます。また、いくつかの[デフォルト環境変数](#デフォルト環境変数)が用意されており、現在のプロジェクトの設定値（`site`や`base`など）や、プロジェクトが開発・本番のどちらで実行されているかなどにアクセスできます。 + +さらにAstroは、[型安全に環境変数を使い、整理する方法](#型安全な環境変数)も提供しています。これはAstroのコンテキスト内（Astroコンポーネント、ルートやエンドポイント、UIフレームワークコンポーネント、ミドルウェアなど）で利用でき、[Astro設定内のスキーマ](/ja/reference/configuration-reference/#env)で管理します。 + +## Viteの組み込みサポート + +Astroは、Viteに組み込まれた環境変数のサポートを利用します。これらの環境変数はビルド時に静的に置き換えられ、[Viteが提供する環境変数を扱うためのさまざまな機能](https://vite.dev/guide/env-and-mode.html)を利用できます。 + +なお、すべての環境変数はサーバーサイドのコードから利用できますが、セキュリティ上の理由から、クライアントサイドのコードで利用できるのは`PUBLIC_`で始まる環境変数のみです。 + +```ini title=".env" +SECRET_PASSWORD=password123 +PUBLIC_ANYBODY=there +``` + +この例では、`PUBLIC_ANYBODY`（`import.meta.env.PUBLIC_ANYBODY`でアクセス可能）はサーバーコードでもクライアントコードでも利用できますが、`SECRET_PASSWORD`（`import.meta.env.SECRET_PASSWORD`でアクセス可能）はサーバーサイドでのみ利用できます。 + +:::caution +`.env`ファイルは[設定ファイル](#astro設定ファイル内)の中では読み込まれません。 +::: + +### TypeScriptのIntelliSense + +デフォルトでは、Astroは`astro/client.d.ts`内に`import.meta.env`の型定義をあらかじめ用意しています。 + +`.env.[mode]`ファイルでその他のカスタム環境変数を定義できますが、`PUBLIC_`で始まるユーザー定義の環境変数についてTypeScriptのIntelliSenseを効かせたい場合があります。 + +そのためには、`src/`に`env.d.ts`を作成して[グローバルな型を拡張](/ja/guides/typescript/#extending-global-types)し、次のように`ImportMetaEnv`を設定します。 + +```ts title="src/env.d.ts" +interface ImportMetaEnv { + readonly DB_PASSWORD: string; + readonly PUBLIC_POKEAPI: string; + // その他の環境変数... +} + +interface ImportMeta { + readonly env: ImportMetaEnv; +} +``` + +## デフォルト環境変数 + +Astroには、いくつかの環境変数が標準で組み込まれています。 + +- `import.meta.env.MODE`: サイトが実行されているモードです。`astro dev`の実行時は`development`、`astro build`の実行時は`production`になります。 +- `import.meta.env.PROD`: サイトが本番環境で実行されている場合は`true`、それ以外は`false`になります。 +- `import.meta.env.DEV`: サイトが開発環境で実行されている場合は`true`、それ以外は`false`になります。常に`import.meta.env.PROD`の逆の値です。 +- `import.meta.env.BASE_URL`: サイトが配信されるベースURLです。[`base`設定オプション](/ja/reference/configuration-reference/#base)によって決まります。 +- `import.meta.env.SITE`: プロジェクトの`astro.config`で指定された[`site`オプション](/ja/reference/configuration-reference/#site)が設定されます。 + +これらは、他の環境変数と同じように使えます。 + +```ts utils.ts +const isProd = import.meta.env.PROD; +const isDev = import.meta.env.DEV; +``` + +## 環境変数を設定する + +### `.env`ファイル + +環境変数は、プロジェクトディレクトリにある`.env`ファイルから読み込まれます。 + +プロジェクトディレクトリに`.env`ファイルを作成し、変数をいくつか追加してみましょう。 + +```ini title=".env" +# これはサーバー上で実行されるときのみ利用できます！ +DB_PASSWORD="foobar" + +# これはどこでも利用できます！ +PUBLIC_POKEAPI="https://pokeapi.co/api/v2" +``` + +ファイル名に`.production`や`.development`、あるいはカスタムモード名（例: `.env.testing`、`.env.staging`）を加えることもできます。これにより、状況に応じて異なる環境変数のセットを使い分けられます。 + +`astro dev`と`astro build`コマンドは、それぞれデフォルトで`"development"`モードと`"production"`モードになります。これらのコマンドを[`--mode`フラグ](/ja/reference/cli-reference/#--mode-string)付きで実行すると、`mode`に別の値を渡し、対応する`.env`ファイルを読み込めます。 + +これにより、APIの接続先を変えて開発サーバーを起動したり、サイトをビルドしたりできます。 + + + + ```shell + # 「staging」APIに接続した状態で開発サーバーを起動する + npm run astro dev -- --mode staging + + # 「production」APIに接続し、追加のデバッグ情報を含めてサイトをビルドする + npm run astro build -- --devOutput + + # 「testing」APIに接続した状態でサイトをビルドする + npm run astro build -- --mode testing + ``` + + + ```shell + # 「staging」APIに接続した状態で開発サーバーを起動する + pnpm astro dev --mode staging + + # 「production」APIに接続し、追加のデバッグ情報を含めてサイトをビルドする + pnpm astro build --devOutput + + # 「testing」APIに接続した状態でサイトをビルドする + pnpm astro build --mode testing + ``` + + + ```shell + # 「staging」APIに接続した状態で開発サーバーを起動する + yarn astro dev --mode staging + + # 「production」APIに接続し、追加のデバッグ情報を含めてサイトをビルドする + yarn astro build --devOutput + + # 「testing」APIに接続した状態でサイトをビルドする + yarn astro build --mode testing + ``` + + + +`.env`ファイルの詳細については、[Viteのドキュメント](https://vite.dev/guide/env-and-mode.html#env-files)を参照してください。 + +### Astro設定ファイル内 + +Astroは、他のファイルを読み込む前に設定ファイルを評価します。そのため、`astro.config.mjs`内で`import.meta.env`を使って、`.env`ファイルに設定された環境変数にアクセスすることはできません。 + +設定ファイル内では、[CLIで設定した値](#cliを使う)など、その他の環境変数に`process.env`でアクセスできます。 + +また、[Viteの`loadEnv`ヘルパー](https://main.vite.dev/config/#using-environment-variables-in-config)を使って、`.env`ファイルを手動で読み込むことも可能です。 + +```js title="astro.config.mjs" +import { loadEnv } from "vite"; + +const { SECRET_PASSWORD } = loadEnv(process.env.NODE_ENV, process.cwd(), ""); +``` + +:::note +`pnpm`では、プロジェクトに直接インストールされていないモジュールをインポートできません。`pnpm`を使っている場合は、`loadEnv`ヘルパーを使うために`vite`をインストールする必要があります。 + +```sh +pnpm add -D vite +``` +::: + +### CLIを使う + +プロジェクトの実行時に環境変数を追加することもできます。 + + + + ```shell + PUBLIC_POKEAPI=https://pokeapi.co/api/v2 yarn run dev + ``` + + + ```shell + PUBLIC_POKEAPI=https://pokeapi.co/api/v2 npm run dev + ``` + + + ```shell + PUBLIC_POKEAPI=https://pokeapi.co/api/v2 pnpm run dev + ``` + + + +## 環境変数を取得する + +Astroでは、環境変数へのアクセスに`process.env`ではなく、[ES2020で追加された`import.meta`機能](https://tc39.es/ecma262/2020/#prod-ImportMeta)を利用した`import.meta.env`を使います。 + +たとえば、`PUBLIC_POKEAPI`環境変数を取得するには`import.meta.env.PUBLIC_POKEAPI`を使います。 + +```js /(?アダプターを開発していますか？[アダプターを`astro:env`に対応させる方法](/ja/reference/adapter-reference/#envgetsecret)を参照してください。 + +### 基本的な使い方 + +#### スキーマを定義する + +スキーマを設定するには、Astroの設定に`env.schema`オプションを追加します。 + +```js title="astro.config.mjs" ins={4-8} +import { defineConfig } from "astro/config"; + +export default defineConfig({ + env: { + schema: { + // ... + } + } +}) +``` + +続いて、`envField`ヘルパーを使って[変数を文字列、数値、列挙型、真偽値として登録](#データ型)できます。各変数に`context`（`"client"`または`"server"`）と`access`（`"secret"`または`"public"`）を指定して[環境変数の種類](#変数の種類)を定義し、`optional`や`default`といった追加のプロパティをオブジェクトで渡します。 + +```js title="astro.config.mjs" ins="envField" +import { defineConfig, envField } from "astro/config"; + +export default defineConfig({ + env: { + schema: { + API_URL: envField.string({ context: "client", access: "public", optional: true }), + PORT: envField.number({ context: "server", access: "public", default: 4321 }), + API_SECRET: envField.string({ context: "server", access: "secret" }), + } + } +}) +``` + +型は`astro dev`や`astro build`の実行時に自動生成されますが、`astro sync`を実行して型のみを生成することもできます。 + +#### スキーマで定義した変数を使う + +定義した変数を、`/client`または`/server`モジュールからインポートして使います。 + +```astro +--- +import { API_URL } from "astro:env/client"; +import { API_SECRET_TOKEN } from "astro:env/server"; + +const data = await fetch(`${API_URL}/users`, { + method: "GET", + headers: { + "Content-Type": "application/json", + "Authorization": `Bearer ${API_SECRET_TOKEN}` + }, +}) +--- + + +``` + +### 変数の種類 + +環境変数には、スキーマで定義する`context`（`"client"`または`"server"`）と`access`（`"secret"`または`"public"`）の設定の組み合わせによって決まる、3つの種類があります: + +- **パブリックなクライアント変数**: この変数は最終的なクライアントバンドルとサーバーバンドルの両方に含まれ、`astro:env/client`モジュールを通じてクライアントとサーバーの両方からアクセスできます。 + + ```js + import { API_URL } from "astro:env/client"; + ``` + +- **パブリックなサーバー変数**: この変数は最終的なサーバーバンドルに含まれ、`astro:env/server`モジュールを通じてサーバー上でアクセスできます。 + + ```js + import { PORT } from "astro:env/server"; + ``` + +- **シークレットサーバー変数**: この変数は最終的なバンドルには含まれず、`astro:env/server`モジュールを通じてサーバー上でアクセスできます。 + + ```js + import { API_SECRET } from "astro:env/server"; + ``` + + デフォルトでは、`astro:env/server`モジュールから何かがインポートされるたびに、すべてのシークレットが検証されます。つまり、インポートされていないシークレットも検証される場合があります。ビルド時にこの検証を満たすために、[ダミーの環境変数を渡す](#環境変数を設定する)必要があるかもしれません。 + + また、[`validateSecrets: true`を設定](/ja/reference/configuration-reference/#envvalidatesecrets)することで、起動時にシークレットを検証するようにもできます。 + +:::note +**シークレットクライアント変数**は、データを安全にクライアントへ送信する方法がないためサポートされていません。したがって、スキーマで`context: "client"`と`access: "secret"`の両方を設定することはできません。 +::: + +### データ型 + +現在、文字列、数値、列挙型、真偽値の4つのデータ型がサポートされています。 + +```js +import { envField } from "astro/config"; + +envField.string({ + // context と access + optional: true, + default: "foo", +}) + +envField.number({ + // context と access + optional: true, + default: 15, +}) + +envField.boolean({ + // context と access + optional: true, + default: true, +}) + +envField.enum({ + // context と access + values: ["foo", "bar", "baz"], + optional: true, + default: "baz", +}) +``` + +`envField`で指定できる検証用フィールドの完全な一覧については、[`envField` APIリファレンス](/ja/reference/modules/astro-config/#envfield)を参照してください。 + +### シークレットを動的に取得する + +スキーマを定義していても、特定のシークレットの生の値を取得したい場合や、スキーマで定義されていないシークレットを取得したい場合があります。そのような場合は、`astro:env/server`からエクスポートされている`getSecret()`を使えます。 + +```js +import { + FOO, // boolean + getSecret +} from "astro:env/server"; + +getSecret("FOO"); // string | undefined +``` + +詳しくは[APIリファレンス](/ja/reference/modules/astro-env/#getsecret)を参照してください。 + +### 制限事項 + +`astro:env`は仮想モジュールであり、Astroコンテキスト内でのみ使えます。たとえば、以下の場所で使えます。 + +- ミドルウェア +- Astroのルートとエンドポイント +- Astroコンポーネント +- フレームワークコンポーネント +- モジュール + +以下の場所では利用できないため、`process.env`を使う必要があります。 + +- `astro.config.mjs` +- スクリプト diff --git a/src/content/docs/ja/guides/integrations-guide/node.mdx b/src/content/docs/ja/guides/integrations-guide/node.mdx index 5cdf460fd9d78..65c0456e08c83 100644 --- a/src/content/docs/ja/guides/integrations-guide/node.mdx +++ b/src/content/docs/ja/guides/integrations-guide/node.mdx @@ -108,84 +108,80 @@ export default defineConfig({ }); ``` -### `experimentalDisableStreaming` +### `staticHeaders`

**Type:** `boolean`
**Default:** `false`
- +

-オンデマンドでレンダリングされるページの、Astroのデフォルトの[HTMLストリーミング](/ja/guides/on-demand-rendering/#htmlストリーミング)を無効にします。 - -HTMLストリーミングはパフォーマンスに役立ち、一般的にユーザーにより良い体験を提供します。ほとんどの場合、ストリーミングを無効にすることはお勧めできません。 +有効にすると、コンテンツセキュリティポリシーなどのAstroの機能から提供される場合に、アダプターはプリレンダリングされたページのヘッダーを`Response`オブジェクトを使って配信します。 -ただし、HTMLストリーミングを無効にする必要がある場合（たとえば、ホストがCDNレベルでストリーミングされていないHTMLキャッシュのみをサポートしている場合）、デフォルトの動作をオプトアウトできます。 +たとえば、[コンテンツセキュリティポリシー](/ja/reference/configuration-reference/#securitycsp)を有効にしている場合、`staticHeaders`を使うと、``要素を作成する代わりにCSPヘッダーを`Response`オブジェクトに追加できます。 -```js title="astro.config.mjs" {7} +```js title="astro.config.mjs" {10} import { defineConfig } from 'astro/config'; import node from '@astrojs/node'; export default defineConfig({ + security: { + csp: true + }, adapter: node({ mode: 'standalone', - experimentalDisableStreaming: true, - }), + staticHeaders: true, + }) }); ``` -### `experimentalStaticHeaders` +### `experimentalDisableStreaming`

- **Type:** `boolean`
- **Default:** `false`
- +**Type:** `boolean`
+**Default:** `false`
+

-有効にすると、アダプターは、コンテンツセキュリティポリシーなどのAstroの機能によって提供された場合、`Response`オブジェクトを使用して事前レンダリングされたページのヘッダーを提供します。 +オンデマンドレンダリングされるページに対して、Astroのデフォルトの[HTMLストリーミング](/ja/guides/on-demand-rendering/#html-streaming)を無効にします。 -たとえば、[CSP設定](/ja/reference/configuration-reference/)を有効にしている場合、`experimentalStaticHeaders`を使用して、``要素を作成する代わりにCSPヘッダーを`Response`オブジェクトに追加できます。 +HTMLストリーミングはパフォーマンスの向上に役立ち、一般的に訪問者により良い体験を提供します。ほとんどの場合、ストリーミングを無効にすることは推奨されません。 -```js title="astro.config.mjs" {10} +ただし、HTMLストリーミングを無効にする必要がある場合（たとえば、ホスティング環境がCDNレベルで非ストリーミングのHTMLキャッシュのみをサポートしている場合など）は、デフォルトの動作をオプトアウトできます。 + +```js title="astro.config.mjs" {7} import { defineConfig } from 'astro/config'; import node from '@astrojs/node'; export default defineConfig({ - security: { - csp: true - }, adapter: node({ mode: 'standalone', - experimentalStaticHeaders: true, - }) + experimentalDisableStreaming: true, + }), }); ``` -### `experimentalErrorPageHost` +### `bodySizeLimit`

- **Type:** `string | URL`
- **Default:** `undefined`
- +**Type:** `number`
+**Default:** `1073741824` (1 GB)
+

-事前レンダリングされた[カスタムエラーページ](/ja/basics/astro-pages/#カスタム404エラーページ)を読み込むための代替ホストを指定します。 - -Astroがレスポンスで404ページを返すためには、ページを読み込める必要があります。デフォルトでは、Astroはリクエストが送信されたホストと同じホストから事前レンダリングされたカスタムエラーページを読み込みます。たとえば、`https://example.com/nonexistent-page`にリクエストが送信された場合、Astroは`https://example.com/404.html`から事前レンダリングされたエラーページを読み込もうとします。 +リクエストボディの最大許容サイズをバイト単位で設定します。受信したリクエストのボディがこの上限を超えると、ボディの読み取り時にエラーがスローされます。 -`experimentalErrorPageHost`は、カスタムエラーページを別のホストから読み込む必要がある場合に使用します。たとえば、サーバーがリバースプロキシの背後で実行されている場合や、外部ホストURLにアクセスできないコンテナ内で実行されている場合です。また、パブリックインターネットを経由するよりもlocalhostから事前レンダリングされたエラーページを読み込む方が効率的な場合にも使用できます。 +`Infinity`または`0`を設定すると、上限を完全に無効にできます。これは、動画のアップロードなど、非常に大きなリクエストボディを受け付ける必要がある場合に役立ちます。 -値は文字列またはURLオブジェクトです。プロトコルを含む完全修飾URLである必要があります（例：`http://localhost:4321`）。Astroは常にルートパスから事前レンダリングされたエラーページを読み込み、パスやクエリパラメーターは無視されます。 - -```js +```js title="astro.config.mjs" {7} import { defineConfig } from 'astro/config'; import node from '@astrojs/node'; export default defineConfig({ adapter: node({ - // パブリックURLではなくlocalhostからページを読み込みます。 - experimentalErrorPageHost: 'http://localhost:4321', - }) + mode: 'standalone', + bodySizeLimit: 5 * 1024 * 1024 * 1024, // 5 GB + }), }); ``` @@ -302,7 +298,7 @@ Astroは、Nodeアダプターを使用する場合、セッションストレ ## 環境変数 -ランタイムで[`astro:env`](/ja/guides/environment-variables/#type-safe-environment-variables)のシークレットや`process.env`を使用する場合、Astroもアダプターも環境変数を自動的に読み込みません。 +ランタイムで[`astro:env`](/ja/guides/environment-variables/#型安全な環境変数)のシークレットや`process.env`を使用する場合、Astroもアダプターも環境変数を自動的に読み込みません。 一部のホストでは、ダッシュボードで設定した環境変数がビルド時およびランタイムに公開される場合があります。各プラットフォームでの環境変数の設定と使用方法については、ホストのドキュメントを確認してください。 diff --git a/src/content/docs/ja/guides/upgrade-to/v6.mdx b/src/content/docs/ja/guides/upgrade-to/v6.mdx index 00b86fc8b1faa..873af13c6d911 100644 --- a/src/content/docs/ja/guides/upgrade-to/v6.mdx +++ b/src/content/docs/ja/guides/upgrade-to/v6.mdx @@ -262,7 +262,7 @@ export async function getStaticPaths() { --- ``` -[`getStaticPaths()`を使用して静的ルートを動的に生成する](/ja/guides/routing/#static-ssg-mode)際にアクセスできる[`import.meta.env.SITE`などの組み込み環境変数](/ja/guides/environment-variables/#default-environment-variables)の詳細を確認してください。 +[`getStaticPaths()`を使用して静的ルートを動的に生成する](/ja/guides/routing/#static-ssg-mode)際にアクセスできる[`import.meta.env.SITE`などの組み込み環境変数](/ja/guides/environment-variables/#デフォルト環境変数)の詳細を確認してください。 ### 非推奨: `import.meta.env.ASSETS_PREFIX`