第 29 讲：Node Server / Standalone / Adapter 三种部署形态

┌──────────────────────────────────────────────────┐
│ 形态 1: next start                                 │
│ ──────────────────                                │
│ pnpm start                                        │
│ ↓                                                 │
│ bin/next.ts → cli/next-start.ts                  │
│ ↓                                                 │
│ startServer() 起 http.createServer               │
│ ↓                                                 │
│ router-server worker (Node Worker Thread)        │
│ ↓                                                 │
│ render-server worker (默认进同进程)                │
│ ↓                                                 │
│ NextNodeServer.handleRequest                     │
└──────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────┐
│ 形态 2: output: 'standalone'                       │
│ ────────────────────────────                      │
│ node .next/standalone/server.js                  │
│ ↓                                                 │
│ 内嵌一个轻量 startServer                          │
│ ↓                                                 │
│ 同样起 http.createServer + router-server         │
│ 区别: 不依赖外部 node_modules                     │
└──────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────┐
│ 形态 3: Vercel/Cloudflare Adapter                 │
│ ──────────────────────────────────                │
│ Vercel 部署器读 required-server-files.json        │
│ ↓                                                 │
│ 每个 route handler/page 打成一个 serverless fn    │
│ ↓                                                 │
│ 平台分配 region/runtime/memory                    │
│ ↓                                                 │
│ 请求来时 lambda invoke                            │
│ ↓                                                 │
│ 内部仍是 NextNodeServer.handleRequest             │
│ 区别: 没有 http server，request 由平台代为接入     │
└──────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────┐
│ 形态 4: Custom Server (express/koa/...)           │
│ ──────────────────────────────────                │
│ const next = require('next')                     │
│ const app = next({ dir: '.', dev: false })       │
│ const handle = app.getRequestHandler()           │
│ express().all('*', (req, res) => handle(req, res)) │
│                                                   │
│ 区别: 用户自己起 server，把请求转给 Next handler   │
└──────────────────────────────────────────────────┘

pnpm start

const nextStart = async (options: NextStartOptions, directory?: string) => {
  const dir = getProjectDir(directory)
  const hostname = options.hostname
  const inspect = options.inspect
  const port = options.port
  const keepAliveTimeout = options.keepAliveTimeout

  if (isPortIsReserved(port)) {
    printAndExit(getReservedPortExplanation(port), 1)
  }

  if (inspect) {
    const inspector = await import('inspector')
    // ... 启用 --inspect debugger
  }

  if (options.experimentalCpuProf) {
    Log.info(`CPU profiling enabled. Profile will be saved on exit (Ctrl+C).`)
    process.on('SIGTERM', () => saveCpuProfile())
    process.on('SIGINT', () => saveCpuProfile())
  }

  await startServer({
    dir,
    isDev: false,
    hostname,
    port,
    keepAliveTimeout,
  })
}

export async function startServer(serverOptions: StartServerOptions): Promise<StartServerResult> {
  // ...
  process.title = `next-server (v${process.env.__NEXT_VERSION})`

  let handlersPromise: Promise<void> | undefined = new Promise<void>(...)
  let requestHandler: WorkerRequestHandler = async (req, res) => {
    if (handlersPromise) {
      await handlersPromise   // 等待 handler 就绪后再处理请求
      return requestHandler(req, res)
    }
    throw new Error('Invariant request handler was not setup')
  }

  async function requestListener(req: IncomingMessage, res: ServerResponse) {
    try {
      if (handlersPromise) {
        await handlersPromise
        handlersPromise = undefined
      }
      await requestHandler(req, res)
    } catch (err) {
      res.statusCode = 500
      res.end('Internal Server Error')
      // ...
    } finally {
      // ... dev 模式下内存 monitor
    }
  }

  const server = http.createServer(requestListener)

  if (keepAliveTimeout) {
    server.keepAliveTimeout = keepAliveTimeout
  }

const cleanup = (signal: 'SIGINT' | 'SIGTERM') => {
  if (cleanupStarted) {
    return
  }
  cleanupStarted = true
  ;(async () => {
    // first, stop accepting new connections and finish pending requests
    await new Promise<void>((res) => {
      server.close((err) => {
        if (err) console.error(err)
        res()
      })
      if (isDev) {
        server.closeAllConnections()
        closeUpgraded?.()
      }
    })

    // now that no new requests can come in, clean up the rest
    await Promise.all([
      nextServer?.close().catch(console.error),
      cleanupListeners?.runAll().catch(console.error),
    ])

    await flushAllTraces()

    switch (signal) {
      case 'SIGINT':
        process.exit(130)
        break
      case 'SIGTERM':
        process.exit(143)
        break
    }
  })()
}

.next/standalone/
├─ server.js           # 入口
├─ package.json
├─ .next/server/...    # server bundle + manifest
├─ node_modules/       # nft 选中的依赖（不含 dev deps）
└─ public/             # public 资源

process.env.__NEXT_PRIVATE_STANDALONE_CONFIG = JSON.stringify({...})

const path = require('node:path')
const { startServer } = require('next/dist/server/lib/start-server')

const dir = path.join(__dirname)

process.chdir(__dirname)

// 兼容传统环境变量
const currentPort = parseInt(process.env.PORT, 10) || 3000
const hostname = process.env.HOSTNAME || '0.0.0.0'
const keepAliveTimeout = parseInt(process.env.KEEP_ALIVE_TIMEOUT, 10)

startServer({
  dir,
  isDev: false,
  config: { /* embedded next.config */ },
  hostname,
  port: currentPort,
  keepAliveTimeout: !Number.isNaN(keepAliveTimeout) ? keepAliveTimeout : undefined,
})

// 大致
const requestHandler = await createServer({
  hostname: 'localhost',
  port: 0,  // 不绑定端口
  conf: { ... },
})

module.exports = async function lambda(req, res) {
  return requestHandler(req, res)
}

// server.js
const { createServer } = require("http");
const { parse } = require("url");
const next = require("next");

const port = parseInt(process.env.PORT || "3000", 10);
const dev = process.env.NODE_ENV !== "production";
const app = next({ dev });
const handle = app.getRequestHandler();

app.prepare().then(() => {
  createServer((req, res) => {
    const parsedUrl = parse(req.url, true);
    handle(req, res, parsedUrl);
  }).listen(port);
});

const express = require("express");
const next = require("next");

const app = next({ dev: false });
const handle = app.getRequestHandler();

app.prepare().then(() => {
  const server = express();

  // 自定义路由
  server.get("/legacy/:id", (req, res) => {
    return handle(req, res, { pathname: "/blog/" + req.params.id, query: {} });
  });

  // 把其它请求转给 Next.js
  server.all("*", (req, res) => handle(req, res));

  server.listen(3000);
});

pm2 start npm --name 'next' -i max -- start

livenessProbe:
  httpGet:
    path: /api/health
    port: 3000
  initialDelaySeconds: 30
  periodSeconds: 10

readinessProbe:
  httpGet:
    path: /api/health
    port: 3000
  initialDelaySeconds: 5
  periodSeconds: 5

// app/api/health/route.ts
export const dynamic = "force-dynamic";

export async function GET() {
  return Response.json({ ok: true, ts: Date.now() });
}

# 第一阶段：依赖安装
FROM node:20-alpine AS deps
WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN corepack enable && pnpm install --frozen-lockfile

# 第二阶段：build
FROM node:20-alpine AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN corepack enable && pnpm build  # 生成 .next/standalone/

# 第三阶段：runtime
FROM node:20-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
ENV PORT=3000

# 复制 standalone 产物
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static
COPY --from=builder /app/public ./public

# 用非 root 用户
RUN addgroup -S app && adduser -S app -G app
USER app

EXPOSE 3000
CMD ["node", "server.js"]

cd learning/nextjs-40-lectures/fixtures/lecture-29
pnpm install

# 1. next start
pnpm build
PORT=3029 pnpm start &
curl http://localhost:3029/api/health

# 2. standalone
pnpm build:standalone
PORT=3029 node .next/standalone/server.js &

# 3. custom server
pnpm build
node custom-server.js

# 4. Docker
docker build -f Dockerfile.standalone -t lec29 .
docker run --rm -p 3029:3000 lec29