done fix

docs/02-app/02-api-reference/05-next-config-js/output.mdx

@@ -39,8 +39,8 @@ Additionally, a minimal `server.js` file is also output which can be used instea
 
 > **Good to know**:
 >
+> - If your project needs to listen to a specific port or hostname, you can define `PORT` or `HOSTNAME` environment variables before running `server.js`. For example, run `PORT=8080 HOSTNAME=0.0.0.0 node server.js` to start the server on `http://0.0.0.0:8080`.
 > - If your project uses [Image Optimization](/docs/app/building-your-application/optimizing/images) with the default `loader`, you must install `sharp` as a dependency:
-> - If your project needs alternative port or hostname for listening, you can define `PORT` and `HOSTNAME` environment variables, before running `server.js`. For example, `PORT=3000 HOSTNAME=localhost node server.js`.
 
 </AppOnly>
 
@@ -49,6 +49,7 @@ Additionally, a minimal `server.js` file is also output which can be used instea
 > **Good to know**:
 >
 > - `next.config.js` is read during `next build` and serialized into the `server.js` output file. If the legacy [`serverRuntimeConfig` or `publicRuntimeConfig` options](/docs/pages/api-reference/next-config-js/runtime-configuration) are being used, the values will be specific to values at build time.
+> - If your project needs to listen to a specific port or hostname, you can define `PORT` or `HOSTNAME` environment variables before running `server.js`. For example, run `PORT=8080 HOSTNAME=0.0.0.0 node server.js` to start the server on `http://0.0.0.0:8080`.
 > - If your project uses [Image Optimization](/docs/pages/building-your-application/optimizing/images) with the default `loader`, you must install `sharp` as a dependency:
 
 </PagesOnly>

examples/with-docker-multi-env/docker/development/Dockerfile

@@ -47,6 +47,8 @@ USER nextjs
 EXPOSE 3000
 
 ENV PORT 3000
-ENV HOSTNAME localhost
+# Uncomment the following line if `process.env.HOSTNAME` is not provided by your provider
+# and `localhost` doesn't work with your use case.
+# ENV HOSTNAME 0.0.0.0
 
 CMD ["node", "server.js"]

examples/with-docker-multi-env/docker/production/Dockerfile

@@ -48,6 +48,8 @@ USER nextjs
 EXPOSE 3000
 
 ENV PORT 3000
-ENV HOSTNAME localhost
+# Uncomment the following line if `process.env.HOSTNAME` is not provided by your provider
+# and `localhost` doesn't work with your use case.
+# ENV HOSTNAME 0.0.0.0
 
 CMD ["node", "server.js"]

examples/with-docker-multi-env/docker/staging/Dockerfile

@@ -48,6 +48,8 @@ USER nextjs
 EXPOSE 3000
 
 ENV PORT 3000
-ENV HOSTNAME localhost
+# Uncomment the following line if `process.env.HOSTNAME` is not provided by your provider
+# and `localhost` doesn't work with your use case.
+# ENV HOSTNAME 0.0.0.0
 
 CMD ["node", "server.js"]

examples/with-docker/Dockerfile

@@ -59,7 +59,8 @@ USER nextjs
 EXPOSE 3000
 
 ENV PORT 3000
-# set hostname to localhost
-ENV HOSTNAME "0.0.0.0"
+# Uncomment the following line if `process.env.HOSTNAME` is not provided by your provider
+# and `localhost` doesn't work with your use case.
+# ENV HOSTNAME 0.0.0.0
 
 CMD ["node", "server.js"]

packages/next/src/experimental/testmode/server.ts

@@ -5,8 +5,8 @@ import type {
   ProxyResponse,
 } from './proxy'
 import { ClientRequestInterceptor } from 'next/dist/compiled/@mswjs/interceptors/ClientRequest'
-import { WorkerRequestHandler } from '../../server/lib/setup-server-worker'
-import { NodeRequestHandler } from '../../server/next-server'
+import type { WorkerRequestHandler } from '../../server/lib/setup-server-worker'
+import type { NodeRequestHandler } from '../../server/next-server'
 
 interface TestReqInfo {
   url: string

packages/next/src/server/lib/format-hostname.ts

@@ -6,7 +6,6 @@ import { isIPv6 } from './is-ipv6'
  * @param hostname
  * @returns
  */
-
 export function formatHostname(hostname: string): string {
   return isIPv6(hostname) ? `[${hostname}]` : hostname
 }

packages/next/src/server/lib/get-fetch-hostname.ts

@@ -0,0 +1,19 @@
+import { formatHostname } from './format-hostname'
+
+/**
+ * Gets the hostname used to fetch pages (also checks whether the server
+ * is running on `0.0.0.0` or `::`).
+ * @param actualHostname - The host the server runs on.
+ * @param providedHostname - The hostname the user provides.
+ * @returns
+ */
+export function getFetchHostname(
+  actualHostname: string,
+  providedHostname: string | undefined
+) {
+  return actualHostname === '0.0.0.0'
+    ? 'localhost'
+    : actualHostname === '::'
+    ? '[::1]'
+    : formatHostname(providedHostname || actualHostname)
+}

packages/next/src/server/lib/render-server.ts

@@ -2,9 +2,9 @@ import type { RequestHandler } from '../next'
 
 // this must come first as it includes require hooks
 import { initializeServerWorker } from './setup-server-worker'
-import { formatHostname } from './format-hostname'
 import next from '../next'
 import { PropagateToWorkersField } from './router-utils/types'
+import { getFetchHostname } from './get-fetch-hostname'
 
 export const WORKER_SELF_EXIT_CODE = 77
 
@@ -102,11 +102,8 @@ export async function initialize(opts: {
     ...opts,
     _routerWorker: opts.workerType === 'router',
     _renderWorker: opts.workerType === 'render',
-    hostname,
     customServer: false,
     httpServer: server,
-    port: opts.port,
-    isNodeDebugging: opts.isNodeDebugging,
   })
 
   requestHandler = app.getRequestHandler()
@@ -115,7 +112,7 @@ export async function initialize(opts: {
 
   result = {
     port,
-    hostname: formatHostname(hostname),
+    hostname: getFetchHostname(hostname, opts.hostname),
   }
 
   return result

packages/next/src/server/lib/setup-server-worker.ts

@@ -87,7 +87,6 @@ export async function initializeServerWorker(
         upgradeHandler(req, socket, upgrade)
       })
     }
-    let hostname = opts.hostname || 'localhost'
 
     server.on('listening', async () => {
       try {
@@ -116,6 +115,6 @@ export async function initializeServerWorker(
         return reject(err)
       }
     })
-    server.listen(0, hostname)
+    server.listen(0, opts.hostname)
   })
 }

packages/next/src/server/lib/start-server.ts

@@ -11,11 +11,12 @@ import { getDebugPort } from './utils'
 import { formatHostname } from './format-hostname'
 import { initialize } from './router-server'
 import fs from 'fs'
-import {
+import type {
   WorkerRequestHandler,
   WorkerUpgradeHandler,
 } from './setup-server-worker'
 import { checkIsNodeDebugging } from './is-node-debugging'
+import { getFetchHostname } from './get-fetch-hostname'
 const debug = setupDebug('next:start-server')
 
 if (process.env.NEXT_CPU_PROF) {
@@ -28,7 +29,7 @@ export interface StartServerOptions {
   port: number
   logReady?: boolean
   isDev: boolean
-  hostname: string
+  hostname?: string
   allowRetry?: boolean
   customServer?: boolean
   minimalMode?: boolean
@@ -54,7 +55,7 @@ export async function getRequestHandlers({
   dir: string
   port: number
   isDev: boolean
-  hostname: string
+  hostname?: string
   minimalMode?: boolean
   isNodeDebugging?: boolean
   keepAliveTimeout?: number
@@ -187,18 +188,15 @@ export async function startServer({
   await new Promise<void>((resolve) => {
     server.on('listening', async () => {
       const addr = server.address()
-      const actualHostname = formatHostname(
+      const host =
         typeof addr === 'object'
           ? addr?.address || hostname || 'localhost'
           : addr
-      )
 
-      const formattedHostname =
-        !hostname || actualHostname === '0.0.0.0'
-          ? 'localhost' 
-          : actualHostname === '[::]' 
-          ? '[::1]'
-          : formatHostname(hostname)
+      // The server's actual host
+      const formattedServerHost = formatHostname(host)
+      // appUrl's host - the server should respond when this hostname is fetched
+      const formattedHostname = getFetchHostname(host, hostname)
 
       port = typeof addr === 'object' ? addr?.port || port : port
       const appUrl = `${
@@ -215,7 +213,9 @@ export async function startServer({
       }
 
       if (logReady) {
-        Log.ready(`started server on ${actualHostname}:${port}, url: ${appUrl}`)
+        Log.ready(
+          `started server on ${formattedServerHost}:${port}, url: ${appUrl}`
+        )
         // expose the main port to render workers
         process.env.PORT = port + ''
       }

packages/next/src/server/next.ts

@@ -19,7 +19,7 @@ import { PHASE_PRODUCTION_SERVER } from '../shared/lib/constants'
 import { getTracer } from './lib/trace/tracer'
 import { NextServerSpan } from './lib/trace/constants'
 import { formatUrl } from '../shared/lib/router/utils/format-url'
-import {
+import type {
   WorkerRequestHandler,
   WorkerUpgradeHandler,
 } from './lib/setup-server-worker'