nextjs环境变量带NEXT_PUBLIC_和不带NEXT_PUBLIC_的区别

[🧠 1️⃣ 核心规则（一句话）](#🧠 1️⃣ 核心规则（一句话）)

[🌐 2️⃣ NEXT_PUBLIC_ 的作用](#🌐 2️⃣ NEXT_PUBLIC_ 的作用)

[✔️ 可以在前端使用](#✔️ 可以在前端使用)

[⚠️ 注意：](#⚠️ 注意：)

[🔒 3️⃣ 不带 NEXT_PUBLIC_ 的变量（服务端专用）](#🔒 3️⃣ 不带 NEXT_PUBLIC_ 的变量（服务端专用）)

[✔️ 只能在：](#✔️ 只能在：)

[❌ 前端不能用：](#❌ 前端不能用：)

[🚨 4️⃣ Next.js 的安全设计本质](#🚨 4️⃣ Next.js 的安全设计本质)

[📦 5️⃣ 实际运行机制（很重要）](#📦 5️⃣ 实际运行机制（很重要）)

[✔️ 服务端阶段](#✔️ 服务端阶段)

[✔️ 构建阶段](#✔️ 构建阶段)

[⚠️ 6️⃣ 常见误区（非常重要）](#⚠️ 6️⃣ 常见误区（非常重要）)

[❌ 误区1：以为 NEXT_PUBLIC 是加密的](#❌ 误区1：以为 NEXT_PUBLIC 是加密的)

[❌ 误区2：把敏感信息写 NEXT_PUBLIC](#❌ 误区2：把敏感信息写 NEXT_PUBLIC)

[❌ 误区3：以为服务端变量前端"读不到但安全"](#❌ 误区3：以为服务端变量前端“读不到但安全”)

[🧪 7️⃣ 推荐使用方式（实战）](#🧪 7️⃣ 推荐使用方式（实战）)

[🔵 前端变量（必须 NEXT_PUBLIC）](#🔵 前端变量（必须 NEXT_PUBLIC）)

[🔴 服务端变量（绝不能暴露）](#🔴 服务端变量（绝不能暴露）)

[🚀 8️⃣ Web3 项目特别提醒（重点）](#🚀 8️⃣ Web3 项目特别提醒（重点）)

[❌ 不要这样：](#❌ 不要这样：)

[✔️ 应该这样：](#✔️ 应该这样：)

[🧠 9️⃣ 一句话总结](#🧠 9️⃣ 一句话总结)

在 Next.js 里，环境变量是否带 NEXT_PUBLIC_，本质区别只有一个核心点：

👉 是否会暴露到浏览器端（客户端）

🧠 1️⃣ 核心规则（一句话）

前缀	运行位置	是否暴露给前端
`NEXT_PUBLIC_`	浏览器 + 服务端	✅ 会暴露
无前缀	仅服务端	❌ 不会暴露

🌐 2️⃣ NEXT_PUBLIC_ 的作用

复制代码

NEXT_PUBLIC_API_URL=https://api.example.com

✔️ 可以在前端使用

复制代码

console.log(process.env.NEXT_PUBLIC_API_URL)

👉 浏览器 JS 里也能看到

⚠️ 注意：

❗ 任何 NEXT_PUBLIC_ 都等于"公开变量"

比如：

API base URL
feature flag
公共配置

🔒 3️⃣ 不带 NEXT_PUBLIC_ 的变量（服务端专用）

复制代码

DATABASE_URL=postgres://...
JWT_SECRET=xxxx
PRIVATE_KEY=xxxx

✔️ 只能在：

Server Components
Route Handlers（app/api）
getServerSideProps（旧模式）

console.log(process.env.DATABASE_URL)

❌ 前端不能用：

复制代码

console.log(process.env.DATABASE_URL) // undefined

🚨 4️⃣ Next.js 的安全设计本质

Next.js 默认策略是：

👉 "所有变量默认私有，必须显式声明才暴露"

📦 5️⃣ 实际运行机制（很重要）

✔️ 服务端阶段

复制代码

Node.js 读取 .env

✔️ 构建阶段

复制代码

NEXT_PUBLIC_* 被"注入"进前端 bundle

👉 变成静态 JS 常量

⚠️ 6️⃣ 常见误区（非常重要）

❌ 误区1：以为 NEXT_PUBLIC 是加密的

不是。

它只是"允许前端访问"，不是保护机制

❌ 误区2：把敏感信息写 NEXT_PUBLIC

比如：

复制代码

NEXT_PUBLIC_JWT_SECRET=xxx ❌
NEXT_PUBLIC_PRIVATE_KEY=xxx ❌

👉 这等于直接公开给所有用户

❌ 误区3：以为服务端变量前端"读不到但安全"

错。

只要你不写 NEXT_PUBLIC，它才不会进 bundle

🧪 7️⃣ 推荐使用方式（实战）

🔵 前端变量（必须 NEXT_PUBLIC）

复制代码

NEXT_PUBLIC_APP_ENV=production
NEXT_PUBLIC_API_URL=https://api.xxx.com
NEXT_PUBLIC_WALLETCONNECT_ID=xxx

🔴 服务端变量（绝不能暴露）

复制代码

DATABASE_URL
JWT_SECRET
PRIVY_SECRET_KEY
PRIVATE_RPC_URL

🚀 8️⃣ Web3 项目特别提醒（重点）

如果你做：

Wallet 登录
Privy
RPC
API key

❌ 不要这样：

复制代码

NEXT_PUBLIC_PRIVY_SECRET ❌

✔️ 应该这样：

复制代码

PRIVY_SECRET_KEY ✔️ (server only)

🧠 9️⃣ 一句话总结

NEXT_PUBLIC_ = "允许浏览器看到"

不带前缀 = "只能后端用，浏览器永远看不到"