NEXT_PUBLIC_ is an instruction to the compiler, not a runtime feature. During next build, every reference spelled process.env.NEXT_PUBLIC_X is replaced with the value from the build environment. Browsers have no process.env, so a literal in the JavaScript is the only way the value can reach them.
On Next.js 16.4.5 I built with NEXT_PUBLIC_X=a SECRET=s1 and started with NEXT_PUBLIC_X=b SECRET=s2:
- Client chunk: the source
dotted: process.env.NEXT_PUBLIC_Xwasdotted:"a"in.next/static/chunks/*.js. No rebuild, no change. - Server bundle: also inlined. A dynamic Server Component printed
x: "a"; the built code read{x:"a",secret:process.env.SECRET. - Non-prefixed variables stay real lookups on the server: the same dynamic page printed
SECRETass2, and a.envvalue edited between build and start was read fresh. - Static pages freeze everything. The prerendered
/showeda,s1and the old.envvalue, because it ran once, at build.
Only the literal process.env.NAME form is replaced. Destructuring (const { NEXT_PUBLIC_X } = process.env) and a key held in a prop stayed runtime lookups: b in the server render, undefined in Chrome 156 and Firefox 159.
So one image promoted from staging to production carries staging's public values. The fix the docs give is to keep per-environment values on the server: read them in a dynamically rendered Server Component (await connection(), or any request API, makes it per request) and pass them to Client Components as props, or serve them from your own endpoint. Otherwise, build once per environment.