Kurs Next.js · Moduł 8: Deployment i produkcja
Zmienne środowiskowe i konfiguracja produkcyjna
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 środowiskKaż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=productionPrefix 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ędziePrzykł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:
- Pliki .env - hierarchia:
.env.local>.env.production>.env - NEXT_PUBLIC_ prefix - tylko te zmienne trafiają do przeglądarki
- Runtime vs Build-time - zmienne serwerowe są dynamiczne, klienckie zamrożone po build
- Walidacja z Zod - gwarantuje poprawność konfiguracji
- 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. Co oznacza prefix NEXT_PUBLIC_ przy zmiennych środowiskowych w Next.js?
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.