⚙️ Next.js 多环境部署全攻略

🧭 一、为什么要进行多环境部署？

在现代 Web 开发中，我们常常需要在不同环境中测试与上线：

环境	说明	典型用途
🧪 Development	本地开发环境	本地调试、快速重启、实验功能
👀 Preview (Staging)	临时预览环境	Pull Request 预览、产品验收测试
🚀 Production	线上正式环境	最终用户访问

在 Vercel 上，这三个环境会自动对应到你的部署阶段：

本地运行：next dev → Development

分支部署：git push feature/... → Preview

合并主分支：git push main → Production

🌱 二、环境变量的分离与管理

Next.js 内置了对多环境变量文件的支持，你可以在根目录下创建以下文件：

bash 复制代码

.env.local         # 本地开发环境
.env.development   # `next dev` 使用
.env.preview       # Vercel Preview 环境使用
.env.production    # Vercel Production 环境使用

🧩 示例变量配置

`.env.local`

ini 复制代码

NEXT_PUBLIC_API_BASE=http://localhost:3000/api
PRIVATE_KEY_LOCAL=dev_secret

`.env.preview`

ini 复制代码

NEXT_PUBLIC_API_BASE=https://preview-api.example.com
PRIVATE_KEY_PREVIEW=preview_secret

`.env.production`

ini 复制代码

NEXT_PUBLIC_API_BASE=https://api.example.com
PRIVATE_KEY_PRODUCTION=prod_secret

🧠 三、Next.js 环境变量加载逻辑

Next.js 会在构建时读取环境变量，根据运行命令自动选择优先级：

优先级从高到低：

bash 复制代码

.env.local > .env.[mode] > .env

并且：

以 NEXT_PUBLIC_ 开头的变量会暴露到浏览器端。
其他变量（如数据库密钥）仅在 Node.js 端可访问。

⚡ 四、在 Vercel 中配置环境变量

当部署在 Vercel 上时，环境变量的管理可以更轻松。

🧩 操作步骤：

打开项目 → 点击 Settings → Environment Variables
添加以下键值：

Name	Value	Environment
`NEXT_PUBLIC_API_BASE`	`http://localhost:3000/api`	Development
`NEXT_PUBLIC_API_BASE`	`https://preview-api.example.com`	Preview
`NEXT_PUBLIC_API_BASE`	`https://api.example.com`	Production

💡 一次设置即可，推送/部署时 Vercel 自动选取对应的环境。

🧰 五、Vercel CLI 配置与部署流程

安装 CLI：

复制代码

npm install -g vercel

登录并初始化：

csharp 复制代码

vercel login
vercel init

📦 部署命令：

命令	作用
`vercel dev`	启动本地 Vercel 模拟环境（等价于 `next dev`）
`vercel`	部署到 Preview 环境（默认）
`vercel --prod`	部署到 Production

🌍 示例输出

vbnet 复制代码

▲ Vercel CLI 31.0.1
Deploying Next.js project to Vercel...
✔️  https://myapp-preview.vercel.app   (preview)
→ Run `vercel --prod` to deploy to production.

🧩 六、在代码中使用环境变量（JS示例）

javascript 复制代码

export default function ApiDemo() {
  const base = process.env.NEXT_PUBLIC_API_BASE;

  async function loadData() {
    const res = await fetch(`${base}/lessons`);
    const data = await res.json();
    console.log("👀 当前环境来自于：", base);
  }

  return (
    <div>
      <h3>🌐 当前环境: {base}</h3>
      <button onClick={loadData}>加载数据</button>
    </div>
  );
}

🧠 七、加点幽默的总结

Development 是"想法冒泡"的温床。

Preview 是"老板先别上线，我再改两下"的保险阀。

Production 是"上线那一刻，所有 commit 都变成命运的签名"。

而你，作为开发者，不再需要在 .env 文件中手忙脚乱地切换。

一条命令，一个环境，一个世界。

🚀 八、快速总结图

css 复制代码

graph TD
A[本地 Dev 环境] -->|vercel| B[Preview 环境 (分支)]
B -->|vercel --prod| C[Production 正式环境]
A --> D[.env.local]
B --> E[.env.preview]
C --> F[.env.production]

🎯 最佳实践：

使用 .env.xxx 文件分离不同环境。
对外暴露变量必须加 NEXT_PUBLIC_ 前缀。
通过 Vercel 环境管理控制 Preview/Prod。
使用 vercel / vercel --prod 明确部署目标。