Next.js 安装部署教程

Next.js 16 要求 Node.js 20.9+，默认打包器已切换为 Turbopack，默认集成 React Compiler，并原生支持 AI Agent 通过 MCP 协议对接 DevTools。

一、环境准备

node -v   # 需要 >= 20.9
npm -v

可选工具：

# 容器化部署需要
docker --version

# Kubernetes 部署需要
kubectl version

macOS 推荐用 nvm 管理 Node 版本：

nvm install 20
nvm use 20

二、项目初始化

方式 A：新建项目

npx create-next-app@latest my-app
cd my-app

交互式选项中建议：

• TypeScript：Yes
• ESLint：Yes
• Tailwind CSS：按需开启
• App Router：Yes
• Turbopack：Yes（默认）

方式 B：克隆开源项目

git clone https://github.com/vercel/next.js.git
cd next.js
npm install

三、本地开发

npm run dev

浏览器访问 http://localhost:3000。

package.json 核心脚本：

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "eslint"
  }
}

本地开发不要用 Docker 跑 next dev，macOS / Windows 下文件系统性能较差。

四、生产构建

npm run build
npm start

npm run build 生成 .next 目录；npm start 启动内置 Node.js 服务器，完整支持 SSR、ISR、API Routes、Server Components。

五、部署方式

1. Vercel（最快上手）

npm install -g vercel
vercel login
vercel --prod

或直接在 Vercel Dashboard 导入 GitHub 仓库，push 即自动部署。

2. Node.js 自托管

npm run build
pm2 start npm --name next-app -- start
pm2 save

前面挂 Nginx 反向代理 + HTTPS 即可上线。

3. Docker（standalone 模式）

next.config.ts 中开启 standalone：

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  output: "standalone",
};

export default nextConfig;

Dockerfile（多阶段构建）：

FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:20-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static
COPY --from=builder /app/public ./public
EXPOSE 3000
CMD ["node", "server.js"]

构建运行：

docker build -t next-app .
docker run -p 3000:3000 next-app

standalone 模式下，运行时必须用 node server.js，不能用 npm start / next start。

4. Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: next-app
spec:
  replicas: 2
  selector:
    matchLabels:
      app: next-app
  template:
    metadata:
      labels:
        app: next-app
    spec:
      containers:
      - name: next-app
        image: next-app:latest
        ports:
        - containerPort: 3000
        env:
        - name: NODE_ENV
          value: "production"
---
apiVersion: v1
kind: Service
metadata:
  name: next-app
spec:
  selector:
    app: next-app
  ports:
  - port: 80
    targetPort: 3000
  type: ClusterIP

外部访问再加 Ingress 或 Gateway API。多副本 ISR 场景需共享存储卷。

5. 静态导出（仅静态站点）

const nextConfig: NextConfig = { output: "export", };

npm run build

产物在 out/ 目录，可托管到 Nginx / S3 / GitHub Pages。不支持 SSR、ISR、API Routes、Server Actions。

六、常见问题

• 构建失败：检查 Node 版本 ≥ 20.9、依赖是否完整、环境变量是否缺失。
• standalone 启动失败：确认已复制 .next/static 和 public，且用 node server.js 启动。
• 环境变量不生效：前端变量必须 NEXT_PUBLIC_ 前缀，服务端变量在部署平台注入。
• K8s 多副本 ISR 异常：需配置共享卷让副本共享 ISR 缓存。
• UUID 兼容：IP 访问（非 HTTPS/localhost）时 crypto.randomUUID 可能受限，建议用第三方 uuid 库。