The correct way to manage environment variables in Next.js applications is to use named specifications .env files and ensure security. 1. Create .env files of different environments such as .env.local, .env.development, .env.production and .env.test, where variables prefixed with NEXT_PUBLIC_ will be exposed to the client; 2. Access variables securely in the code, always provide default values to prevent missing, and only use non-public variables on the server side; 3. Configure environment variables through deployment platforms (such as Vercel, Netlify or cloud services) in the production environment to avoid dependency files; 4. Add sensitive files such as .env.local to .gitignore to prevent leakage; 5. Use verification logic to check necessary variables at startup, which can be implemented through a custom config module; 6. Note that statically generated pages solidify environment variables when building. Dynamic configuration needs to be obtained through API routing or client requests, ultimately ensuring that sensitive information does not enter the front-end code and the configuration is maintained.

Handling environment variables in a Next.js app is essential for managing configuration across different environments—like development, staging, and production—without exposing sensitive data. Here's how to do it properly and securely.

Use .env Files with Proper Naming

Next.js supports .env files out of the box. You can create different files for different environments:

• .env.local – Local environment variables (used in all environments, not committed to version control)
• .env.development – Only loaded in development
• .env.production – Only loaded in production
• .env.test – Used during testing

?? Important : Only variables prefixed with NEXT_PUBLIC_ are exposed to the browser. Others are kept server-side and not accessible on the client.

Example .env.local :

 # Server-side only (safe for secrets)
API_SECRET=your_secret_key
DATABASE_URL=postgresql://user:pass@localhost:5432/mydb

# Client-side accessible
NEXT_PUBLIC_API_URL=https://api.example.com
NEXT_PUBLIC_ANALYTICS_ID=ga-123456

These values can then be accessed in your code:

 // Accessible anywhere
console.log(process.env.NEXT_PUBLIC_API_URL);

// Only available on the server (eg, API routes, getStaticProps, etc.)
console.log(process.env.API_SECRET);

Access Environment Variables Safely

Always assume environment variables might be undefined, especially during build or if misconfigured.

? Good practice – provide fallbacks :

 const apiUrl = process.env.NEXT_PUBLIC_API_URL || 'http://localhost:3000/api';

? Avoid direct usage without checks:

 // Risky if variable is missing
fetch(`${process.env.API_URL}/users`);

Also, remember:

• Client-side : Only NEXT_PUBLIC_ variables are available.
• Server-side (Node.js context) : All variables (including non-prefixed ones) are available.

This includes:

• getStaticProps
• getServerSideProps
• API routes
• middleware.js

Set Environment Variables in Production

During deployment, avoid relying on .env files in production. Instead:

1. Use your hosting platform's environment variable UI or CLI :

   • Vercel : Go to Project Settings → Environment Variables
   • Netlify : Site Settings → Build & Deploy → Environment
   • AWS, GCP, Docker, etc. : Set via deployment config or orchestration tools

2. Never commit .env.local
   Add it to .gitignore :

    .env.local
   *.env.local

3. For CI/CD pipelines, inject secrets via encrypted environment variables or secret managers.

Validate Required Environment Variables

You can add a validation step at startup to catch missing critical variables.

Create a helper, eg, lib/env.js :

 const required = (name) => {
  if (!process.env[name]) {
    throw new Error(`Missing environment variable: ${name}`);
  }
  return process.env[name];
};

export const config = {
  apiUrl: required('NEXT_PUBLIC_API_URL'),
  analyticsId: process.env.NEXT_PUBLIC_ANALYTICS_ID,
  apiSecret: required('API_SECRET'), // Only used server-side
};

Then import config in your API routes or config files to ensure early failure if something's missing.

Bonus: Runtime vs Build-Time Variables

• Build-time variables : Defined when the app is built ( next build ).
  Used in getStaticProps and static generation.

• Runtime variables : For server-rendered or API routes, values are read at request time.
  This means you can update secrets without rebuilding (if your hosting support dynamic env vars).

?? Static pages (ISR or SSG) will bake in environment values at build time. So if you rely on dynamic configuration, consider using API routes or client-side fetching.

Basically, stick to the NEXT_PUBLIC_ rule, keep secrets out of client code, validate inputs, and manage production variables through your deployment platform. It's simple but easy to mess up—so be deliberate.

The above is the detailed content of How to Handle Environment Variables in a Next.js App. For more information, please follow other related articles on the PHP Chinese website!