From 2da8c1541e5670dea37780bde9b25c0b658fe2a0 Mon Sep 17 00:00:00 2001 From: fkatsuhiro Date: Tue, 2 Dec 2025 17:18:39 +0900 Subject: [PATCH 1/5] feat(docs): Clarify astro:env/server variable evaluation and secret handling --- src/content/docs/en/guides/environment-variables.mdx | 5 +++++ src/content/docs/es/guides/environment-variables.mdx | 5 +++++ src/content/docs/fr/guides/environment-variables.mdx | 5 +++++ src/content/docs/ko/guides/environment-variables.mdx | 5 +++++ src/content/docs/zh-cn/guides/environment-variables.mdx | 5 +++++ 5 files changed, 25 insertions(+) diff --git a/src/content/docs/en/guides/environment-variables.mdx b/src/content/docs/en/guides/environment-variables.mdx index 1b8c4f73848c7..f4ad6a181d71f 100644 --- a/src/content/docs/en/guides/environment-variables.mdx +++ b/src/content/docs/en/guides/environment-variables.mdx @@ -285,6 +285,11 @@ There are three kinds of environment variables, determined by the combination of **Secret client variables** are not supported because there is no safe way to send this data to the client. Therefore, it is not possible to configure both `context: "client"` and `access: "secret"` in your schema. ::: +:::caution +Environment variables are evaluated immediately when `astro:env/server` is imported. Therefore, **secret server variables** are validated even when running `astro build`. +If your build process does not have access to these secrets, the build will fail. To fix this, you can pass dummy values to the build command to satisfy the validation. +::: + ### Data types There are currently four data types supported: strings, numbers, enums, and booleans: diff --git a/src/content/docs/es/guides/environment-variables.mdx b/src/content/docs/es/guides/environment-variables.mdx index da01b123a45e8..6b0771707c313 100644 --- a/src/content/docs/es/guides/environment-variables.mdx +++ b/src/content/docs/es/guides/environment-variables.mdx @@ -289,6 +289,11 @@ Hay tres tipos de variables de entorno, determinados por la combinación de las **Las variables secretas de cliente** no son compatibles porque no existe una forma segura de enviar estos datos al cliente. Por lo tanto, no es posible configurar simultáneamente `context: "client"` y `access: "secret"` en tu esquema. ::: +:::caution +Al importar `astro:env/server`, las variables de entorno se evalúan de inmediato. Por lo tanto, las **variables secretas del servidor** también se validan al ejecutar `astro build`. +Si el proceso de compilación no tiene acceso a estos secretos, la compilación fallará. Para solucionar este problema, puedes pasar valores ficticios en el comando de compilación para que la validación se realice correctamente. +::: + ### Tipos de datos Actualmente se admiten cuatro tipos de datos: cadenas, números, enumeraciones y booleanos: diff --git a/src/content/docs/fr/guides/environment-variables.mdx b/src/content/docs/fr/guides/environment-variables.mdx index 3e092ef7fbec1..d04fb2b50c1ad 100644 --- a/src/content/docs/fr/guides/environment-variables.mdx +++ b/src/content/docs/fr/guides/environment-variables.mdx @@ -285,6 +285,11 @@ Il existe trois types de variables d'environnement, déterminées par la combina Les **variables secrètes du client** ne sont pas prises en charge car il n'existe aucun moyen sûr d'envoyer ces données au client. Par conséquent, il n'est pas possible de configurer à la fois `context: "client"` et `access: "secret"` dans votre schéma. ::: +:::caution +Les variables d’environnement sont évaluées immédiatement lorsque astro:env/server est importé. Ainsi, les variables serveur secrètes sont également validées lors de l’exécution de astro build. +Si votre processus de build n’a pas accès à ces variables secrètes, le build échouera. Pour résoudre ce problème, vous pouvez fournir des valeurs factices dans la commande de build afin de satisfaire la validation. +::: + ### Types de données Il existe actuellement quatre types de données pris en charge : les chaînes de caractères, les nombres, les énumérations et les booléens : diff --git a/src/content/docs/ko/guides/environment-variables.mdx b/src/content/docs/ko/guides/environment-variables.mdx index 5cc2abd3e25fd..c2c6603f4b150 100644 --- a/src/content/docs/ko/guides/environment-variables.mdx +++ b/src/content/docs/ko/guides/environment-variables.mdx @@ -285,6 +285,11 @@ const data = await fetch(`${API_URL}/users`, { **비밀 클라이언트 변수**는 지원되지 않습니다. 이 데이터를 클라이언트로 안전하게 전송할 방법이 없기 때문입니다. 따라서 스키마에서 `context: "client"`와 `access: "secret"`을 모두 구성하는 것은 불가능합니다. ::: +:::caution +`astro:env/server`를 가져오면 환경 변수가 즉시 평가됩니다. 따라서 **비밀 서버 변수**는 `astro build` 실행 시에도 확인됩니다. +빌드 환경에서 이러한 비밀 값에 접근할 수 없으면 빌드가 실패합니다. 이 문제를 해결하려면, 검증을 통과하도록 빌드 명령어에 임시 값(더미 값)을 전달하면 됩니다. +::: + ### 데이터 타입 현재 문자열, 숫자, enum 및 부울의 네 가지 데이터 타입이 지원됩니다. diff --git a/src/content/docs/zh-cn/guides/environment-variables.mdx b/src/content/docs/zh-cn/guides/environment-variables.mdx index 1d3db3df1aa53..a478e8936788c 100644 --- a/src/content/docs/zh-cn/guides/environment-variables.mdx +++ b/src/content/docs/zh-cn/guides/environment-variables.mdx @@ -286,6 +286,11 @@ const data = await fetch(`${API_URL}/users`, { 不支持 **私密的客户端变量**，因为没有一种可以将这些数据安全发送到客户端的方式。所以，不能在你的 schema 中配置 `context: "client"` 和 `access: "secret"`。 ::: +:::caution +导入 `astro:env/server` 后，环境变量会被立即评估。因此，**私密的服务器变量** 在执行 `astro build` 时也会进行验证。 +如果构建环境无法访问这些私密变量，构建将会失败。为了解决这个问题，可以在构建命令中传入临时值（虚拟值）以通过验证。 +::: + ### 数据类型 目前支持四种数据类型：字符串、数字、枚举和布尔值： From 87b686720d63f765de3d2fab558ebf6a2b3126ee Mon Sep 17 00:00:00 2001 From: fkatsuhiro Date: Wed, 3 Dec 2025 23:16:01 +0900 Subject: [PATCH 2/5] fix: move explanation location and add sample commands --- .../docs/en/guides/environment-variables.mdx | 32 ++++++++++++++++--- .../docs/es/guides/environment-variables.mdx | 32 ++++++++++++++++--- .../docs/fr/guides/environment-variables.mdx | 32 ++++++++++++++++--- .../docs/ko/guides/environment-variables.mdx | 32 ++++++++++++++++--- .../zh-cn/guides/environment-variables.mdx | 32 ++++++++++++++++--- 5 files changed, 135 insertions(+), 25 deletions(-) diff --git a/src/content/docs/en/guides/environment-variables.mdx b/src/content/docs/en/guides/environment-variables.mdx index f4ad6a181d71f..1bf994933d345 100644 --- a/src/content/docs/en/guides/environment-variables.mdx +++ b/src/content/docs/en/guides/environment-variables.mdx @@ -285,11 +285,6 @@ There are three kinds of environment variables, determined by the combination of **Secret client variables** are not supported because there is no safe way to send this data to the client. Therefore, it is not possible to configure both `context: "client"` and `access: "secret"` in your schema. ::: -:::caution -Environment variables are evaluated immediately when `astro:env/server` is imported. Therefore, **secret server variables** are validated even when running `astro build`. -If your build process does not have access to these secrets, the build will fail. To fix this, you can pass dummy values to the build command to satisfy the validation. -::: - ### Data types There are currently four data types supported: strings, numbers, enums, and booleans: @@ -325,6 +320,33 @@ envField.enum({ For a complete list of validation fields, see the [`envField` API reference](/en/reference/configuration-reference/#envschema). +### Secrets during the build + +**Secret server variables** are validated even during `astro build` because `astro:env/server` is evaluated on import. + +If your build process does not have access to these secrets, the build will fail. You can pass dummy values to the build command to satisfy the validation: + + + + ```shell + # Example: passing a dummy value to build + MY_SECRET_KEY="placeholder" npm run build + ``` + + + ```shell + # Example: passing a dummy value to build + MY_SECRET_KEY="placeholder" pnpm build + ``` + + + ```shell + # Example: passing a dummy value to build + MY_SECRET_KEY="placeholder" yarn build + ``` + + + ### Retrieving secrets dynamically Despite defining your schema, you may want to retrieve the raw value of a given secret or to retrieve secrets not defined in your schema. In this case, you can use `getSecret()` exported from `astro:env/server`: diff --git a/src/content/docs/es/guides/environment-variables.mdx b/src/content/docs/es/guides/environment-variables.mdx index 6b0771707c313..bc6d224920c67 100644 --- a/src/content/docs/es/guides/environment-variables.mdx +++ b/src/content/docs/es/guides/environment-variables.mdx @@ -289,11 +289,6 @@ Hay tres tipos de variables de entorno, determinados por la combinación de las **Las variables secretas de cliente** no son compatibles porque no existe una forma segura de enviar estos datos al cliente. Por lo tanto, no es posible configurar simultáneamente `context: "client"` y `access: "secret"` en tu esquema. ::: -:::caution -Al importar `astro:env/server`, las variables de entorno se evalúan de inmediato. Por lo tanto, las **variables secretas del servidor** también se validan al ejecutar `astro build`. -Si el proceso de compilación no tiene acceso a estos secretos, la compilación fallará. Para solucionar este problema, puedes pasar valores ficticios en el comando de compilación para que la validación se realice correctamente. -::: - ### Tipos de datos Actualmente se admiten cuatro tipos de datos: cadenas, números, enumeraciones y booleanos: @@ -330,6 +325,33 @@ envField.enum({ {/*TODO: add link to /es/reference/configuration-reference/#envschema */} Para ver la lista completa de campos de validación, consulta la referencia de la API `envField`. +### Secretos durante la construcción + +Las **variables secretas del servidor** se validan incluso durante `astro build` debido a que `astro:env/server` se evalúa al importarse. + +Si tu proceso de construcción no tiene acceso a estos secretos, la construcción fallará. Puedes pasar valores ficticios al comando de construcción para cumplir con la validación: + + + + ```shell + # Ejemplo: pasar un valor ficticio a la construcción + MY_SECRET_KEY="placeholder" npm run build + ``` + + + ```shell + # Ejemplo: pasar un valor ficticio a la construcción + MY_SECRET_KEY="placeholder" pnpm build + ``` + + + ```shell + # Ejemplo: pasar un valor ficticio a la construcción + MY_SECRET_KEY="placeholder" yarn build + ``` + + + ### Recuperar secretos de forma dinámica Aunque definas tu esquema, puede que quieras obtener el valor en bruto de un secreto específico o recuperar secretos que no estén definidos en tu esquema. En este caso, puedes usar `getSecret()` exportado desde `astro:env/server`: diff --git a/src/content/docs/fr/guides/environment-variables.mdx b/src/content/docs/fr/guides/environment-variables.mdx index d04fb2b50c1ad..48084de0a084c 100644 --- a/src/content/docs/fr/guides/environment-variables.mdx +++ b/src/content/docs/fr/guides/environment-variables.mdx @@ -285,11 +285,6 @@ Il existe trois types de variables d'environnement, déterminées par la combina Les **variables secrètes du client** ne sont pas prises en charge car il n'existe aucun moyen sûr d'envoyer ces données au client. Par conséquent, il n'est pas possible de configurer à la fois `context: "client"` et `access: "secret"` dans votre schéma. ::: -:::caution -Les variables d’environnement sont évaluées immédiatement lorsque astro:env/server est importé. Ainsi, les variables serveur secrètes sont également validées lors de l’exécution de astro build. -Si votre processus de build n’a pas accès à ces variables secrètes, le build échouera. Pour résoudre ce problème, vous pouvez fournir des valeurs factices dans la commande de build afin de satisfaire la validation. -::: - ### Types de données Il existe actuellement quatre types de données pris en charge : les chaînes de caractères, les nombres, les énumérations et les booléens : @@ -325,6 +320,33 @@ envField.enum({ Pour une liste complète des champs de validation, consultez la [référence de l'API `envField`](/fr/reference/configuration-reference/#envschema). +### Secrets lors de la construction + +Les **variables secrètes du serveur** sont validées même lors de `astro build` car `astro:env/server` est évalué lors de l'importation. + +Si votre processus de construction n'a pas accès à ces secrets, la construction échouera. Vous pouvez transmettre des valeurs factices à la commande de construction pour satisfaire la validation : + + + + ```shell + # Exemple : transmettre une valeur factice à la construction + MY_SECRET_KEY="placeholder" npm run build + ``` + + + ```shell + # Exemple : transmettre une valeur factice à la construction + MY_SECRET_KEY="placeholder" pnpm build + ``` + + + ```shell + # Exemple : transmettre une valeur factice à la construction + MY_SECRET_KEY="placeholder" yarn build + ``` + + + ### Récupérer des secrets de manière dynamique Malgré la définition de votre schéma, vous souhaiterez peut-être récupérer la valeur brute d'un secret donné ou récupérer des secrets non définis dans votre schéma. Dans ce cas, vous pouvez utiliser `getSecret()` exporté depuis `astro:env/server` : diff --git a/src/content/docs/ko/guides/environment-variables.mdx b/src/content/docs/ko/guides/environment-variables.mdx index c2c6603f4b150..f12613bf40bd5 100644 --- a/src/content/docs/ko/guides/environment-variables.mdx +++ b/src/content/docs/ko/guides/environment-variables.mdx @@ -285,11 +285,6 @@ const data = await fetch(`${API_URL}/users`, { **비밀 클라이언트 변수**는 지원되지 않습니다. 이 데이터를 클라이언트로 안전하게 전송할 방법이 없기 때문입니다. 따라서 스키마에서 `context: "client"`와 `access: "secret"`을 모두 구성하는 것은 불가능합니다. ::: -:::caution -`astro:env/server`를 가져오면 환경 변수가 즉시 평가됩니다. 따라서 **비밀 서버 변수**는 `astro build` 실행 시에도 확인됩니다. -빌드 환경에서 이러한 비밀 값에 접근할 수 없으면 빌드가 실패합니다. 이 문제를 해결하려면, 검증을 통과하도록 빌드 명령어에 임시 값(더미 값)을 전달하면 됩니다. -::: - ### 데이터 타입 현재 문자열, 숫자, enum 및 부울의 네 가지 데이터 타입이 지원됩니다. @@ -325,6 +320,33 @@ envField.enum({ 유효성 검사 필드의 전체 목록은 [`envField` API 참조](/ko/reference/configuration-reference/#envschema)를 확인하세요. +### 빌드 시 비밀 변수 + +`astro:env/server`가 가져올 때 환경 변수가 즉시 평가되므로 `astro build`를 실행할 때도 **비밀 서버 변수**의 유효성이 검사됩니다. + +빌드 프로세스에서 이러한 비밀 변수에 접근할 수 없는 경우 빌드가 실패합니다. 유효성 검사를 통과하기 위해 빌드 명령에 더미 값을 전달할 수 있습니다. + + + + ```shell + # 예시: 빌드 시 더미 값 전달 + MY_SECRET_KEY="placeholder" npm run build + ``` + + + ```shell + # 예시: 빌드 시 더미 값 전달 + MY_SECRET_KEY="placeholder" pnpm build + ``` + + + ```shell + # 예시: 빌드 시 더미 값 전달 + MY_SECRET_KEY="placeholder" yarn build + ``` + + + ## 비밀 변수를 동적으로 검색 스키마를 정의했음에도 불구하고, 특정 비밀 변수의 원시 값을 검색하거나 스키마에 정의되지 않은 비밀 변수를 검색해야 할 수 있습니다. 이 경우 `astro:env/server`에서 내보낸 `getSecret()`을 사용할 수 있습니다. diff --git a/src/content/docs/zh-cn/guides/environment-variables.mdx b/src/content/docs/zh-cn/guides/environment-variables.mdx index a478e8936788c..7b34c6a9fc199 100644 --- a/src/content/docs/zh-cn/guides/environment-variables.mdx +++ b/src/content/docs/zh-cn/guides/environment-variables.mdx @@ -286,11 +286,6 @@ const data = await fetch(`${API_URL}/users`, { 不支持 **私密的客户端变量**，因为没有一种可以将这些数据安全发送到客户端的方式。所以，不能在你的 schema 中配置 `context: "client"` 和 `access: "secret"`。 ::: -:::caution -导入 `astro:env/server` 后，环境变量会被立即评估。因此，**私密的服务器变量** 在执行 `astro build` 时也会进行验证。 -如果构建环境无法访问这些私密变量，构建将会失败。为了解决这个问题，可以在构建命令中传入临时值（虚拟值）以通过验证。 -::: - ### 数据类型 目前支持四种数据类型：字符串、数字、枚举和布尔值： @@ -326,6 +321,33 @@ envField.enum({ 有关验证字段的完整列表，请参阅 [`envField` API 参考](/zh-cn/reference/configuration-reference/#envschema)。 +### 构建时的私密变量 + +由于 `astro:env/server` 在导入时会被求值，因此即使在运行 `astro build` 时，**私密的服务器变量**也会被验证。 + +如果你的构建流程无法获取这些私密变量，构建将会失败。你可以向构建命令传递占位值以通过验证： + + + + ```shell + # 示例：向构建传递占位值 + MY_SECRET_KEY="placeholder" npm run build + ``` + + + ```shell + # 示例：向构建传递占位值 + MY_SECRET_KEY="placeholder" pnpm build + ``` + + + ```shell + # 示例：向构建传递占位值 + MY_SECRET_KEY="placeholder" yarn build + ``` + + + ### 动态检索私密变量 尽管定义了你的 schema，你可能想要检索某一个私密变量的原始值，或者检索未在你的 schema 中定义的私密变量。在这种情况下，你可以使用 `astro:env/server` 导出的 `getSecret()`： From 58866e1e1e1da56ac1ebfcb975897f4b55d2ea23 Mon Sep 17 00:00:00 2001 From: fkatsuhiro Date: Wed, 3 Dec 2025 23:31:05 +0900 Subject: [PATCH 3/5] fix: sample secret server valiable placeholder to dummy --- src/content/docs/en/guides/environment-variables.mdx | 6 +++--- src/content/docs/es/guides/environment-variables.mdx | 6 +++--- src/content/docs/fr/guides/environment-variables.mdx | 6 +++--- src/content/docs/ko/guides/environment-variables.mdx | 6 +++--- src/content/docs/zh-cn/guides/environment-variables.mdx | 6 +++--- 5 files changed, 15 insertions(+), 15 deletions(-) diff --git a/src/content/docs/en/guides/environment-variables.mdx b/src/content/docs/en/guides/environment-variables.mdx index 1bf994933d345..94a23f36a96c8 100644 --- a/src/content/docs/en/guides/environment-variables.mdx +++ b/src/content/docs/en/guides/environment-variables.mdx @@ -330,19 +330,19 @@ If your build process does not have access to these secrets, the build will fail ```shell # Example: passing a dummy value to build - MY_SECRET_KEY="placeholder" npm run build + MY_SECRET_KEY="dummy" npm run build ``` ```shell # Example: passing a dummy value to build - MY_SECRET_KEY="placeholder" pnpm build + MY_SECRET_KEY="dummy" pnpm build ``` ```shell # Example: passing a dummy value to build - MY_SECRET_KEY="placeholder" yarn build + MY_SECRET_KEY="dummy" yarn build ``` diff --git a/src/content/docs/es/guides/environment-variables.mdx b/src/content/docs/es/guides/environment-variables.mdx index bc6d224920c67..1b994d5f02eb6 100644 --- a/src/content/docs/es/guides/environment-variables.mdx +++ b/src/content/docs/es/guides/environment-variables.mdx @@ -335,19 +335,19 @@ Si tu proceso de construcción no tiene acceso a estos secretos, la construcció ```shell # Ejemplo: pasar un valor ficticio a la construcción - MY_SECRET_KEY="placeholder" npm run build + MY_SECRET_KEY="dummy" npm run build ``` ```shell # Ejemplo: pasar un valor ficticio a la construcción - MY_SECRET_KEY="placeholder" pnpm build + MY_SECRET_KEY="dummy" pnpm build ``` ```shell # Ejemplo: pasar un valor ficticio a la construcción - MY_SECRET_KEY="placeholder" yarn build + MY_SECRET_KEY="dummy" yarn build ``` diff --git a/src/content/docs/fr/guides/environment-variables.mdx b/src/content/docs/fr/guides/environment-variables.mdx index 48084de0a084c..4db7cdbddebef 100644 --- a/src/content/docs/fr/guides/environment-variables.mdx +++ b/src/content/docs/fr/guides/environment-variables.mdx @@ -330,19 +330,19 @@ Si votre processus de construction n'a pas accès à ces secrets, la constructio ```shell # Exemple : transmettre une valeur factice à la construction - MY_SECRET_KEY="placeholder" npm run build + MY_SECRET_KEY="dummy" npm run build ``` ```shell # Exemple : transmettre une valeur factice à la construction - MY_SECRET_KEY="placeholder" pnpm build + MY_SECRET_KEY="dummy" pnpm build ``` ```shell # Exemple : transmettre une valeur factice à la construction - MY_SECRET_KEY="placeholder" yarn build + MY_SECRET_KEY="dummy" yarn build ``` diff --git a/src/content/docs/ko/guides/environment-variables.mdx b/src/content/docs/ko/guides/environment-variables.mdx index f12613bf40bd5..96aa33348d418 100644 --- a/src/content/docs/ko/guides/environment-variables.mdx +++ b/src/content/docs/ko/guides/environment-variables.mdx @@ -330,19 +330,19 @@ envField.enum({ ```shell # 예시: 빌드 시 더미 값 전달 - MY_SECRET_KEY="placeholder" npm run build + MY_SECRET_KEY="dummy" npm run build ``` ```shell # 예시: 빌드 시 더미 값 전달 - MY_SECRET_KEY="placeholder" pnpm build + MY_SECRET_KEY="dummy" pnpm build ``` ```shell # 예시: 빌드 시 더미 값 전달 - MY_SECRET_KEY="placeholder" yarn build + MY_SECRET_KEY="dummy" yarn build ``` diff --git a/src/content/docs/zh-cn/guides/environment-variables.mdx b/src/content/docs/zh-cn/guides/environment-variables.mdx index 7b34c6a9fc199..a90174f9dd03d 100644 --- a/src/content/docs/zh-cn/guides/environment-variables.mdx +++ b/src/content/docs/zh-cn/guides/environment-variables.mdx @@ -331,19 +331,19 @@ envField.enum({ ```shell # 示例：向构建传递占位值 - MY_SECRET_KEY="placeholder" npm run build + MY_SECRET_KEY="dummy" npm run build ``` ```shell # 示例：向构建传递占位值 - MY_SECRET_KEY="placeholder" pnpm build + MY_SECRET_KEY="dummy" pnpm build ``` ```shell # 示例：向构建传递占位值 - MY_SECRET_KEY="placeholder" yarn build + MY_SECRET_KEY="dummy" yarn build ``` From f0f13aca4d708ee000d948ddb521be225637b0d3 Mon Sep 17 00:00:00 2001 From: fkatsuhiro Date: Thu, 4 Dec 2025 00:30:36 +0900 Subject: [PATCH 4/5] fix: remove translation other than English --- .../docs/es/guides/environment-variables.mdx | 27 ------------------- .../docs/fr/guides/environment-variables.mdx | 27 ------------------- .../docs/ko/guides/environment-variables.mdx | 27 ------------------- .../zh-cn/guides/environment-variables.mdx | 27 ------------------- 4 files changed, 108 deletions(-) diff --git a/src/content/docs/es/guides/environment-variables.mdx b/src/content/docs/es/guides/environment-variables.mdx index 1b994d5f02eb6..da01b123a45e8 100644 --- a/src/content/docs/es/guides/environment-variables.mdx +++ b/src/content/docs/es/guides/environment-variables.mdx @@ -325,33 +325,6 @@ envField.enum({ {/*TODO: add link to /es/reference/configuration-reference/#envschema */} Para ver la lista completa de campos de validación, consulta la referencia de la API `envField`. -### Secretos durante la construcción - -Las **variables secretas del servidor** se validan incluso durante `astro build` debido a que `astro:env/server` se evalúa al importarse. - -Si tu proceso de construcción no tiene acceso a estos secretos, la construcción fallará. Puedes pasar valores ficticios al comando de construcción para cumplir con la validación: - - - - ```shell - # Ejemplo: pasar un valor ficticio a la construcción - MY_SECRET_KEY="dummy" npm run build - ``` - - - ```shell - # Ejemplo: pasar un valor ficticio a la construcción - MY_SECRET_KEY="dummy" pnpm build - ``` - - - ```shell - # Ejemplo: pasar un valor ficticio a la construcción - MY_SECRET_KEY="dummy" yarn build - ``` - - - ### Recuperar secretos de forma dinámica Aunque definas tu esquema, puede que quieras obtener el valor en bruto de un secreto específico o recuperar secretos que no estén definidos en tu esquema. En este caso, puedes usar `getSecret()` exportado desde `astro:env/server`: diff --git a/src/content/docs/fr/guides/environment-variables.mdx b/src/content/docs/fr/guides/environment-variables.mdx index 4db7cdbddebef..3e092ef7fbec1 100644 --- a/src/content/docs/fr/guides/environment-variables.mdx +++ b/src/content/docs/fr/guides/environment-variables.mdx @@ -320,33 +320,6 @@ envField.enum({ Pour une liste complète des champs de validation, consultez la [référence de l'API `envField`](/fr/reference/configuration-reference/#envschema). -### Secrets lors de la construction - -Les **variables secrètes du serveur** sont validées même lors de `astro build` car `astro:env/server` est évalué lors de l'importation. - -Si votre processus de construction n'a pas accès à ces secrets, la construction échouera. Vous pouvez transmettre des valeurs factices à la commande de construction pour satisfaire la validation : - - - - ```shell - # Exemple : transmettre une valeur factice à la construction - MY_SECRET_KEY="dummy" npm run build - ``` - - - ```shell - # Exemple : transmettre une valeur factice à la construction - MY_SECRET_KEY="dummy" pnpm build - ``` - - - ```shell - # Exemple : transmettre une valeur factice à la construction - MY_SECRET_KEY="dummy" yarn build - ``` - - - ### Récupérer des secrets de manière dynamique Malgré la définition de votre schéma, vous souhaiterez peut-être récupérer la valeur brute d'un secret donné ou récupérer des secrets non définis dans votre schéma. Dans ce cas, vous pouvez utiliser `getSecret()` exporté depuis `astro:env/server` : diff --git a/src/content/docs/ko/guides/environment-variables.mdx b/src/content/docs/ko/guides/environment-variables.mdx index 96aa33348d418..5cc2abd3e25fd 100644 --- a/src/content/docs/ko/guides/environment-variables.mdx +++ b/src/content/docs/ko/guides/environment-variables.mdx @@ -320,33 +320,6 @@ envField.enum({ 유효성 검사 필드의 전체 목록은 [`envField` API 참조](/ko/reference/configuration-reference/#envschema)를 확인하세요. -### 빌드 시 비밀 변수 - -`astro:env/server`가 가져올 때 환경 변수가 즉시 평가되므로 `astro build`를 실행할 때도 **비밀 서버 변수**의 유효성이 검사됩니다. - -빌드 프로세스에서 이러한 비밀 변수에 접근할 수 없는 경우 빌드가 실패합니다. 유효성 검사를 통과하기 위해 빌드 명령에 더미 값을 전달할 수 있습니다. - - - - ```shell - # 예시: 빌드 시 더미 값 전달 - MY_SECRET_KEY="dummy" npm run build - ``` - - - ```shell - # 예시: 빌드 시 더미 값 전달 - MY_SECRET_KEY="dummy" pnpm build - ``` - - - ```shell - # 예시: 빌드 시 더미 값 전달 - MY_SECRET_KEY="dummy" yarn build - ``` - - - ## 비밀 변수를 동적으로 검색 스키마를 정의했음에도 불구하고, 특정 비밀 변수의 원시 값을 검색하거나 스키마에 정의되지 않은 비밀 변수를 검색해야 할 수 있습니다. 이 경우 `astro:env/server`에서 내보낸 `getSecret()`을 사용할 수 있습니다. diff --git a/src/content/docs/zh-cn/guides/environment-variables.mdx b/src/content/docs/zh-cn/guides/environment-variables.mdx index a90174f9dd03d..1d3db3df1aa53 100644 --- a/src/content/docs/zh-cn/guides/environment-variables.mdx +++ b/src/content/docs/zh-cn/guides/environment-variables.mdx @@ -321,33 +321,6 @@ envField.enum({ 有关验证字段的完整列表，请参阅 [`envField` API 参考](/zh-cn/reference/configuration-reference/#envschema)。 -### 构建时的私密变量 - -由于 `astro:env/server` 在导入时会被求值，因此即使在运行 `astro build` 时，**私密的服务器变量**也会被验证。 - -如果你的构建流程无法获取这些私密变量，构建将会失败。你可以向构建命令传递占位值以通过验证： - - - - ```shell - # 示例：向构建传递占位值 - MY_SECRET_KEY="dummy" npm run build - ``` - - - ```shell - # 示例：向构建传递占位值 - MY_SECRET_KEY="dummy" pnpm build - ``` - - - ```shell - # 示例：向构建传递占位值 - MY_SECRET_KEY="dummy" yarn build - ``` - - - ### 动态检索私密变量 尽管定义了你的 schema，你可能想要检索某一个私密变量的原始值，或者检索未在你的 schema 中定义的私密变量。在这种情况下，你可以使用 `astro:env/server` 导出的 `getSecret()`： From e0ffd592dcc7d2661162eced67c5f498e377cfdc Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> Date: Thu, 4 Dec 2025 10:59:55 -0400 Subject: [PATCH 5/5] integrate new info into existing text --- .../docs/en/guides/environment-variables.mdx | 31 ++----------------- 1 file changed, 3 insertions(+), 28 deletions(-) diff --git a/src/content/docs/en/guides/environment-variables.mdx b/src/content/docs/en/guides/environment-variables.mdx index 94a23f36a96c8..af2b99b85fd9e 100644 --- a/src/content/docs/en/guides/environment-variables.mdx +++ b/src/content/docs/en/guides/environment-variables.mdx @@ -279,7 +279,9 @@ There are three kinds of environment variables, determined by the combination of import { API_SECRET } from "astro:env/server"; ``` - By default, secrets are only validated at runtime. You can enable validating private variables on start by [configuring `validateSecrets: true`](/en/reference/configuration-reference/#envvalidatesecrets). + By default, all secrets are validated whenever anything is imported from the `astro:env/server` module. This means, secrets may be validated even when they are not imported. You may need to [pass dummy environment variables](#setting-environment-variables) to satisfy this validation during the build. + + You can also enable validating secrets on start by [configuring `validateSecrets: true`](/en/reference/configuration-reference/#envvalidatesecrets). :::note **Secret client variables** are not supported because there is no safe way to send this data to the client. Therefore, it is not possible to configure both `context: "client"` and `access: "secret"` in your schema. @@ -320,33 +322,6 @@ envField.enum({ For a complete list of validation fields, see the [`envField` API reference](/en/reference/configuration-reference/#envschema). -### Secrets during the build - -**Secret server variables** are validated even during `astro build` because `astro:env/server` is evaluated on import. - -If your build process does not have access to these secrets, the build will fail. You can pass dummy values to the build command to satisfy the validation: - - - - ```shell - # Example: passing a dummy value to build - MY_SECRET_KEY="dummy" npm run build - ``` - - - ```shell - # Example: passing a dummy value to build - MY_SECRET_KEY="dummy" pnpm build - ``` - - - ```shell - # Example: passing a dummy value to build - MY_SECRET_KEY="dummy" yarn build - ``` - - - ### Retrieving secrets dynamically Despite defining your schema, you may want to retrieve the raw value of a given secret or to retrieve secrets not defined in your schema. In this case, you can use `getSecret()` exported from `astro:env/server`: