Kurs Next.js · Moduł 8: Deployment i produkcja

Zmienne środowiskowe i konfiguracja produkcyjna

6 min czytania ·
W tej lekcji8

W Metropolii Quantum 2150 każdy system wymaga precyzyjnej konfiguracji środowiskowej. Tak jak w cyberpunkowym mieście każda dzielnica ma własne protokoły bezpieczeństwa, tak aplikacja Next.js potrzebuje różnych ustawień dla różnych środowisk - development, staging i production. Zmienne środowiskowe to klucz do bezpiecznego i elastycznego zarządzania konfiguracją.

Czym są zmienne środowiskowe?

Zmienne środowiskowe (environment variables) to pary klucz-wartość, które konfigurują zachowanie aplikacji bez modyfikacji kodu źródłowego. Dzięki nim możesz przechowywać:

  • Klucze API i sekrety (np. klucze do bazy danych, tokeny autoryzacji)
  • Adresy URL serwisów zewnętrznych
  • Flagi konfiguracyjne (np. tryb debug, poziom logowania)
  • Ustawienia specyficzne dla środowiska (development vs production)

Pliki .env w Next.js

Next.js ma wbudowane wsparcie dla plików .env. Framework automatycznie ładuje zmienne środowiskowe z kilku plików, w określonej kolejności priorytetów:

Hierarchia plików .env

# Pliki .env w Next.js (od najwyższego priorytetu):
.env.local          # Lokalne nadpisania - NIGDY nie commituj do git!
.env.development    # Tylko dla npm run dev
.env.production     # Tylko dla npm run build / npm start
.env                # Domyślne wartości dla wszystkich środowisk

Każdy plik może nadpisywać wartości z plików o niższym priorytecie. Plik .env.local ma zawsze najwyższy priorytet i powinien być w .gitignore.

Tworzenie plików .env

# .env - domyślne wartości (commitowane do repo)
NEXT_PUBLIC_APP_NAME=QuantumCity
NEXT_PUBLIC_API_URL=http://localhost:4000/api
DATABASE_URL=mongodb://localhost:27017/quantum_dev
JWT_SECRET=development-secret-key-change-in-production

# .env.local - lokalne sekrety (NIE commituj!)
DATABASE_URL=mongodb://user:secret@prod-cluster.mongodb.net/quantum
JWT_SECRET=super-tajny-klucz-produkcyjny-2150
OPENAI_API_KEY=sk-proj-abc123...
STRIPE_SECRET_KEY=sk_live_abc123...

# .env.production - ustawienia produkcyjne
NEXT_PUBLIC_API_URL=https://api.quantum-city.com
NEXT_PUBLIC_APP_NAME=QuantumCity Production
NODE_ENV=production

Prefix NEXT_PUBLIC_ - klucz do bezpieczeństwa

To jedna z najważniejszych zasad w Next.js! Prefix NEXT_PUBLIC_ determinuje, czy zmienna jest dostępna w przeglądarce:

// Zmienne BEZ prefixu - dostępne TYLKO na serwerze
// Nigdy nie trafiają do bundla przeglądarki!
const dbUrl = process.env.DATABASE_URL;        // OK w Server Components
const apiKey = process.env.OPENAI_API_KEY;     // OK w Route Handlers
const secret = process.env.JWT_SECRET;         // OK w middleware

// Zmienne Z prefixem NEXT_PUBLIC_ - dostępne WSZĘDZIE
// Trafiają do bundla JavaScript w przeglądarce!
const appName = process.env.NEXT_PUBLIC_APP_NAME;  // OK w Client Components
const apiUrl = process.env.NEXT_PUBLIC_API_URL;    // OK wszędzie

Przykład użycia w komponentach

// app/layout.tsx - Server Component
export default function RootLayout({ children }: { children: React.ReactNode }) {
  // Bezpieczne - zmienna serwerowa, nie trafia do przeglądarki
  const dbUrl = process.env.DATABASE_URL;
  console.log('Connecting to:', dbUrl);

  return (
    <html>
      <body>
        {/* NEXT_PUBLIC_ - bezpiecznie używane w HTML */}
        <h1>{process.env.NEXT_PUBLIC_APP_NAME}</h1>
        {children}
      </body>
    </html>
  );
}

// components/ApiStatus.tsx - Client Component
'use client';
import { useEffect, useState } from 'react';

export default function ApiStatus() {
  const [status, setStatus] = useState('checking...');

  useEffect(() => {
    // NEXT_PUBLIC_ zmienne działają w przeglądarce
    const apiUrl = process.env.NEXT_PUBLIC_API_URL;

    fetch(apiUrl + '/health')
      .then(res => res.json())
      .then(data => setStatus(data.status));
  }, []);

  return <span>API: {status}</span>;
}

Runtime vs Build-time zmienne środowiskowe

Ważne jest zrozumienie, kiedy zmienne są odczytywane:

Build-time (czas budowania)

Zmienne NEXT_PUBLIC_ są wstrzykiwane podczas npm run build. Oznacza to, że po zbudowaniu aplikacji ich wartości są "zamrożone" w kodzie JavaScript:

# Te wartości zostaną wstrzyknięte do bundla podczas build:
NEXT_PUBLIC_API_URL=https://api.quantum-city.com npm run build

# Po zbudowaniu, zmiana tej zmiennej NIE zmieni zachowania aplikacji!
# Trzeba przebudować (rebuild), aby zastosować nową wartość.

Runtime (czas wykonywania)

Zmienne serwerowe (bez NEXT_PUBLIC_) są odczytywane w czasie rzeczywistym - przy każdym żądaniu:

// app/api/config/route.ts
import { NextResponse } from 'next/server';

export async function GET() {
  // Ta wartość jest odczytywana PRZY KAŻDYM żądaniu
  // Zmiana zmiennej na serwerze natychmiast wpływa na odpowiedź
  const dbUrl = process.env.DATABASE_URL;
  const maxConnections = process.env.DB_MAX_CONNECTIONS || '10';

  return NextResponse.json({
    database: dbUrl ? 'connected' : 'not configured',
    maxConnections: parseInt(maxConnections),
  });
}

Walidacja zmiennych środowiskowych z Zod (wzorzec t3-env)

W profesjonalnych aplikacjach warto walidować zmienne środowiskowe przy starcie aplikacji, aby uniknąć błędów w runtime. Popularne podejście to użycie biblioteki Zod:

// lib/env.ts
import { z } from 'zod';

// Schemat walidacji zmiennych serwerowych
const serverEnvSchema = z.object({
  DATABASE_URL: z.string().url('DATABASE_URL musi być poprawnym URL'),
  JWT_SECRET: z.string().min(32, 'JWT_SECRET musi mieć min. 32 znaki'),
  OPENAI_API_KEY: z.string().startsWith('sk-', 'Nieprawidłowy klucz OpenAI'),
  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
  PORT: z.coerce.number().default(4000),
});

// Schemat walidacji zmiennych klienckich
const clientEnvSchema = z.object({
  NEXT_PUBLIC_APP_NAME: z.string().min(1),
  NEXT_PUBLIC_API_URL: z.string().url(),
});

// Walidacja przy imporcie modułu
const serverEnv = serverEnvSchema.safeParse(process.env);
const clientEnv = clientEnvSchema.safeParse(process.env);

if (!serverEnv.success) {
  console.error('Brakujące zmienne serwerowe:', serverEnv.error.format());
  throw new Error('Nieprawidłowa konfiguracja środowiska serwerowego');
}

if (!clientEnv.success) {
  console.error('Brakujące zmienne klienckie:', clientEnv.error.format());
  throw new Error('Nieprawidłowa konfiguracja środowiska klienckiego');
}

export const env = {
  ...serverEnv.data,
  ...clientEnv.data,
};

Użycie walidowanych zmiennych

// app/api/users/route.ts
import { env } from '@/lib/env';

export async function GET() {
  // TypeScript zna typy - env.DATABASE_URL jest zawsze string
  // Walidacja gwarantuje, że wartość jest poprawnym URL
  const response = await fetch(env.NEXT_PUBLIC_API_URL + '/users', {
    headers: {
      'Authorization': 'Bearer ' + env.JWT_SECRET,
    },
  });

  return Response.json(await response.json());
}

Konfiguracja next.config.js pod różne środowiska

Plik next.config.js może wykorzystywać zmienne środowiskowe do dynamicznej konfiguracji:

// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  // Ustawianie dodatkowych zmiennych środowiskowych
  env: {
    CUSTOM_KEY: process.env.NODE_ENV === 'production'
      ? 'production-value'
      : 'development-value',
    BUILD_TIME: new Date().toISOString(),
  },

  // Konfiguracja obrazów zależna od środowiska
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: process.env.NODE_ENV === 'production'
          ? 'cdn.quantum-city.com'
          : 'localhost',
      },
    ],
  },

  // Różne nagłówki dla dev i prod
  async headers() {
    const securityHeaders = [
      { key: 'X-Frame-Options', value: 'SAMEORIGIN' },
      { key: 'X-Content-Type-Options', value: 'nosniff' },
    ];

    if (process.env.NODE_ENV === 'production') {
      securityHeaders.push({
        key: 'Strict-Transport-Security',
        value: 'max-age=63072000; includeSubDomains; preload',
      });
    }

    return [{ source: '/:path*', headers: securityHeaders }];
  },
};

module.exports = nextConfig;

Zarządzanie sekretami w produkcji

W środowisku produkcyjnym nigdy nie przechowujemy sekretów w plikach .env. Zamiast tego używamy platform do zarządzania sekretami:

# Vercel - dodawanie zmiennych przez CLI
vercel env add DATABASE_URL production
vercel env add JWT_SECRET production
vercel env add OPENAI_API_KEY production

# Vercel - podgląd zmiennych
vercel env ls

# Docker - zmienne przez docker-compose.yml
# docker-compose.yml:
# services:
#   app:
#     environment:
#       - DATABASE_URL=${DATABASE_URL}
#       - JWT_SECRET=${JWT_SECRET}

# GitHub Actions - sekrety w CI/CD
# Settings → Secrets and variables → Actions
# Użycie: ${{ secrets.DATABASE_URL }}

Podsumowanie

Zmienne środowiskowe to fundament bezpiecznej konfiguracji aplikacji Next.js:

  1. Pliki .env - hierarchia: .env.local > .env.production > .env
  2. NEXT_PUBLIC_ prefix - tylko te zmienne trafiają do przeglądarki
  3. Runtime vs Build-time - zmienne serwerowe są dynamiczne, klienckie zamrożone po build
  4. Walidacja z Zod - gwarantuje poprawność konfiguracji
  5. Sekrety w produkcji - nigdy w plikach, zawsze przez platformę hostingową

Przećwicz te koncepcje w edytorze poniżej.

Kod do tej lekcji: App.tsx
import React, { useState } from 'react';

// Demo: Zmienne środowiskowe i konfiguracja produkcyjna
interface EnvVar {
  name: string;
  value: string;
  type: 'server' | 'public';
  file: string;
  description: string;
}

const envVars: EnvVar[] = [
  { name: 'DATABASE_URL', value: 'mongodb://localhost:27017/quantum', type: 'server', file: '.env', description: 'URL bazy danych' },
  { name: 'JWT_SECRET', value: 'dev-secret-key-change-me', type: 'server', file: '.env.local', description: 'Klucz JWT (tajny!)' },
  { name: 'OPENAI_API_KEY', value: 'sk-proj-abc123...', type: 'server', file: '.env.local', description: 'Klucz API OpenAI' },
  { name: 'NEXT_PUBLIC_APP_NAME', value: 'QuantumCity', type: 'public', file: '.env', description: 'Nazwa aplikacji (widoczna w przegladarce)' },
  { name: 'NEXT_PUBLIC_API_URL', value: 'http://localhost:4000/api', type: 'public', file: '.env', description: 'URL API (widoczny w przegladarce)' },
  { name: 'NODE_ENV', value: 'development', type: 'server', file: 'system', description: 'Srodowisko uruchomieniowe' },
];

type EnvFile = '.env' | '.env.local' | '.env.production' | '.env.development';

const fileHierarchy: { file: EnvFile; priority: number; description: string; gitIgnored: boolean }[] = [
  { file: '.env.local', priority: 1, description: 'Lokalne nadpisania (najwyzszy priorytet)', gitIgnored: true },
  { file: '.env.development', priority: 2, description: 'Tylko dla npm run dev', gitIgnored: false },
  { file: '.env.production', priority: 2, description: 'Tylko dla npm run build/start', gitIgnored: false },
  { file: '.env', priority: 3, description: 'Domyslne wartosci', gitIgnored: false },
];

export default function EnvVarsDemo() {
  const [activeTab, setActiveTab] = useState<'vars' | 'hierarchy' | 'validation'>('vars');
  const [filter, setFilter] = useState<'all' | 'server' | 'public'>('all');
  const [showValues, setShowValues] = useState(false);

  const filtered = filter === 'all' ? envVars : envVars.filter(v => v.type === filter);

  const zodSchema = `import { z } from 'zod';

const serverEnvSchema = z.object({
  DATABASE_URL: z.string().url(),
  JWT_SECRET: z.string().min(32),
  OPENAI_API_KEY: z.string().startsWith('sk-'),
  NODE_ENV: z.enum(['development', 'production', 'test']),
});

const clientEnvSchema = z.object({
  NEXT_PUBLIC_APP_NAME: z.string().min(1),
  NEXT_PUBLIC_API_URL: z.string().url(),
});

// Walidacja przy starcie aplikacji
const result = serverEnvSchema.safeParse(process.env);
if (!result.success) {
  throw new Error('Brakujace zmienne!');
}`;

  return (
    <div style={{ background: '#0f0f23', minHeight: '100vh', padding: '20px', color: '#e0e0e0', fontFamily: 'system-ui' }}>
      <h1 style={{ color: '#64ffda', marginBottom: '8px' }}>Zmienne Srodowiskowe</h1>
      <p style={{ color: '#8892b0', marginBottom: '24px' }}>Konfiguracja produkcyjna Next.js</p>

      <div style={{ display: 'flex', gap: '8px', marginBottom: '24px' }}>
        {[
          { id: 'vars' as const, label: 'Zmienne' },
          { id: 'hierarchy' as const, label: 'Hierarchia .env' },
          { id: 'validation' as const, label: 'Walidacja Zod' },
        ].map(t => (
          <button key={t.id} onClick={() => setActiveTab(t.id)} style={{
            padding: '8px 16px', borderRadius: '8px', border: 'none', cursor: 'pointer',
            background: activeTab === t.id ? '#64ffda' : '#1a1a2e', color: activeTab === t.id ? '#0f0f23' : '#8892b0', fontWeight: 'bold',
          }}>{t.label}</button>
        ))}
      </div>

      {activeTab === 'vars' && (
        <div>
          <div style={{ display: 'flex', gap: '8px', marginBottom: '16px' }}>
            {(['all', 'server', 'public'] as const).map(f => (
              <button key={f} onClick={() => setFilter(f)} style={{
                padding: '6px 12px', borderRadius: '6px', border: 'none', cursor: 'pointer', fontSize: '13px',
                background: filter === f ? '#7c3aed' : '#1a1a2e', color: filter === f ? '#fff' : '#8892b0',
              }}>{f === 'all' ? 'Wszystkie' : f === 'server' ? 'Serwerowe' : 'NEXT_PUBLIC_'}</button>
            ))}
            <button onClick={() => setShowValues(!showValues)} style={{
              padding: '6px 12px', borderRadius: '6px', border: '1px solid #333', background: 'transparent', color: '#8892b0', cursor: 'pointer', fontSize: '13px', marginLeft: 'auto',
            }}>{showValues ? 'Ukryj wartosci' : 'Pokaz wartosci'}</button>
          </div>
          <div style={{ display: 'grid', gap: '8px' }}>
            {filtered.map(v => (
              <div key={v.name} style={{
                padding: '12px', borderRadius: '8px', background: '#1a1a2e',
                border: '1px solid ' + (v.type === 'server' ? '#f4433640' : '#64ffda40'),
              }}>
                <div style={{ display: 'flex', alignItems: 'center', gap: '8px', marginBottom: '4px' }}>
                  <code style={{ color: v.type === 'server' ? '#f44336' : '#64ffda', fontWeight: 'bold', fontSize: '13px' }}>{v.name}</code>
                  <span style={{ fontSize: '10px', padding: '2px 6px', borderRadius: '4px', background: v.type === 'server' ? '#f4433620' : '#64ffda20', color: v.type === 'server' ? '#f44336' : '#64ffda' }}>
                    {v.type === 'server' ? 'ONLY SERVER' : 'PUBLIC (browser)'}
                  </span>
                  <span style={{ fontSize: '10px', color: '#666', marginLeft: 'auto' }}>{v.file}</span>
                </div>
                <p style={{ color: '#8892b0', fontSize: '12px', margin: '4px 0 0' }}>{v.description}</p>
                {showValues && <code style={{ color: '#ff9800', fontSize: '12px', display: 'block', marginTop: '4px' }}>{v.value}</code>}
              </div>
            ))}
          </div>
          <div style={{ marginTop: '16px', padding: '12px', borderRadius: '8px', background: '#f4433610', border: '1px solid #f4433630' }}>
            <p style={{ color: '#f44336', fontSize: '13px', margin: 0, fontWeight: 'bold' }}>Uwaga!</p>
            <p style={{ color: '#8892b0', fontSize: '12px', margin: '4px 0 0' }}>Zmienne BEZ prefixu NEXT_PUBLIC_ sa dostepne TYLKO na serwerze. Nigdy nie trafia do przegladarki!</p>
          </div>
        </div>
      )}

      {activeTab === 'hierarchy' && (
        <div>
          <h3 style={{ color: '#64ffda', fontSize: '16px', marginBottom: '12px' }}>Hierarchia plikow .env (od najwyzszego priorytetu)</h3>
          {fileHierarchy.map((f, i) => (
            <div key={f.file} style={{
              padding: '16px', marginBottom: '8px', borderRadius: '8px',
              background: '#1a1a2e', border: '1px solid ' + (i === 0 ? '#64ffda40' : '#33333380'),
              display: 'flex', alignItems: 'center', gap: '16px',
            }}>
              <span style={{ color: '#64ffda', fontSize: '24px', fontWeight: 'bold', width: '30px' }}>{f.priority}</span>
              <div style={{ flex: 1 }}>
                <code style={{ color: '#fff', fontWeight: 'bold' }}>{f.file}</code>
                <p style={{ color: '#8892b0', fontSize: '12px', margin: '4px 0 0' }}>{f.description}</p>
              </div>
              <span style={{ fontSize: '11px', padding: '2px 8px', borderRadius: '4px', background: f.gitIgnored ? '#f4433620' : '#4caf5020', color: f.gitIgnored ? '#f44336' : '#4caf50' }}>
                {f.gitIgnored ? '.gitignore' : 'commitowany'}
              </span>
            </div>
          ))}
        </div>
      )}

      {activeTab === 'validation' && (
        <div>
          <h3 style={{ color: '#64ffda', fontSize: '16px', marginBottom: '12px' }}>Walidacja z Zod (wzorzec t3-env)</h3>
          <pre style={{ background: '#1a1a2e', padding: '16px', borderRadius: '8px', fontSize: '12px', overflow: 'auto', border: '1px solid #333', whiteSpace: 'pre-wrap' }}>
            {zodSchema}
          </pre>
          <p style={{ color: '#8892b0', fontSize: '13px', marginTop: '12px' }}>Walidacja zmiennych przy starcie aplikacji zapobiega bledom w runtime.</p>
        </div>
      )}
    </div>
  );
}

Hasła z dokumentacji w tej lekcji

Widzisz błąd w tej lekcji?

Sprawdź się

Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.

  1. 1. Co oznacza prefix NEXT_PUBLIC_ przy zmiennych środowiskowych w Next.js?

  2. 2. Który plik .env ma NAJWYŻSZY priorytet w Next.js?

To 2 z 3 pytań do tej lekcji. Pozostałe rozwiążesz w grze.

  1. PytaniePrefix NEXT_PUBLIC_ w Next.js
  2. PytanieHierarchia plików .env w Next.js
  3. PytanieZmienne build-time vs runtime w Next.js

Przydatne artykuły