Переменные окружения в CI
Храните секреты в GitHub Secrets, передавайте их в сборку как переменные окружения и обращайтесь к ним в Vite через import.meta.env или в Next.js через process.env
«Переменные окружения в CI» — бесплатный урок Frontend Academy на CoddyKit. Это урок 3 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения Frontend Academy, и твой прогресс синхронизируется между веб-версией и приложением CoddyKit. Курс Frontend Academy содержит 4 уроков всего.
Зачем нужны разные среды
Приложениям нужны разные значения для каждой среды: адрес API для разработки, адрес API для промежуточной среды и адрес API для production. Кроме того, есть секреты (ключи доступа к API и токены), которые никогда не должны попадать в репозиторий. Переменные среды — стандартный способ передавать эти значения.
Публичные и серверные переменные
Переменные фронтенда, встроенные в пакет, являются публичными — их видит любой пользователь DevTools. Никогда не помещайте туда секреты. Серверные переменные (используемые в бессерверных функциях, SSR и маршрутах API) действительно могут быть секретными.
Переменные среды Vite
Vite предоставляет клиентскому коду переменные с префиксом VITE_ через import.meta.env.
# .env
VITE_API_URL=https://api.example.com
VITE_FEATURE_FLAGS={"newOnboarding":true}
# In code:
const apiUrl = import.meta.env.VITE_API_URL;
# DEV_ONLY or NEVER PREFIXED vars are NOT exposed:
SECRET_KEY=xxx # not accessible to client codeПеременные среды Next.js
Next добавляет префикс NEXT_PUBLIC_ к публичным переменным. Серверные переменные не имеют префикса и используются в обработчиках маршрутов и getServerSideProps.
# .env.local
NEXT_PUBLIC_API_URL=https://api.example.com # client-accessible
DATABASE_URL=postgres://... # server-only
# Client:
const url = process.env.NEXT_PUBLIC_API_URL;
# Server (API route):
const db = process.env.DATABASE_URL;Локальные файлы .env
Используйте .env.local для личных переопределений, а .env.development и .env.production — для значений по умолчанию, зависящих от среды. Добавьте .env.local в .gitignore — никогда не добавляйте секреты в репозиторий.
# .gitignore
.env.local
.env.*.local
# Commit only .env.example with placeholder values:
VITE_API_URL=https://api.example.com
DATABASE_URL=Хранение секретов в GitHub Actions
Добавляйте секреты в настройках репозитория: Настройки → Секреты и переменные → Actions. Получайте к ним доступ через secrets.NAME.
# .github/workflows/deploy.yml
- name: Deploy
env:
VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
run: |
npx vercel --token $VERCEL_TOKEN --prod
npx sentry-cli releases new $RELEASEСекреты для конкретных сред
GitHub Environments (Настройки → Среды) позволяют ограничить область действия секретов конкретной средой (staging, production) с optional этапами утверждения.
# Job that requires environment:
deploy-prod:
environment: production # requires reviewer approval if configured
steps:
- run: deploy
env:
DB_URL: ${{ secrets.DB_URL }} # only prod's DB_URL is exposedПеременные среды у провайдеров хостинга
Vercel, Netlify и Cloudflare предоставляют env-переменные сборке и среде выполнения. Задавайте их через панель управления или CLI.
# Vercel:
vercel env add VITE_API_URL production
vercel env add VITE_API_URL preview
# Netlify:
netlify env:set VITE_API_URL https://api.example.com
# Cloudflare Pages:
wrangler pages secret put API_URLНе встраивайте секреты в сборки фронтенда
Если значение находится в клиентском JS, оно публично. Ключи API для сторонних SDK (публичный ключ Stripe, ключ поиска Algolia) изначально предназначены для публикации. Всё остальное, включая серверные ключи API, должно оставаться на серверной части.
Проверка переменных среды во время сборки
Используйте zod или envalid, чтобы сборка завершалась с ошибкой при отсутствии обязательных переменных среды.
// env.ts
import { z } from 'zod';
const envSchema = z.object({
VITE_API_URL: z.string().url(),
VITE_SENTRY_DSN: z.string().url().optional()
});
export const env = envSchema.parse(import.meta.env);
// Throws helpful error if VITE_API_URL is missingПеременные во время сборки и выполнения
Переменные среды сборки встраиваются в пакет — для их изменения требуется новая сборка. Переменные среды выполнения (маршруты API Next, Netlify Functions и Cloudflare Workers) вычисляются для каждого запроса. Выбирайте подход в зависимости от того, должно ли значение изменяться без повторного развертывания.
Ротация секретов
Регулярно меняйте секреты (каждые 90 дней), а также после любого изменения состава команды. Используйте 1Password Secrets Automation, AWS Secrets Manager или аналогичный инструмент, чтобы в CI всегда применялись актуальные секреты без ручных обновлений.
Распространенные ошибки
1) Добавление .env с настоящими секретами — используйте git-secrets, чтобы предотвратить это. 2) Предоставление серверных переменных клиенту (неверный префикс). 3) Забытые переменные среды в предварительных развертываниях. 4) Смешивание тестовых и production-ключей в одной среде.
Быстрая проверка
Почему переменные среды Vite, предоставляемые клиенту, должны иметь префикс VITE_?
Повторение: переменные среды в CI
Публичные переменные: имеют префикс (VITE_, NEXT_PUBLIC_), встраиваются в пакет и видны пользователям. Серверные переменные: не имеют префикса и используются в маршрутах API и SSR. Файл .env.local добавляется в .gitignore; файл .env.example следует добавлять в репозиторий. Секреты GitHub используются для CI, а GitHub Environments — для ограничения области действия секретов в production. Провайдеры хостинга (Vercel, Netlify и Cloudflare) задают переменные отдельно для каждой среды. Проверяйте их с помощью zod во время сборки.
Часто задаваемые вопросы
Урок «Переменные окружения в CI» бесплатный?
Да — полный текст урока «Переменные окружения в CI» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс Frontend Academy, подпишись на CoddyKit PRO. Курс Frontend Academy содержит 4 уроков всего.
Чему я научусь в уроке «Переменные окружения в CI»?
Храните секреты в GitHub Secrets, передавайте их в сборку как переменные окружения и обращайтесь к ним в Vite через import.meta.env или в Next.js через process.env Ты практикуешь Frontend Academy с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.
Нужен ли мне опыт, чтобы начать Frontend Academy?
Предыдущий опыт не требуется. Frontend Academy на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 3 из 4.
Сколько времени занимает урок «Переменные окружения в CI»?
Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.
Можно ли писать и запускать код в этом уроке Frontend Academy?
Да. Каждый урок Frontend Academy включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.
Все уроки этого курса
- GitHub Actions для фронтенда: проверка, тестирование и сборка
- Развёртывание в Vercel, Netlify и Cloudflare Pages
- Переменные окружения в CI
- Автоматические проверки Lighthouse