Переменная Cloudflare Pages может существовать и всё равно быть недоступной коду, если её читают не на том этапе. Build command, Pages Function и JavaScript в браузере работают в разных контекстах. Сначала найдите строку чтения и ответьте: значение нужно при сборке статических файлов, во время запроса к Function или уже в клиентском bundle.
Для Pages Functions переменные и secrets являются bindings и доступны через `context.env`. Статическая страница не получает runtime bindings. Если значение должно попасть в frontend, его обычно встраивает framework во время build по своим правилам публичных префиксов — после этого оно уже не секрет и будет доступно посетителю.
Три контекста дают три разных симптома
| Где читается | Правильный источник | Типичная причина undefined |
|---|---|---|
| Build command | Build environment выбранного deploy | Переменная добавлена после сборки или только в другом окружении |
| Pages Function | context.env binding | Код читает process.env либо binding не привязан |
| Preview deployment | Preview vars/secrets | Значение задано только для production |
| Production deployment | Production 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
- Создать тестовое неопасное значение отдельно для preview и production.
- Запустить новый deploy и записать commit, environment и deployment ID.
- Проверить build log только на факт наличия имени, без значения.
- Вызвать контрольную Function и получить `configured: true`.
- Убедиться, что secret отсутствует в собранных assets и исходных картах.
Для разбора понадобятся способ deploy, branch, названия переменных, фрагмент Wrangler config без значений, место чтения и обезличенный build log. Значения secrets, API tokens, account ID и полный dump окружения не передавайте.