Next.js Standalone 模式详解：轻量部署与零停机更新

什么是 Standalone 模式

Next.js 的 Standalone 模式是一种生产部署优化方案，它会自动分析项目依赖，只打包运行时必需的文件，生成一个独立的、最小化的部署包。

为什么需要 Standalone

传统部署方式的痛点：

• 体积庞大：需要上传整个 node_modules（几百MB甚至GB级别）
• 服务器压力：需要在服务器上执行 npm install 和 npm run build
• 依赖风险：服务器网络问题可能导致依赖安装失败
• 无法 Cluster：npm run start 自己绑定端口，不支持 PM2 cluster 模式

Standalone 的优势

• 体积极小：30-100MB vs 传统的几百MB
• 无需服务器装依赖：所有必需文件已打包
• 支持 PM2 Cluster：可实现真正的零停机更新
• 部署速度快：上传文件少，启动迅速

如何配置

在 next.config.js 中添加：

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'standalone',
  // 其他配置...
}

module.exports = nextConfig

构建产物

执行 npm run build 后，会生成：

.next/
├── standalone/       # 独立部署包
│   ├── server.js     # 入口文件
│   ├── node_modules/ # 最小化依赖
│   └── ...          
└── static/           # 静态资源

部署步骤

1. 本地构建

npm run build

2. 上传到服务器

需要上传以下文件：

• .next/standalone/ - 主程序
• .next/static/ - 静态资源（复制到 .next/standalone/.next/static）
• public/ - 公共资源（复制到 .next/standalone/public）

3. 启动服务

cd .next/standalone
node server.js

配合 PM2 使用

ecosystem.config.js 配置示例：

module.exports = {
  apps: [
    {
      name: 'nextjs-app',
      script: '.next/standalone/server.js',
      instances: 2,              // 多实例
      exec_mode: 'cluster',      // cluster 模式
      env: {
        PORT: 3000,
        HOSTNAME: '0.0.0.0',
        NODE_ENV: 'production',
      },
    },
  ],
}

零停机更新：

# 拉取新代码并构建后
pm2 reload nextjs-app

PM2 会逐个重启实例，保证服务不中断。

部署脚本示例

#!/bin/bash

# 1. 本地构建
npm run build

# 2. 复制静态资源
cp -r .next/static .next/standalone/.next/
cp -r public .next/standalone/

# 3. 打包上传
tar -czf deploy.tar.gz .next/standalone
scp deploy.tar.gz user@server:/path/to/app/

# 4. 服务器端解压并重启
ssh user@server "cd /path/to/app && tar -xzf deploy.tar.gz && pm2 reload nextjs-app"

注意事项

• 环境变量：运行时环境变量需要在启动时设置，构建时的 NEXT_PUBLIC_* 变量会被内联
• 静态资源：必须手动复制 .next/static 和 public 目录
• 自定义 server：如果使用自定义 server.js，standalone 模式可能不适用
• 动态路由：ISR 等功能正常支持

总结

Standalone 模式是 Next.js 生产部署的最佳实践，特别适合需要快速迭代和高可用的项目。