Next.js部署全攻略：ECS+pm2+Nginx实现SSR项目稳定上线

Next.js部署这件事，说难不难，说简单也真不简单。很多用React做过纯前端项目的同学，第一次把Next.js项目往服务器上放的时候，脑子里还停留在“npm run build，然后把静态文件丢到Nginx目录里”的思维。但对服务端渲染框架来说，这套流程是走不通的——Next.js的服务端渲染依赖一个常驻的Node进程，build之后的产物并不是纯静态HTML，还有大量需要在服务端运行的代码和逻辑。这篇文章就围绕“Next.js项目部署到阿里云服务器、用pm2做进程守护”这条完整链路，讲讲我从环境准备、代码上传、生产构建、进程守护到Nginx反向代理和HTTPS配置的实操过程，以及中间踩过的坑和排查思路。适合正在用Next.js做个人项目或小团队项目、第一次尝试在云服务器上正式部署的开发者参考。

1. 部署方案选型：为什么是ECS + pm2 + Nginx

1.1 SSR项目部署的核心差异

先说一下最本质的问题：为什么Next.js项目不能像传统React项目那样“打包后丢静态服务器”？

传统React SPA项目，构建完就是一个index.html加一堆JS、CSS文件，所有页面渲染都在浏览器端完成。你只需要把产物扔到Nginx、OSS或者任何静态托管里，浏览器访问时自己去加载JS，再由JS渲染页面。

但Next.js是React服务端渲染框架，它在服务器端完成首次渲染，把渲染好的HTML直接返回给浏览器。这意味着：

• 服务器上必须有一个能运行JavaScript的Node环境；
• 必须有至少一个常驻的Node服务进程来处理请求，不能是“跑完命令就退出”的一次性任务；
• .next目录里不仅包含静态资源，还包含服务端代码、路由映射、构建缓存等运行时依赖；
• 如果你的项目用了API Routes、Server Actions、ISR增量静态再生之类的特性，这些统统依赖Node运行时。

当然，Next.js也支持output: 'export'做纯静态导出，但那样等于放弃了服务端渲染的全部能力，动态路由、按需更新、API接口全都用不了。对于真正依赖SSR能力的项目来说，这不是一个可选的方案。

所以，部署的核心思路就变了：我们需要在ECS上跑一个Node服务，然后保证这个服务稳定、可靠、不会因为SSH窗口关闭或者进程异常退出就挂掉，最后还要把域名流量通过Nginx转发到这个Node服务上。这是整篇文章要实现的目标。

1.2 方案选型依据与服务器配置建议

先说我最终采用的架构栈，以及为什么选这套而不是别的：

• 阿里云ECS（云服务器）：提供长期在线的Linux运行环境，这是跑Node服务的基础。想临时验证用轻量应用服务器也行，网络配置和操作方式都差不多。
• pm2（进程守护工具）：保持Node进程常驻、崩溃自动重启、开机自启、统一日志。很多人会问“直接node server.js不行吗”，答案是不行——SSH一断开，命令行的子进程通常也会收到挂断信号退出，pm2把进程变成独立的守护进程，跟你的SSH会话解耦。
• Nginx（反向代理）：对外统一接收80/443端口流量，同时提供SSL证书卸载、Gzip压缩、静态资源缓存。Next.js服务本身监听一个内部端口（比如3000），由Nginx转发过去。这样不仅更安全灵活，以后在同一个服务器上部署多个应用时，也只靠Nginx做路由分发就行。

关于服务器配置，我给一个踩过坑之后的参考：

• 最低：2核2G内存、40G硬盘。Next.js的next build在2G内存下勉强能跑，但如果你项目依赖多、图片静态资源多，构建时很容易触发OOM后被系统kill掉；
• 推荐：2核4G，构建过程会舒服很多，开发调试也更从容；
• 系统镜像：Ubuntu 22.04 / Debian 11这类主流发行版即可，包管理器好用，教程也多；
• Node版本：Next.js 14要求Node 18.17以上，建议直接装Node 20 LTS，不要用太老的版本，否则构建时会直接报错。

这套方案最大的好处是把每个环节拆开，出问题时可以快速定位是Node进程的问题、Nginx的问题还是网络/安全组的问题，排查链路非常清晰。

2. 服务器环境准备与代码上传

2.1 服务器初始化与Node环境安装

新买的ECS，第一步永远是更新系统包、安装基础工具。用SSH连上服务器之后，我习惯先做这几件事：

apt update && apt upgrade -y apt install -y git curl wget build-essential

然后安装Node环境。这里我强烈建议不要直接去官网下载二进制压缩包，也不要直接用apt install nodejs——前者后续升级麻烦，后者版本通常太旧。我推荐用nvm安装和管理Node版本，虽然服务器上不太可能频繁切换版本，但nvm能让你轻松装到指定版本，切版本也只是一条命令的事：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 安装完成后重开SSH或执行: source ~/.bashrc nvm install 20 nvm alias default 20 node -v npm -v

注意：很多人卡在nvm装完后node命令找不到，这是因为nvm把初始化脚本写进了~/.bashrc，当前SSH会话不会自动加载。执行source ~/.bashrc或者干脆断开重新连接一次，就能解决。

接着可以顺手把npm镜像源切换成一个国内访问更快的源，能显著提升后续依赖安装的速度：

npm config set registry https://registry.npmmirror.com

2.2 项目代码上传的几种方式

项目代码传到服务器，常见路径有两条：

路径一：如果你有Git仓库，在服务器上直接clone是最省心的。

mkdir -p /home/app && cd /home/app git clone git@your-git-host:your-org/next-app.git cd next-app

服务器上需要配好SSH Key并让代码托管平台信任它。生成方式就是老生常谈的ssh-keygen -t rsa -b 4096，然后将~/.ssh/id_rsa.pub内容添加到托管平台的SSH Keys列表里。

路径二：如果你的代码没有放在Git仓库，或者你不想在服务器上保留源码仓库，可以直接从本地打包上传：

# 本地执行 tar --exclude='node_modules' --exclude='.git' --exclude='.next' -czf app.tar.gz . scp app.tar.gz root@你的服务器IP:/home/app/ # 服务器执行 mkdir -p /home/app/next-app tar -xzf app.tar.gz -C /home/app/next-app

这里给个提醒：排除node_modules和.next是必须的，这两个目录动辄几百MB甚至上GB，打包进去完全是浪费带宽和时间。依赖统一在服务器上用npm ci安装。

无论用哪种方式，上传之后都建议检查一下关键文件是否完整，比如package.json、package-lock.json/yarn.lock、.env.production这些文件一个都不能少。

3. Next.js生产构建与本地验证

3.1 安装依赖与生产构建

代码到位后，先安装依赖。这里我比较坚持用npm ci而不是npm install：

cd /home/app/next-app npm ci

npm ci会严格按照package-lock.json里的版本安装，丢弃掉package.json中的模糊版本范围，保证服务器和本地开发环境的依赖版本完全一致。CI构建、生产部署这种场景用它是最稳的。

接着就是正式构建：

NODE_ENV=production npm run build

如果你的项目里配置了next build以外的构建逻辑，同样会一并执行。构建成功时，命令末尾会输出路由表、各页面类型（静态/服务端/客户端渲染）、首次加载JS体积等汇总信息。看到那个表，说明前面的基础环境没问题。

构建过程中最容易踩的坑是内存不足。我自己的项目在2G内存的机器上构建，中间直接被杀进程，终端上只留下一句Killed。这时候有两个选择：给服务器加内存，或者在不加内存的情况下添加swap交换空间临时顶一顶。对2G内存的机器，我是这么加swap的：

fallocate -l 2G /swapfile chmod 600 /swapfile mkswap /swapfile swapon /swapfile echo '/swapfile swap swap defaults 0 0' >> /etc/fstab

加完swap再重新构建，基本就能顺利跑完。我自己后续测试过：一个中等复杂度的Next.js项目（依赖约500个包），在2G内存+2G swap的机器上构建能跑完，但会比较吃力。长期运行还是建议4G内存。

还有一种思路是给Node进程单独设置内存上限：

NODE_OPTIONS="--max-old-space-size=2048" npm run build

这个参数的意思是让V8老生代内存上限设为2048MB。要注意的是：设置得太接近物理内存上限，反而容易在内存紧张的机器上提前触发OOM，要根据实际情况来。

3.2 本地验证与standalone模式

构建完成不等于部署完成。在接入pm2之前，先手动把生产服务跑起来验证一下：

npm run start -- -p 3000

然后另开一个SSH窗口，在服务器本地确认服务有没有正常响应：

curl -I http://127.0.0.1:3000

如果返回HTTP/1.1 200 OK以及x-powered-by: Next.js等相关响应头，说明生产服务在服务器本机已经可以访问了。接着可以再验证一下首页HTML是否真的是服务端渲染的：

curl http://127.0.0.1:3000 | grep -o '<title>[^<]*</title>'

能看到页面标题真实出现在HTML源码里，而不是空HTML配合一堆JS，就说明SSR渲染链路是通的。

这里还要聊一下standalone模式。Next.js提供了output: 'standalone'配置，开启后构建产物会包含一个最小化的server文件，复制时需要手动带上.next/static和public目录。它的核心价值是让服务摆脱对node_modules和生产依赖的依赖，适合做Docker镜像或快速迁移。但如果你就是在ECS上直接跑pm2，用默认的next start方式更简单直接，不需要额外处理静态资源复制的问题，也不容易出错。所以我的建议是：没有容器化需求的情况下，优先用标准的next start，如果你想未来迁移到Docker，再考虑开standalone。

4. pm2进程守护配置与实操

4.1 为什么选择pm2以及基础启动方式

验证项目本身没问题之后，接着就轮到pm2登场了。pm2本质上是一个Node进程管理器，它做的事情非常契合服务端部署的场景：保持进程常驻、崩溃自动重启、统一收集日志、监控内存CPU占用、配置开机自启。

安装pm2：

npm i -g pm2

启动Next.js生产服务的最简单方式：

pm2 start npm --name "next-app" -- run start -- -p 3000

启动之后务必看一眼状态：

pm2 status

正常会看到一个online状态的进程，内存占用字段会显示实际数值。只要进程状态是online，你就算关掉SSH窗口，服务也会继续运行。但只做到这一步还不够，生产环境的守护要更细致。

4.2 ecosystem配置文件与开机自启

我建议不要每次用命令手动拼参数，而是写一个ecosystem.config.js放在项目根目录。这个文件的配置项一目了然，以后重启、改参数、迁移服务器，都直接复制一份改改路径就行：

module.exports = { apps: [ { name: 'next-app', cwd: '/home/app/next-app', script: 'npm', args: 'run start -- -p 3000', interpreter: 'none', env: { NODE_ENV: 'production', PORT: 3000 }, max_memory_restart: '600M', instances: 1, autorestart: true, exec_mode: 'fork', time: true, out_file: '/home/app/logs/next-out.log', error_file: '/home/app/logs/next-error.log', merge_logs: true } ] };

说明几个关键配置项：

• cwd：pm2启动工作目录。很多人在这一步踩坑，因为如果工作目录不对，启动后立刻找不到项目文件，进程会进入“反复重启”循环；
• interpreter: 'none'：因为script指向的是npm，要避免pm2把npm当成Node脚本去解析，这个配置告诉pm2直接用系统方式执行；
• max_memory_restart: '600M'：当进程内存占用超过600M时自动重启。这个值是根据项目实际情况调的，不要设置得太低，否则频繁重启反而影响稳定性；
• autorestart: true：进程崩溃时自动拉起，这是守护的核心；
• time: true：日志输出附带时间戳，排查问题时特别有用。

配置好之后，启动命令就变成了：

pm2 start ecosystem.config.js pm2 save

pm2 save会把当前进程列表保存下来，这一步是开机自启的前置条件。接着还需要执行：

pm2 startup

执行这个命令后，pm2会打印一条需要以root身份运行的命令（通常是env PATH=$PATH:/usr/bin pm2 startup systemd -u root --hp /root之类的），复制下来执行一遍。这样服务器重启后，pm2会自动拉起你保存过的所有进程，不需要手动再去SSH里执行启动命令。

注意：pm2 startup生成的命令必须执行，只执行pm2 save不够。有些教程只说保存快照，不说启动项，结果服务器一重启服务全没了，人都懵了。这两条是配套动作，缺一不可。

查看日志和监控的命令也列一下，排查问题时会频繁用到：

pm2 logs next-app # 实时日志，加 --lines 100 看最近100行 pm2 monit # 终端实时监控面板 pm2 restart next-app # 手动重启 pm2 reload next-app # 优雅重载，不中断请求更推荐

pm2还有一个cluster模式，可以按CPU核数开启多个实例做负载均衡。但对Next.js这种SSR应用来说，是否用cluster要看你的状态存储方式：如果你的应用用到了内存态数据、内存态Session或WebSocket长连接，cluster模式下多实例之间天然不共享，需要额外引入Redis之类的外部存储。小项目一开始老老实实instances: 1+fork模式就好，别为了性能盲目多开进程，反而给自己造出更多问题。

5. Nginx反向代理与HTTPS配置

5.1 用Nginx统一接管对外流量

虽然Next.js自己监听3000端口后，已经可以通过http://IP:3000访问了，但生产环境不会这么裸奔。端口一多不好记、不美观，也不方便统一管理证书和缓存。更关键的是，Next.js服务直接暴露在外网，没有中间层做过滤和转发，一旦Node进程出问题，用户看到的错误就是底层不可用状态，处理起来也更棘手。

所以我在ECS上装好Nginx，让它监听80/443端口，再转发到Next.js进程的3000端口：

apt install -y nginx systemctl start nginx systemctl enable nginx

然后给Next.js建一个站点配置文件/etc/nginx/conf.d/next-app.conf：

upstream nextjs_upstream { server 127.0.0.1:3000; keepalive 64; } server { listen 80; server_name your-domain.com; gzip on; gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript; # 静态资源直接由Nginx处理，不转发给Node location /_next/static/ { alias /home/app/next-app/.next/static/; expires 365d; access_log off; } location / { proxy_pass http://nextjs_upstream; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection 'upgrade'; 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; proxy_cache_bypass $http_upgrade; } }

这里有几个细节值得展开说：

• _next/static的alias配置是指向构建产物目录。Next.js的静态资源默认会带上很长的哈希文件名，天然适合缓存，所以我给它设置了365天的过期时间。访问旧页面时即便HTML发生了更新，静态文件名变了，浏览器也能正确请求到新文件，不会因为缓存导致样式错乱；
• proxy_set_header Host $host非常关键。如果没有这一行，Next.js收到的Host头是127.0.0.1:3000，某些依赖域名判断的逻辑（比如完全URL生成、SSR请求转发）就会出错；
• Connection 'upgrade'和Upgrade $http_upgrade看起来像是为WebSocket准备的，但Next.js的HMR和部分内部机制也可能依赖长连接，加上之后更保险；
• X-Forwarded-Proto $scheme让Next.js能正确识别访客是通过http还是https访问，避免在HTTPS场景下生成错误的协议链接。

写完配置文件后，先检查语法，再重载Nginx让配置生效：

nginx -t systemctl reload nginx

环境变量方面，Next.js默认从process.env读取PORT，但要注意Nginx转发过去的请求并不会自动带上这个变量。如果你在代码里用的端口跟Nginxproxy_pass不一致，链路就会断掉。我一般都是在ecosystem.config.js里通过env.PORT固定端口，Nginx配置里也写死同一个端口，避免两处各配各的。

5.2 HTTPS证书配置

现在的新项目，已经没必要纠结“要不要上HTTPS”了。浏览器和各种API都会对HTTPS有更严格的要求，Next.js在SSR阶段如果调用了一些外部接口，也可能会因为混合内容或证书问题被拦。

证书方案我推荐用阿里云上的免费证书，或者用Let's Encrypt的免费证书，都够用。以阿里云上的证书为例，拿到证书文件后放到服务器某个固定目录，比如/home/app/ssl/下，然后在Nginx同一个server块下方追加443端口的监听：

server { listen 443 ssl http2; server_name your-domain.com; ssl_certificate /home/app/ssl/server.crt; ssl_certificate_key /home/app/ssl/server.key; ssl_protocols TLSv1.2 TLSv1.3; # 其他location配置和80端口一致 }

同时把80端口加一个301跳转，让所有http请求自动升级为https：

server { listen 80; server_name your-domain.com; return 301 https://$host$request_uri; }

配置完成后同样执行nginx -t && systemctl reload nginx。打开浏览器访问https://your-domain.com，能看到主页正常渲染、地址栏出现锁形图标，就说明链路通了。

多说一句：国内服务器上解析到域名后，如果访问遇到“无法访问此网站”之类的问题，先确认域名是否已经按云厂商的要求完成了接入流程。这是国内云服务器部署的常规合规要求，不是Nginx配置能解决的范畴，提前了解好能少走很多弯路。

6. 常见问题与排查实录

部署过程中踩过的坑，我整理成一张速查表，这些几乎都是我实际遇到或帮别人排查过的问题：

除此之外，有几个排查工具和技巧值得分享：

一是curl分级排查法。外部访问不通时，先看服务器本机curl http://127.0.0.1:3000，通说明Node层正常；再看curl http://127.0.0.1/带Host头，通说明Nginx配置正常；最后从外部访问域名，层层逐步缩小范围。这套思路比瞎猜要高效得多。

二是日志永远是最诚实的信息来源。pm2日志会告诉你Node最近发生了什么，Nginx的error log会告诉你转发过程中哪里断了，这两个日志配合着看，绝大多数问题都能定位。不要一上来就重启进程，先把日志翻完。

三是在修改Nginx配置后，养成写nginx -t的习惯。有些配置错误不会在reload时立刻报错，语法检查能提前拦截一大半低级问题。

写在最后

我个人在实际部署中的体会是：Next.js服务端渲染项目的部署，本质上就是把“前端开发思维”切换成“服务运维思维”。你需要接受一个Node进程常驻在服务器上这件事，然后用pm2把它管好，用Nginx把它挡住，让它在生产环境里稳定地跑下去。

最后再分享一个小技巧：上线初期，我建议在pm2日志保持开启的前提下，先跑一周例行观察。每天登录服务器看一遍pm2 status和pm2 monit，确认内存没有肉眼可见的持续增长、进程没有频繁重启。等一周数据都平稳了，再彻底把精力放到业务迭代上。一个项目稳定部署之后，你会发现后续每次更新只需要git pull、npm ci、npm run build、pm2 reload next-app这四步，整个流程跑顺了就非常轻量。