一、项目配置（本地准备）
1. 启用 standalone 模式
修改 next.config.js（或 next.config.ts）：
/** @type {import('next').NextConfig} */
const nextConfig = {
// 核心：开启独立打包模式
output: "standalone",
// 可选：指定构建输出目录（默认 .next）
distDir: ".next",
// 可选：静态资源/图片配置（按需）
images: { unoptimized: false, // 如需 Next 图片优化保持 false
},
// 其他配置...
};
module.exports = nextConfig;
2. 确认 package.json 脚本
{
"scripts": {
"dev": "next dev",
"build": "next build",
"start": "next start" // 生产不用此命令，用 node server.js
}
}
3. 本地构建
# 安装依赖（首次/依赖更新时）
npm install # 或 yarn install / pnpm install
# 生产构建（关键）
npm run build
二、手动部署（VPS / 物理机）
1. 整理部署文件（必做）
standalone 默认不复制 public 和 .next/static，需手动拷贝：
# 拷贝 public 到 standalone
cp -r public .next/standalone/
# 拷贝 .next/static 到 standalone/.next
cp -r .next/static .next/standalone/.next/
2. 上传部署包到服务器
- 方式 A：SCP（命令行）
# 压缩（方便上传）
cd .next/standalone zip -r deploy.zip ./*
# 上传到服务器（替换为你的服务器信息）
scp deploy.zip root@xxx.xxx.xxx.xxx:/var/www/next-app/
- 方式 B：FTP 工具
根据自己的工具处理，目标是：
上传整个 .next/standalone 目录到服务器目标路径（如 /var/www/next-app）
3. 服务器环境准备
# 1. 安装 Node.js（必须 ≥18.17 或 ≥20，推荐 LTS）
curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
apt install -y nodejs
# 验证
node -v # v20.x.x
npm -v
# 2. （可选）安装 PM2（进程守护，生产必备）
npm install -g pm2
4. 启动服务
- 方式 1：直接启动（测试）
# 进入部署目录
cd /var/www/next-app
# 启动（指定端口/主机）
HOSTNAME=0.0.0.0 PORT=3000 node server.js
# HOSTNAME=0.0.0.0：允许外部访问 # PORT=3000：自定义端口
- 方式 2：PM2 守护（生产推荐）
# 启动并命名应用
HOSTNAME=0.0.0.0 PORT=3000 pm2 start server.js --name "next-app"
# 设置开机自启
pm2 startup pm2 save
# 常用命令
pm2 list # 查看状态
pm2 logs next-app # 查看日志
pm2 restart next-app # 重启
pm2 stop next-app # 停止
5. 验证访问
浏览器访问：http://服务器IP:3000看到页面即部署成功。
三、Docker 容器化部署（推荐）
1. 编写 Dockerfile（多阶段构建，最小镜像）
# syntax=docker/dockerfile:1
FROM node:20-alpine AS base
# 1. 安装依赖阶段
FROM base AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --frozen-lockfile
# 2. 构建阶段
FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
# 构建（自动启用 standalone）
RUN npm run build
# 3. 生产运行阶段（最小镜像）
FROM base AS runner
WORKDIR /app
# 安全：非 root 用户
RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs
# 环境变量
ENV NODE_ENV=production
ENV HOSTNAME=0.0.0.0
ENV PORT=3000
# 复制构建产物
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/public ./public
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
# 切换用户
USER nextjs
# 暴露端口
EXPOSE 3000
# 启动命令
CMD ["node", "server.js"]
2. 构建 & 运行 Docker 容器
# 1. 构建镜像
docker build -t next-app:latest .
# 2. 运行容器
docker run -d \
--name next-app \
--restart unless-stopped \
-p 3000:3000 \
next-app:latest
# 3. 验证
docker ps
curl http://localhost:3000
3. Docker Compose（可选，多服务管理）
docker-compose.yml：
version: "3.8"
services:
next-app:
build: .
container_name: next-app
restart: unless-stopped
ports:
- "3000:3000"
environment:
- NODE_ENV=production
运行：
docker-compose up -d --build
四、Nginx 反向代理（HTTPS / 域名 / 多应用）
1. 安装 Nginx
apt install -y nginx
2. 配置站点
vim /etc/nginx/sites-available/next-app
内容：
server {
listen 80;
server_name your-domain.com; # 你的域名
# 代理到 Next.js
location / {
proxy_pass http://127.0.0.1:3000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
# 缓存静态资源
location /_next/static {
proxy_pass http://127.0.0.1:3000;
expires 7d;
}
location /public {
expires 7d;
}
}
3. 启用配置 & 重启
# 启用
ln -s /etc/nginx/sites-available/next-app /etc/nginx/sites-enabled/
# 测试配置
nginx -t
# 重启
systemctl restart nginx
4.（可选）HTTPS（Encrypt）
apt install -y certbot python3-certbot-nginx
certbot --nginx -d your-domain.com
五、常见问题 & 注意事项
- 端口被占用
lsof -i :3000 # 查看占用
kill -9 PID # 关闭进程
- 静态资源 404
必须拷贝 public 和 .next/static 到 standalone 对应目录
-
环境变量
- 服务器启动前设置：
PORT=4000 HOSTNAME=0.0.0.0 node server.js - 或写入
.env.production（放入standalone目录）
- 服务器启动前设置：
-
不能用
next start
standalone 模式必须用 node server.js
- 镜像体积优化
用 node:alpine + 多阶段构建，镜像可控制在 100MB 内
