第 03 讲｜源码主入口与执行流（dev / build / start 三条线）

src/cli/
├── next-dev.ts          ← next dev
├── next-build.ts        ← next build
├── next-start.ts        ← next start
├── next-export.ts       ← next export
├── next-info.ts         ← next info
├── next-telemetry.ts    ← next telemetry
├── next-test.ts         ← next test (实验)
├── next-typegen.ts      ← next typegen
└── next-upgrade.ts      ← next upgrade

bin/next               (CLI 路由)
  └─ cli/next-dev.ts                 (父进程 - watcher / restart 逻辑)
       └─ fork()  →  子进程                ← 真正跑服务的进程
              └─ server/lib/start-server.ts
                   └─ server/lib/router-server.ts  (initialize)
                        ├─ setupFsCheck          (静态文件 / public 索引)
                        ├─ setupDevBundler       (webpack/turbopack/rspack 选择)
                        ├─ render-server.ts      (initialize - 起渲染 worker)
                        └─ requestListener       (HTTP server 真正绑定)

import { initialEnv } from '@next/env'
import { fork } from 'child_process'
import type { ChildProcess } from 'child_process'
import {
  getReservedPortExplanation,
  isPortIsReserved,
} from '../lib/helpers/get-reserved-port'
import { getCacheDirectory } from '../lib/helpers/get-cache-directory'
import { getGitBranch } from '../lib/helpers/git'
import os from 'os'
import fs from 'node:fs'
import { once } from 'node:events'
import { clearTimeout } from 'timers'
import { trace, initializeTraceState, exportTraceState } from '../trace'
import { traceId } from '../trace/shared'
import { Bundler, parseBundlerArgs } from '../lib/bundler'

export async function startServer(
  serverOptions: StartServerOptions
): Promise<StartServerResult> {
  const {
    dir,
    isDev,
    hostname,
    minimalMode,
    allowRetry,
    keepAliveTimeout,
    selfSignedCertificate,
    serverFastRefresh,
  } = serverOptions
  let { port } = serverOptions

  process.title = `next-server (v${process.env.__NEXT_VERSION})`
  let handlersReady = () => {}
  let handlersError = () => {}

  let handlersPromise: Promise<void> | undefined = new Promise<void>(
    (resolve, reject) => {
      handlersReady = resolve
      handlersError = reject
    }
  )
  let requestHandler: WorkerRequestHandler = async (
    req: IncomingMessage,
    res: ServerResponse
  ): Promise<void> => {
    // ... defer until handlers are ready
  }

export async function initialize(opts: {
  // ... options
}) {
  // ...
  let experimentalFeatures: ConfiguredExperimentalFeature[] = []
  const config = await loadConfig(
    opts.dev ? PHASE_DEVELOPMENT_SERVER : PHASE_PRODUCTION_SERVER,
    opts.dir,
    {
      silent: false,
      reportExperimentalFeatures(features) {
        experimentalFeatures = features.toSorted(({ key: a }, { key: b }) =>
          a.localeCompare(b)
        )
      },
    }
  )

export default class NextNodeServer extends BaseServer<
  Options,
  NodeNextRequest,
  NodeNextResponse
> {

export default abstract class Server<
  ServerOptions extends Options = Options,
  ServerRequest extends BaseNextRequest = BaseNextRequest,
  ServerResponse extends BaseNextResponse = BaseNextResponse,
> {

bin/next
  └─ cli/next-build.ts
       └─ build/index.ts             ← 主入口（4000+ 行的大块头）
            ├─ loadConfig + nextBuildSpan.trace(...)    (trace 全程)
            ├─ collectPages                              (扫 app/ + pages/)
            ├─ runWebpackCompiler / runTurbopackBuild    (3 套 compiler 并行/串行)
            ├─ writeManifests                            (12+ 个 manifest 落盘)
            ├─ generateStaticPages (worker)             (调用 worker.ts，并行预渲染)
            ├─ collectBuildTraces                        (生成 .nft.json)
            └─ printTreeView                             (终端表格)

#!/usr/bin/env node

import { saveCpuProfile } from '../server/lib/cpu-profile'
import { existsSync } from 'fs'
import { italic } from '../lib/picocolors'
import build from '../build'
import { warn } from '../build/output/log'
import { printAndExit } from '../server/lib/utils'

bin/next
  └─ cli/next-start.ts
       └─ server/lib/start-server.ts  (与 dev 共用！isDev=false)
            └─ router-server.ts initialize
                 └─ render-server.ts initialize
                      └─ NextNodeServer  (不是 DevServer)
                           └─ BaseServer  (公共逻辑)

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)
  }
  // ... inspector setup ...

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

HTTP socket
  ↓
http.createServer(requestListener)            ← start-server.ts:240
  ↓
requestHandler  (placeholder → 真实 handler)   ← start-server.ts:209
  ↓
router-server.ts  resolveRoutes               ← 检查 rewrite / redirect / public / API
  ↓
NextNodeServer.handleRequest                  ← next-server.ts (继承 base-server.ts)
  ↓  匹配到 app/products/[id]/page.tsx
RouteModule (app-page module)                 ← route-modules/app-page/module.ts
  ↓
app-render.tsx  renderToHTMLOrFlight          ← 真正的渲染入口
  ↓
React renderToReadableStream + RSC payload    ← compiled/react-server-dom-webpack/
  ↓
pipeReadable → http.ServerResponse           ← pipe-readable.ts
  ↓
浏览器收到 HTML + 内嵌 RSC payload

pnpm --filter=next build

cd test/e2e/lecture-01

node --inspect-brk=9229 ../../../packages/next/dist/bin/next.js dev --port 3001

console.log("[app-render] start at", new Date().toISOString());

父进程  next-dev (CLI)
  ├─ 子进程  next-server (主)
  │    ├─ worker  static-paths-worker （build 时）
  │    ├─ worker  render-server worker（部分配置下）
  │    └─ worker  use-cache-probe-worker（实验）
  └─ 父进程发现子进程 crash → fork 重启