Environment Variables Explained Like You're 5
作者： Salty Deprecated Software Engineer
本文由 AI 辅助创作，并经团队审核以确保准确性和质量。所有技术信息和示例均已验证。
Every tutorial says "add your API key to a .env file" like you should know what that means. Nobody explains whythere's a .env file, what happens if you forget one, or why your app works on your machine but crashes on the server.
Environment variables are the simplest concept in software that everyone overcomplicates.Here's the entire idea in one sentence:
Environment variables are settings that change depending on where your code runs.
Your code stays the same. The database URL, the API key, the payment gateway — those change between your laptop, the test server, and production. Environment variables are how you tell your app "here's the right value for thisenvironment."
The Restaurant Analogy
Imagine a restaurant recipe (your code) that says "add salt." How much salt depends on where the dish is being served:
- Development (your kitchen at home): A pinch. Experimenting. Doesn't matter if it's wrong.
- Staging (taste test): The real amount. Testing before the restaurant opens.
- Production (serving customers): The exact, measured amount. No mistakes.
The recipe doesn't change. The salt amount (environment variable) does.
What a .env File Looks Like
# .env.local (your machine only, never committed to git)
DATABASE_URL=postgres://localhost:5432/myapp_dev
STRIPE_SECRET_KEY=sk_test_abc123
NEXT_PUBLIC_SITE_URL=http://localhost:3000
# Lines starting with # are comments
# No quotes around values (usually)
# No spaces around the = sign
That's it. It's a list of KEY=VALUE pairs. Your code reads these values instead of hardcoding them.
Why Not Just Hardcode Values?
Three reasons, each one learned the hard way by someone before you:
- Security. If you put your Stripe API key directly in your code and push it to GitHub, anyone can find it. Bots scan public repos for API keys — you'll get a bill within hours.
- Flexibility. Your development database is at localhost. Your production database is at some-aws-url.com. If the URL is hardcoded, you'd need different code for each environment.
- Teamwork. Every developer has their own API keys, their own test accounts, their own local database. Env files let each person configure their own setup without changing shared code.
How Your Code Reads Them
const dbUrl = process.env.DATABASE_URL;
import os
db_url = os.environ.get('DATABASE_URL')
echo $DATABASE_URL
The File Naming Convention
.env — Default values, sometimes committed to git (non-secret only).env.local — Your machine only. Never committed. Overrides .env.env.development — Used during npm run dev.env.production — Used during production builds.env.example — Template showing which variables are needed (committed to git, no real values)The 5 Mistakes Everyone Makes
- 1. Committing .env.local to git. This exposes your secrets. Add
.env*.localto your .gitignore immediately. - 2. Forgetting to restart the server. Most frameworks only read env files at startup. Changed a variable? Restart.
- 3. Adding spaces around =.
KEY = valuebreaks in most parsers. UseKEY=value. - 4. Missing NEXT_PUBLIC_ prefix. In Next.js, only variables starting with
NEXT_PUBLIC_are available in the browser. Without it, the variable is server-only. - 5. No .env.example file. New developers join your project and have no idea which variables are needed. Always maintain an example file with placeholder values.
The Bottom Line
Environment variables are not complicated — they're just configuration that changes per environment. Put secrets in .env.local, never commit them, restart your server after changes, and keep a .env.example so your teammates (and future you) know what's needed.
Building a project that needs environment variables? Our free Password Generator creates strong API keys and secrets, and our .gitignore Generator makes sure your .env files never get committed.
以 The IT Hustle 的编辑笔名写作——25 年以上笔记本维修技师、系统管理员、存储工程师和软件工程师的经验,如今用在 AI 智能体运维上。每篇文章发布前都经过人工审核,详见编辑准则。
获取最新资讯
第一时间了解新工具、博客文章和更新动态。无垃圾邮件。