Переменная Cloudflare Pages может существовать и всё равно быть недоступной коду, если её читают не на том этапе. Build command, Pages Function и JavaScript в браузере работают в разных контекстах. Сначала найдите строку чтения и ответьте: значение нужно при сборке статических файлов, во время запроса к Function или уже в клиентском bundle.

Для Pages Functions переменные и secrets являются bindings и доступны через `context.env`. Статическая страница не получает runtime bindings. Если значение должно попасть в frontend, его обычно встраивает framework во время build по своим правилам публичных префиксов — после этого оно уже не секрет и будет доступно посетителю.

Три контекста дают три разных симптома

Где читаетсяПравильный источникТипичная причина undefined
Build commandBuild environment выбранного deployПеременная добавлена после сборки или только в другом окружении
Pages Functioncontext.env bindingКод читает process.env либо binding не привязан
Preview deploymentPreview vars/secretsЗначение задано только для production
Production deploymentProduction vars/secretsПроверяется preview URL или старый deployment
Код в браузереПубличная build-time переменнаяОжидание runtime secret в статическом JS

Не начинайте с переименования переменной наугад. В Deployment details сохраните commit, branch и время сборки, затем сопоставьте их со средой, где задано значение. Изменение binding не переписывает уже опубликованный статический bundle: Cloudflare указывает, что secret должен быть настроен до deployment, который его использует.

Function проверяет наличие, а не печатает значение

export async function onRequest({ env }) {
  const configured = typeof env.API_BASE_URL === "string"
    && env.API_BASE_URL.length > 0;

  return Response.json({
    configured,
    environment: env.APP_ENV ?? "unknown"
  });
}

Этот условный endpoint возвращает только факт настройки и безопасную метку окружения. Не выводите значение, длину токена, первые символы или весь объект `env`: build logs и HTTP-ответы часто сохраняются дольше, чем ожидает разработчик. После диагностики ограничьте либо удалите endpoint.

Dashboard и Wrangler должны описывать одну модель

Если проект развёртывается через `wrangler pages deploy`, проверьте `vars` и environment overrides в Wrangler configuration. Cloudflare Pages различает preview и production, а локальная разработка может читать `.dev.vars` или `.env`. Успех локально не подтверждает наличие binding в удалённом deployment.

  • Сравните точное имя с учётом регистра и отсутствие пробела в конце.
  • Проверьте, кто создал deploy: Git integration, deploy hook или Wrangler.
  • Не храните API key в обычном `vars`, если значение должно быть secret.
  • Не коммитьте `.dev.vars*` и `.env*`; добавьте их в `.gitignore`.
  • После изменения создайте новый deploy и проверяйте именно его URL/ID.

Build variable и Function secret нельзя подменять друг другом

Build-time значение полезно для версии Node.js, публичного base URL или feature flag, который допустимо видеть в asset. Secret, нужный для внешнего API, должен использоваться серверной Function. Если frontend вызывает провайдера напрямую, скрыть ключ с помощью необычного имени переменной невозможно: итоговый JavaScript и сетевые запросы доступны пользователю.

Для перехода перенесите привилегированный вызов в Function, добавьте server-side binding, ограничьте права ключа и только затем отзовите значение, ранее попавшее в bundle. Простое удаление переменной из следующей сборки не отзывает уже утёкший credential.

Приёмка начинается с нового deployment ID

  1. Создать тестовое неопасное значение отдельно для preview и production.
  2. Запустить новый deploy и записать commit, environment и deployment ID.
  3. Проверить build log только на факт наличия имени, без значения.
  4. Вызвать контрольную Function и получить `configured: true`.
  5. Убедиться, что secret отсутствует в собранных assets и исходных картах.

Для разбора понадобятся способ deploy, branch, названия переменных, фрагмент Wrangler config без значений, место чтения и обезличенный build log. Значения secrets, API tokens, account ID и полный dump окружения не передавайте.

Проверенные источники