Next.js SSR 项目生产部署全攻略

Next.js 是 React 生态中非常流行的前端框架，支持 SSR（Server-Side Rendering） 、API 路由 和 静态生成 。在开发阶段，Next.js 可以通过 next dev 运行，但在生产环境下，我们需要打包并部署 SSR 服务。本文将介绍完整的 Next.js SSR 生产部署流程，适用于 1Panel 或 VPS 服务器。

---

一、 本地准备

假设你的 Next.js 项目目录如下：

package.json
package-lock.json / yarn.lock
pages/
public/
components/
next.config.js
node_modules/

SSR 项目需要 Node.js 后端支持，因此生产环境必须有 Node.js 环境。

---

二、安装依赖

如果使用 npm：

npm install

如果使用 yarn：

yarn install

确保依赖完整，尤其是 next、react 和 react-dom。

---

三、 构建生产版本

Next.js 提供 next build 命令生成生产构建产物：

npm run build
# 或者
yarn build

• 会生成 .next/ 目录，包含 SSR 所需文件
• 构建完成后可以通过 next start 启动生产服务

---

四、 测试生产环境（可选）

npm start
# 或者
yarn start

• 默认端口 3000
• 确认 SSR 页面可以正常访问

---

五、准备上传文件

生产部署至少需要以下内容：

package.json
package-lock.json / yarn.lock
.next/        # SSR 构建产物
public/       # 静态资源
node_modules/ # 可上传，也可服务器安装

可以打包成 ZIP 上传：

zip -r next-prod.zip package.json package-lock.json .next public .env

---

六、上传到服务器 / 1Panel

• 1Panel：直接上传 ZIP 或 Git 克隆项目
• VPS / 云服务器 ：通过 scp 上传

scp next-prod.zip user@yourserver:/path/to/app
ssh user@yourserver
unzip next-prod.zip -d next-app
cd next-app

---

七、安装生产依赖（如果未上传 node_modules）

npm install --production
# 或者
yarn install --production

SSR 生产环境只需要安装 dependencies，不需要 devDependencies

---

八、配置环境变量

Next.js SSR 项目常用环境变量：

NODE_ENV=production
PORT=3000
NEXT_PUBLIC_API_URL=https://api.example.com

可以在服务器环境中设置，也可以使用 .env.production 文件

---

九、启动生产 SSR 服务

方式一：直接 Node.js

npm start
# 或者
yarn start

• 访问 http://你的域名或公网IP:3000
• 页面由服务器渲染并返回 HTML（SSR）

方式二：PM2 守护

npm install -g pm2
pm2 start npm --name "next-app" -- start
pm2 save
pm2 startup

• 保证服务器重启后自动启动
• 提供日志管理和进程监控

方式三：Docker 部署（可选）

Dockerfile 示例：

FROM node:20-alpine

WORKDIR /app
COPY package*.json ./
RUN npm install --production
COPY . .
RUN npm run build
CMD ["npm", "start"]
EXPOSE 3000

构建 & 运行：

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

---

十、 可选：Nginx 反向代理 + HTTPS

server {
    listen 80;
    server_name yourdomain.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

• 配合 Let's Encrypt 可免费启用 HTTPS
• 提高安全性与稳定性

---

十一、完整部署流程总结

1. 本地 npm install / yarn install
2. npm run build / yarn build 生成 .next/
3. 上传 .next/ + public/ + package.json + node_modules（可选）
4. 服务器安装依赖（如需要）
5. 配置环境变量
6. 使用 npm start / PM2 / Docker 启动
7. 可选 Nginx 反向代理 + HTTPS
8. 访问页面，确认 SSR 正常渲染

---

十二、 小技巧

• 端口管理 ：1Panel 默认分配公网端口，确保 PORT 与之匹配
• 守护进程：PM2 或 Docker 保证 SSR 服务稳定运行
• 环境变量：生产环境变量一定要配置正确，否则 SSR 可能报错
• 安全与性能：建议 Nginx 反向代理 + HTTPS

---

通过以上步骤，你可以快速将 Next.js SSR 项目 打包、上传，并在 1Panel 或 VPS 上运行生产环境，实现服务端渲染。