这类项目最值得先看的不是功能列表而是能不能在普通服务器环境里稳定跑起来。Vue3 Nuxt4 做 SSR 网站部署到 Ubuntu 服务器上听起来是标准流程但实际落地时新手最容易卡在环境依赖、构建配置、进程管理和反向代理这几个环节。我一般会建议把第一次部署拆成三步先把本地开发环境跑通再在服务器上把基础环境配好最后处理构建、启动和对外访问。下面按实际落地顺序拆一遍重点不是命令本身而是每个环节为什么这么做以及卡住时先看哪里。1. 先确认你的项目在本地能正常构建和启动 SSR很多人一上来就在服务器上折腾结果发现是项目本身在本地 SSR 模式下就跑不起来。所以第一步必须在本地验证。1.1 检查项目结构和关键配置打开你的 Vue3 Nuxt4 项目先看几个关键文件是否存在且配置正确。package.json确认nuxt的版本是^4.0.0或更高。同时检查scripts里是否有build和preview命令。一个典型的 Nuxt4 项目脚本配置如下{ scripts: { dev: nuxt dev, build: nuxt build, preview: nuxt preview, generate: nuxt generate } }nuxt.config.ts(或.js)这是核心配置文件。重点检查ssr选项是否设置为true默认就是。另外如果你的应用需要监听特定端口或主机可以在这里配置devServer或nitroNuxt 底层服务引擎相关设置但部署时通常由环境变量或进程管理器控制。.env或.env.production检查生产环境变量特别是NODE_ENVproduction以及任何 API 基础地址。服务器环境和本地开发环境的不同往往首先体现在环境变量上。1.2 在本地执行构建和预览在项目根目录下按顺序执行以下命令模拟生产环境# 1. 安装依赖如果还没安装 npm install # 2. 执行生产构建 npm run build构建过程会生成.output目录里面包含了 SSR 应用运行所需的所有服务端和客户端代码。如果构建失败错误信息会直接输出在终端。常见构建失败原因包括Node.js 版本不兼容Nuxt4 通常需要 Node.js 18 或更高版本。用node -v检查。内存不足构建大型项目可能消耗大量内存如果本地内存不足可能会报JavaScript heap out of memory错误。依赖安装问题node_modules混乱或网络问题导致包未正确安装。可以尝试删除node_modules和package-lock.json后重新npm install。构建成功后运行预览命令npm run preview这个命令会启动一个生产模式的服务器通常基于.output目录监听在某个端口如http://localhost:3000。用浏览器打开这个地址确认页面能正常渲染且是服务端渲染查看网页源代码能看到渲染好的 HTML 内容而不是只有一个div idapp。如果本地预览都失败先别急着上服务器。问题很可能出在项目代码、配置或依赖上在本地解决成本更低。2. 准备 Ubuntu 服务器不只是安装 Node.js假设你有一台干净的 Ubuntu 22.04 LTS 服务器。我们的目标不仅是装上 Node.js还要建立一个稳定、可维护的运行环境。2.1 系统更新与基础工具通过 SSH 连接到你的服务器后首先更新系统包列表并升级现有包sudo apt update sudo apt upgrade -y然后安装一些后续可能需要的工具如用于解压、进程管理和网络调试的sudo apt install -y curl wget unzip htop net-tools2.2 安装 Node.js 和 npm使用 NodeSourceUbuntu 默认仓库的 Node.js 版本可能较旧。更推荐使用 NodeSource 仓库安装长期支持版LTS。以安装 Node.js 20.x 为例# 下载并执行 NodeSource 安装脚本 curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - # 安装 Node.js 和 npm sudo apt install -y nodejs安装后验证版本node -v # 应输出 v20.x.x npm -v # 应输出对应的 npm 版本2.3 安装并配置 PM2进程管理为什么不用npm run preview直接运行因为它在终端关闭后进程就会结束也不具备自动重启、日志管理、监控等功能。对于生产环境PM2是更稳妥的选择。全局安装 PM2sudo npm install -y pm2latest -gPM2 安装后可以将其设置为开机自启动这样服务器重启后应用能自动恢复# 生成启动脚本根据提示选择 pm2 startup # 执行上一条命令输出的指令例如sudo env PATH$PATH:/usr/bin /usr/lib/node_modules/pm2/bin/pm2 startup systemd -u your_username --hp /home/your_username # 保存当前进程列表以便开机恢复 pm2 save2.4 配置防火墙如果启用如果服务器启用了 UFWUncomplicated Firewall需要放行 SSH22、HTTP80和 HTTPS443端口sudo ufw allow ssh sudo ufw allow http sudo ufw allow https sudo ufw enable使用sudo ufw status检查规则。3. 上传代码与服务器端构建代码上传到服务器有多种方式这里介绍两种常见且直接的方法。3.1 方法一通过 Git 克隆推荐如果你的项目代码在 Git 仓库如 GitHub, GitLab, Gitee这是最方便的方式。在服务器上安装 Gitsudo apt install -y git克隆你的项目仓库cd /home/your_username git clone https://your-repository-url.git your-project-name cd your-project-name安装项目依赖并构建npm install --production # 仅安装生产依赖速度更快 npm run build注意服务器构建环境和本地必须一致。如果构建需要开发依赖如某些类型检查工具可能需要去掉--production标志或使用npm ci命令。3.2 方法二通过 SCP 或 SFTP 上传如果项目未使用 Git可以将本地构建好的.output目录和package.json等必要文件打包上传。在本地项目目录打包必要文件假设在项目根目录# 打包除 node_modules 外的源码和配置文件 tar -czf deploy.tar.gz --excludenode_modules --exclude.git .使用 SCP 上传到服务器scp deploy.tar.gz your_usernameyour_server_ip:/home/your_username/在服务器上解压并进入目录cd /home/your_username tar -xzf deploy.tar.gz -C your-project-name cd your-project-name npm install --production npm run build关键点无论哪种方式务必在服务器上重新执行npm run build。因为构建产物.output可能包含与操作系统或 Node.js 版本相关的原生模块本地如 Windows/macOS和服务器Linux环境不同直接拷贝本地构建产物可能导致运行时错误。4. 使用 PM2 启动和管理 Nuxt SSR 应用构建完成后.output目录里会有一个server目录里面包含了 Nitro 服务器入口。我们需要告诉 PM2 如何启动它。4.1 创建 PM2 生态系统配置文件在项目根目录创建一个ecosystem.config.js文件module.exports { apps: [ { name: your-nuxt-app, // 应用名称便于 PM2 管理 script: node, // 使用 node 命令执行 args: .output/server/index.mjs, // Nitro 服务器的入口文件 exec_mode: cluster, // 集群模式充分利用多核CPU instances: max, // 根据 CPU 核心数启动最大实例数 autorestart: true, // 应用崩溃时自动重启 watch: false, // 生产环境不建议开启监听文件变化 max_memory_restart: 1G, // 内存超过 1G 自动重启 env: { NODE_ENV: production, HOST: 0.0.0.0, // 监听所有网络接口 PORT: 3000, // 应用运行端口可自定义 }, }, ], };这个配置做了几件重要的事指定入口明确告诉 PM2 启动哪个文件。集群模式cluster模式可以启动多个应用实例由 PM2 做负载均衡提升并发处理能力。资源限制max_memory_restart可以防止内存泄漏导致服务器崩溃。环境变量在这里集中管理生产环境变量比在系统层面设置更清晰。4.2 启动应用并管理在项目根目录下使用 PM2 启动应用pm2 start ecosystem.config.js启动后可以使用以下命令进行管理pm2 status # 查看所有应用状态 pm2 logs your-nuxt-app # 查看实时日志 pm2 logs your-nuxt-app --err # 只看错误日志 pm2 restart your-nuxt-app # 重启应用 pm2 stop your-nuxt-app # 停止应用 pm2 delete your-nuxt-app # 从 PM2 列表中删除应用现在你的 Nuxt SSR 应用应该已经在服务器的 3000 端口运行了。可以在服务器内部用curl http://localhost:3000测试是否返回 HTML。5. 配置 Nginx 反向代理和域名访问直接通过 IP:3000 访问不专业也不安全无法使用 HTTPS。我们需要用 Nginx 作为反向代理将 80/443 端口的请求转发到本地的 3000 端口。5.1 安装 Nginxsudo apt install -y nginx5.2 配置站点删除默认配置为你的站点创建一个新的配置文件sudo rm /etc/nginx/sites-enabled/default sudo nano /etc/nginx/sites-available/your-domain.conf将以下配置粘贴进去将your_domain.com替换为你的域名your_server_ip替换为服务器公网 IPserver { listen 80; listen [::]:80; server_name your_domain.com www.your_domain.com; # 静态文件缓存可选提升性能 location /_nuxt/ { alias /home/your_username/your-project-name/.output/public/_nuxt/; expires 1y; add_header Cache-Control public, immutable; } location / { proxy_pass http://localhost:3000; # 指向 PM2 运行的端口 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; # 以下两行对 Nuxt SSR 很重要确保能获取到真实客户端 IP 和协议 proxy_set_header X-Forwarded-Host $host; proxy_set_header X-Forwarded-Port $server_port; } }关键配置解释proxy_pass将所有请求转发到本地 3000 端口的 Nuxt 应用。proxy_set_header这些头部信息确保了 Nuxt 应用能接收到原始客户端的 IP、协议等信息对于日志记录和某些中间件功能至关重要。location /_nuxt/这是 Nuxt 构建生成的客户端静态资源JS、CSS路径。通过 Nginx 直接提供这些文件效率远高于经过 Node.js 处理并可以设置长期缓存。5.3 启用配置并测试创建符号链接以启用站点配置并测试 Nginx 配置语法sudo ln -s /etc/nginx/sites-available/your-domain.conf /etc/nginx/sites-enabled/ sudo nginx -t # 测试配置应显示 “syntax is ok” 和 “test is successful”如果测试成功重启 Nginx 使配置生效sudo systemctl restart nginx5.4 配置域名解析和 SSLHTTPS域名解析在你的域名注册商处将域名A记录指向你的服务器公网 IP。安装 Certbot 获取 SSL 证书sudo apt install -y certbot python3-certbot-nginx sudo certbot --nginx -d your_domain.com -d www.your_domain.comCertbot 会自动修改你的 Nginx 配置添加 HTTPS 支持并设置自动续期。完成以上步骤后你应该可以通过https://your_domain.com访问到部署好的 Vue3 Nuxt4 SSR 网站了。6. 部署后的监控、维护与常见问题排查部署上线只是开始后续的稳定运行更需要关注。6.1 基础监控与日志PM2 监控pm2 monit命令可以打开一个仪表板实时查看 CPU、内存占用。日志管理PM2 日志默认在~/.pm2/logs/目录。定期检查或使用日志轮转工具如pm2-logrotate管理。服务器资源使用htop或glances监控整体服务器资源。6.2 自动化部署脚本简易版每次更新代码都手动操作太繁琐。可以在项目根目录创建一个简单的部署脚本deploy.sh#!/bin/bash echo “开始拉取最新代码...” git pull origin main echo “安装依赖...” npm install --production echo “构建项目...” npm run build echo “重启应用...” pm2 restart ecosystem.config.js echo “部署完成”给脚本执行权限chmod x deploy.sh。以后更新时只需在服务器项目目录下运行./deploy.sh即可。6.3 常见问题与排查顺序当网站无法访问或出现错误时按以下顺序排查检查应用进程状态pm2 status查看应用是否为online状态。如果是errored或stopped查看错误日志pm2 logs your-nuxt-app --err。检查端口监听sudo netstat -tlnp | grep :3000确认 3000 端口是否有进程在监听。如果没有PM2 可能启动失败。检查 Nginx 状态和错误日志sudo systemctl status nginx sudo tail -f /var/log/nginx/error.log确认 Nginx 运行正常并查看是否有访问或代理错误。检查防火墙和安全组服务器本地防火墙UFWsudo ufw status云服务商安全组规则确保 80 和 443 端口对公网开放。检查资源占用free -h # 查看内存 df -h # 查看磁盘空间内存或磁盘空间不足会导致应用崩溃或构建失败。检查项目本身回退到上一个稳定版本确认是否是本次代码更新引入的问题。在服务器上直接运行node .output/server/index.mjs看是否有更直接的错误输出。一个典型坑点环境变量。确保服务器上的环境变量如数据库连接字符串、API密钥与本地不同且正确。PM2 的ecosystem.config.js中的env区块是设置它们的好地方。我个人更建议先把单机部署这套流程跑稳包括代码更新、进程重启和日志查看。这套组合Nuxt4 PM2 Nginx对于中小型 SSR 应用已经足够稳定。如果后续流量增长再考虑容器化Docker、CI/CD 流水线或者更复杂的负载均衡方案。