Next.js - 环境变量

Next.js 提供了内置的环境变量支持，允许你管理诸如 API 密钥、数据库凭证或功能标志等配置设置，而无需将其硬编码到应用程序中。

环境变量通常定义在项目根目录下的 .env 文件中。

.env.local: 所有环境的默认值。此文件应添加到 .gitignore 中，因为它可能包含敏感的密钥。
.env.development: 开发环境（npm run dev）特有的变量。
.env.production: 生产环境（npm run build，npm run start）特有的变量。
.env: 默认值（可以提交到 Git，但不应包含密钥）。

Next.js 根据当前环境从这些文件中加载变量。.env.local 始终覆盖默认值，而环境特定的文件（.env.development、.env.production）覆盖 .env.local。

创建 `.env.local`

在项目根目录下创建一个名为 .env.local 的文件，内容示例如下：

# Database Credentials (Server-Side Only)
# 数据库凭证（仅服务器端）
DB_HOST=localhost
DB_USER=myuser
DB_PASS=supersecretpassword

# Public API Key (Client-Side Accessible)
# 公共 API 密钥（客户端可访问）
NEXT_PUBLIC_ANALYTICS_ID=G-XYZ123ABC

# Feature Flag
# 功能标志
ENABLE_BETA_FEATURE=true

重要安全提示： 默认情况下，定义在 .env 文件中的环境变量仅在服务器端可用（在 Server Components、Route Handlers 或服务器端数据获取函数中）。若要将变量暴露给浏览器（用于 Client Components），必须在其前面加上 NEXT_PUBLIC_ 前缀。

访问环境变量

你可以使用 process.env.VARIABLE_NAME 访问环境变量。

让我们创建一个页面组件（app/config-demo/page.tsx）来演示如何访问服务器端和客户端变量。由于我们需要展示一个客户端变量，我们将创建一个单独的 Client Component。

创建 Client Component（app/config-demo/client-config-display.tsx）：

'use client'; // Mark this as a Client Component
// 将此标记为客户端组件

export default function ClientConfigDisplay() {
  // Access the public environment variable
  // 访问公共环境变量
  const analyticsId = process.env.NEXT_PUBLIC_ANALYTICS_ID;

  return (
    <div>
      <h3>Client-Side Configuration</h3>
      <p>Analytics ID: {analyticsId || 'Not Set'}</p>
      {/* Trying to access DB_HOST here would result in 'undefined' */}
      {/* 在这里尝试访问 DB_HOST 将得到 'undefined' */}
      {/* <p>DB Host (Client Attempt): {process.env.DB_HOST}</p> */}
    </div>
  );
}

创建主页面组件（app/config-demo/page.tsx）：

import ClientConfigDisplay from './client-config-display';

export default function ConfigDemoPage() {
  // Access server-side environment variables directly
  // 直接访问服务器端环境变量
  const dbHost = process.env.DB_HOST;
  const dbUser = process.env.DB_USER;
  // Note: Avoid rendering sensitive variables like passwords directly!
  // 注意：避免直接渲染敏感变量，如密码！
  // const dbPass = process.env.DB_PASS;
  const isBetaEnabled = process.env.ENABLE_BETA_FEATURE === 'true';

  return (
    <main>
      <h1>Environment Variable Demo</h1>

      <h2>Server-Side Configuration</h2>
      <p>Database Host: {dbHost || 'Not Set'}</p>
      <p>Database User: {dbUser || 'Not Set'}</p>
      <p>Beta Feature Enabled: {isBetaEnabled ? 'Yes' : 'No'}</p>

      <hr style={{ margin: '20px 0' }} />

      {/* Render the Client Component */}
      {/* 渲染客户端组件 */}
      <ClientConfigDisplay />
    </main>
  );
}

当你运行 npm run dev 时，Next.js 会自动从 .env.local 文件加载变量。

npm run dev
# ... server startup messages ...
# ... 服务器启动信息 ...
# You might see a line like:
# 你可能会看到类似这样一行：
# info  - Loaded env from /path/to/your/project/.env.local

验证输出

在浏览器中打开 http://localhost:3000/config-demo。你应该会看到 .env.local 文件中的值被显示出来：

“Server-Side Configuration”部分将显示 DB_HOST、DB_USER 和 Beta 功能的状态。“Client-Side Configuration”部分（由 Client Component 渲染）将显示 NEXT_PUBLIC_ANALYTICS_ID。请注意，像 DB_HOST 这样仅服务器端可用的变量在 Client Component 中是无法访问的。

Next.js - 环境变量

Next.js - 环境变量

创建 .env.local

访问环境变量

验证输出

创建 `.env.local`