如果你是一名前端开发者正在使用 Vue3 和 Nuxt4 构建一个现代化的 Web 应用并且希望它拥有更好的 SEO 和首屏加载速度那么服务器端渲染SSR几乎是必经之路。然而从本地开发到将 SSR 应用成功部署到一台 Ubuntu 服务器上这中间的路途往往布满荆棘Node.js 环境、PM2 进程守护、Nginx 反向代理、SSL 证书、防火墙配置……任何一个环节出错你的应用都可能无法访问。网上教程很多但大多只讲单一环节或者版本老旧。当你把 Vue3、Nuxt4、Ubuntu 这几个关键词组合在一起时会发现缺少一份能串联所有步骤、讲清原理、并指出常见深坑的完整指南。这篇文章的目的就是填补这个空白。它不是简单的命令罗列而是基于真实部署经验为你梳理出一条从代码到线上可访问的清晰路径并解释每一步背后的“为什么”。我们将聚焦于一个最经典的部署架构在 Ubuntu 服务器上使用 PM2 管理 Nuxt4 SSR 应用进程并通过 Nginx 作为反向代理和静态资源服务器。你会看到部署 SSR 应用的核心不仅是运行npm run build和npm start更在于如何构建一个稳定、可维护的生产环境。1. 为什么 Nuxt4 SSR 部署比传统 SPA 更复杂在开始动手之前我们必须先理解挑战所在。如果你只部署过 Vue CLI 创建的纯客户端 SPA单页应用那么过程通常很简单运行npm run build将生成的dist文件夹扔到 Nginx 或对象存储配置一下路由回退就完成了。因为 SPA 最终只是一堆静态的 HTML、CSS 和 JS 文件。但 Nuxt4 在启用 SSR 模式后情况发生了根本变化它需要一个 Node.js 运行时环境SSR 意味着首次页面渲染是在服务器端完成的。这需要你的服务器上有一个持续运行的 Node.js 进程来执行 Vue 组件代码、生成 HTML。这个进程就是你的应用服务器。它涉及构建与运行两个阶段构建阶段在服务器或 CI/CD 环境中你需要运行npm run build或nuxi build。这个过程会编译你的 Vue 代码并生成两部分产物客户端 Bundle和 SPA 类似的静态资源_nuxt/目录。服务端 Bundle一个用于 Node.js 环境运行的服务器入口文件通常位于.output目录。运行阶段你需要启动这个服务端 Bundle它会在指定端口如 3000启动一个 HTTP 服务器监听请求动态渲染页面。进程管理是必须的你不能仅仅通过node .output/server/index.mjs来启动服务因为一旦终端关闭进程就结束了。你需要一个像PM2这样的进程守护管理器来保证应用持续运行并在崩溃时自动重启。需要反向代理我们通常不会让用户直接访问 Node.js 服务的端口如http://你的服务器IP:3000。更专业的做法是使用Nginx监听 80/443 端口HTTP/HTTPS然后将请求转发给内部运行的 Node.js 应用。这样做的好处包括负载均衡、静态文件高效服务、SSL 卸载、安全过滤等。所以部署 Nuxt4 SSR 应用本质上是在服务器上搭建一个由“Node.js 应用进程 反向代理网关”构成的微型后端服务集群。理解了这一点后续的所有步骤就都有了清晰的逻辑。2. 环境准备你的服务器与工具清单在开始部署前请确保你拥有并配置好以下资源。这是整个流程的基石。2.1 服务器要求操作系统Ubuntu 20.04 LTS 或 22.04 LTS长期支持版。本文以 Ubuntu 22.04 为例其他版本大同小异。最低配置对于初期项目1核 CPU、2GB 内存的云服务器实例如阿里云、腾讯云、AWS 的轻量应用服务器足够运行。内存尤为重要因为 Node.js 进程和构建过程都比较消耗内存。网络确保服务器的安全组或防火墙规则开放了22端口SSH、80端口HTTP和443端口HTTPS。后续我们会在服务器内部使用 3000 端口这个端口不需要对公网开放。2.2 本地与服务器工具本地机器你需要一个终端工具如 macOS 的 Terminal、Windows 的 PowerShell 或 Git Bash通过 SSH 连接服务器。服务器环境我们将通过 SSH 在服务器上安装一系列工具Node.js npm运行 Nuxt 应用的核心。PM2进程管理。NginxWeb 服务器和反向代理。Git从代码仓库拉取项目可选但推荐。2.3 项目前提你有一个基于 Vue3 和 Nuxt4 开发完成的项目。项目根目录下的nuxt.config.ts中配置了ssr: true这是 Nuxt4 的默认配置除非你显式关闭。你有一个可以访问的代码仓库如 GitHub、GitLab或者已经将项目代码打包准备好。3. 第一步连接服务器与基础环境配置让我们从登录服务器开始搭建起最基本的环境。3.1 SSH 连接服务器使用你的终端通过 SSH 连接到 Ubuntu 服务器。你需要服务器的公网 IP 地址和登录密码或密钥。ssh usernameyour_server_ip # 例如ssh root123.123.123.123连接成功后你将进入服务器的命令行界面。3.2 更新系统与安装基础工具首先更新系统的软件包列表并升级现有软件这是一个好习惯。sudo apt update sudo apt upgrade -y安装一些后续可能需要的工具如curl和vim。sudo apt install curl vim -y3.3 安装 Node.js 与 npmUbuntu 默认的软件源中的 Node.js 版本可能较旧。我们推荐使用 NodeSource 提供的仓库来安装长期支持版LTS。安装 NodeSource 仓库脚本这里安装 Node.js 20.x LTS你可以根据需要选择其他版本curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -安装 Node.js 和 npmsudo apt install -y nodejs验证安装node --version # 应输出 v20.x.x npm --version # 应输出对应的 npm 版本4. 第二步部署你的 Nuxt4 项目代码有几种方式可以将代码放到服务器上我们介绍两种最常用的。4.1 方法一通过 Git 克隆推荐如果你的代码在 Git 仓库中这是最清晰、便于后续更新的方式。在服务器上安装 Gitsudo apt install git -y选择一个目录存放你的项目例如/var/www/cd /var sudo mkdir www cd www克隆你的项目仓库这里以公开仓库为例私有仓库需要配置 SSH 密钥或使用 HTTPS 密码sudo git clone https://github.com/your-username/your-nuxt-project.git cd your-nuxt-project安装项目依赖npm install # 或使用 yarn/pnpm注意确保服务器上的 Node.js 版本符合项目package.json中engines字段的要求。4.2 方法二通过压缩包上传如果你不想在服务器上配置 Git或者只是做一次性的部署。在本地将你的项目目录排除node_modules和.env等敏感文件打包# 在本地项目根目录执行 tar -czf nuxt-project.tar.gz --excludenode_modules --exclude.git --exclude.env .使用scp命令将压缩包上传到服务器scp nuxt-project.tar.gz usernameyour_server_ip:/tmp/回到服务器 SSH 会话解压到目标目录sudo mkdir -p /var/www/nuxt-project sudo tar -xzf /tmp/nuxt-project.tar.gz -C /var/www/nuxt-project cd /var/www/nuxt-project安装项目依赖npm install5. 第三步构建 Nuxt4 SSR 应用代码就位后我们需要在服务器上进行构建生成生产环境所需的文件。确保你在项目根目录下/var/www/your-nuxt-project。运行构建命令。Nuxt4 使用nuxi作为 CLI 工具npm run build会调用它。npm run build这个过程会执行以下操作编译 Vue 组件和 TypeScript如果使用。生成客户端资源打包后的 JS、CSS存放在.output/public/_nuxt。生成服务端 BundleNode.js 服务器代码存放在.output/server。生成nitro.json等配置文件。 构建时间取决于项目复杂度。完成后你会看到.output目录。关键点构建过程需要内存。如果服务器内存较小如 1GB可能会在构建过程中因内存不足而失败。如果遇到这种情况可以考虑增加服务器交换空间Swap。在本地构建然后将.output目录上传到服务器但需注意服务器 Node.js 版本与构建环境一致。使用NITRO_PRESETnode环境变量或调整nuxt.config.ts中的nitro配置来优化构建。6. 第四步使用 PM2 进程守护构建完成后我们不能直接运行npm start了事。我们需要 PM2 来管理这个 Node.js 进程。6.1 安装 PM2sudo npm install -g pm26.2 创建 PM2 生态系统配置文件在项目根目录下创建一个ecosystem.config.cjs文件。这个文件告诉 PM2 如何启动和管理你的应用。// 文件路径/var/www/your-nuxt-project/ecosystem.config.cjs module.exports { apps: [ { name: nuxt-app, // 你的应用名称在 PM2 列表中显示 port: 3000, // Nuxt 服务监听的端口需与后续 Nginx 配置对应 exec_mode: cluster, // 集群模式利用多核CPU instances: max, // 启动与 CPU 核心数相同的实例数或指定数字 script: ./.output/server/index.mjs, // Nuxt4 构建后的入口文件 env: { NODE_ENV: production, // 生产环境 HOST: 0.0.0.0, // 监听所有网络接口 PORT: 3000, }, }, ], };重要解释script这是 Nuxt4 构建后生成的服务端入口文件路径与 Nuxt3/4 的 Nitro 引擎输出结构一致。exec_mode: cluster和instances: max这是 PM2 的集群模式可以启动多个应用实例充分利用多核 CPU 性能并提高并发能力。对于 Nuxt SSR 应用这通常是推荐配置。HOST: 0.0.0.0确保应用监听所有网络接口而不仅仅是本地回环地址(127.0.0.1)这样 Nginx 才能访问到它。6.3 启动应用并设置开机自启使用 PM2 启动配置文件pm2 start ecosystem.config.cjs查看应用状态pm2 status你应该能看到名为nuxt-app的应用状态为online。保存当前 PM2 应用列表。这样当服务器重启后PM2 会自动恢复运行这些应用pm2 save生成系统启动脚本让 PM2 本身也能开机自启针对 Ubuntu 使用systemdpm2 startup systemd执行上述命令后它会输出一行需要你执行的sudo命令复制并运行它。例如sudo env PATH$PATH:/usr/bin /usr/lib/node_modules/pm2/bin/pm2 startup systemd -u your_username --hp /home/your_username完成后你的 Nuxt 应用就已经在后台稳定运行并且服务器重启后也会自动启动。6.4 常用的 PM2 命令pm2 logs nuxt-app # 查看实时日志 pm2 logs nuxt-app --lines 100 # 查看最近100行日志 pm2 stop nuxt-app # 停止应用 pm2 restart nuxt-app # 重启应用 pm2 delete nuxt-app # 从 PM2 列表中删除应用 pm2 monit # 打开监控仪表板7. 第五步配置 Nginx 反向代理现在你的应用在http://localhost:3000或http://服务器内网IP:3000上运行。接下来我们需要配置 Nginx让用户通过域名或服务器IP的 80/443 端口访问。7.1 安装 Nginxsudo apt install nginx -y7.2 创建 Nginx 站点配置文件Nginx 的站点配置文件通常放在/etc/nginx/sites-available/并通过在/etc/nginx/sites-enabled/创建软链接来启用。创建一个新的配置文件以你的域名命名如果没有域名也可以用服务器 IPsudo vim /etc/nginx/sites-available/your-domain.com将your-domain.com替换为你的实际域名或一个标识符如nuxt-app将以下配置粘贴到文件中。这是一个最基础但功能完整的配置它处理了将 HTTP 请求转发到本地的 Nuxt 应用3000端口。高效地直接提供_nuxt静态资源减轻 Node.js 进程负担。设置了一些对 SSR 应用有益的 HTTP 头。# 文件路径/etc/nginx/sites-available/your-domain.com server { listen 80; listen [::]:80; server_name your-domain.com www.your-domain.com; # 改为你的域名或用服务器IP # 静态资源缓存优化直接由 Nginx 处理性能最好 location /_nuxt/ { alias /var/www/your-nuxt-project/.output/public/_nuxt/; expires 1y; add_header Cache-Control public, immutable; gzip_static on; # 如果存在预压缩的 .gz 文件直接使用 } # 其他静态文件如 /favicon.ico, /robots.txt location / { try_files $uri $uri/ proxy; } # 反向代理到 Nuxt 应用 location proxy { 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 很重要确保正确的协议和主机头 proxy_set_header X-Forwarded-Host $host; proxy_set_header X-Forwarded-Port $server_port; } # 可选禁止访问某些敏感文件 location ~ /\.(?!well-known) { deny all; } }关键配置解析server_name你的域名。如果暂时没有域名可以填写服务器公网 IP或者用下划线_表示匹配所有。location /_nuxt/这是 Nuxt 生成的客户端静态资源路径。由 Nginx 直接提供这些文件速度远快于经过 Node.js 进程。proxy_pass http://localhost:3000这是核心将所有非静态文件的请求转发给我们在 PM2 下运行的 Nuxt 应用。proxy_set_header这些指令将客户端的真实 IP、协议等信息传递给后端的 Nuxt 应用对于应用内获取客户端信息至关重要。7.3 启用站点并测试配置创建符号链接以启用该站点sudo ln -s /etc/nginx/sites-available/your-domain.com /etc/nginx/sites-enabled/测试 Nginx 配置语法是否正确sudo nginx -t如果输出syntax is ok和test is successful则说明配置正确。重新加载 Nginx 使配置生效sudo systemctl reload nginx # 或者 sudo nginx -s reload7.4 验证访问现在打开浏览器访问你的服务器 IP 地址或配置的域名前提是 DNS 已解析。你应该能看到你的 Nuxt4 SSR 网站正常显示了。可以通过查看日志来确认请求流向# 查看 Nginx 访问日志 sudo tail -f /var/log/nginx/access.log # 查看 Nuxt 应用日志通过 PM2 pm2 logs nuxt-app8. 第六步配置 HTTPSSSL/TLS 证书为了安全生产环境网站必须使用 HTTPS。我们将使用 Let‘s Encrypt 提供的免费证书并通过certbot工具自动化获取和续签。8.1 安装 Certbotsudo apt install certbot python3-certbot-nginx -y8.2 获取并安装证书运行以下命令Certbot 会自动读取你的 Nginx 配置并引导你完成证书申请和配置更新。sudo certbot --nginx -d your-domain.com -d www.your-domain.com按照提示操作输入你的邮箱用于接收证书到期提醒。同意服务条款。选择是否订阅新闻邮件可选否。Certbot 会自动验证你对域名的控制权通过 HTTP 挑战然后下载证书并修改你的 Nginx 配置文件。完成后你的 Nginx 配置文件会被自动修改添加监听 443 端口的server块并配置好 SSL 证书路径。8.3 验证自动续签Let‘s Encrypt 证书有效期为 90 天Certbot 会设置一个定时任务自动续签。你可以测试自动续签是否正常工作sudo certbot renew --dry-run如果测试成功就无需担心证书过期问题。现在你可以通过https://your-domain.com安全地访问你的网站了。Nginx 也会自动将 HTTP 请求重定向到 HTTPS。9. 常见问题与排查思路部署过程很少一帆风顺。下表列出了你可能遇到的一些典型问题及解决方法。问题现象可能原因排查方式解决方案访问服务器 IP 显示 Nginx 默认页Nginx 默认站点 (default) 未被禁用或你的站点配置未生效。1.sudo nginx -t检查配置。2.ls /etc/nginx/sites-enabled/查看启用了哪些站点。禁用默认站点sudo rm /etc/nginx/sites-enabled/default然后sudo systemctl reload nginx。访问网站出现 502 Bad GatewayNginx 无法连接到后端的 Nuxt 应用PM2 进程。1.pm2 status检查应用是否运行。2.curl http://localhost:3000在服务器内部测试应用是否响应。3. 检查 Nginx 配置中proxy_pass的端口是否与 PM2 配置一致。1. 确保 PM2 应用已启动 (pm2 start)。2. 检查应用是否在正确端口监听 (netstat -tlnp | grep 3000)。3. 检查防火墙是否阻止了本地回环地址的通信通常不会。静态资源JS/CSS404Nginx 配置中location /_nuxt/的alias路径错误。1. 检查alias指向的路径是否存在.output/public/_nuxt目录。2. 查看 Nginx 错误日志sudo tail -f /var/log/nginx/error.log。修正alias路径确保指向构建生成的_nuxt目录的绝对路径。应用运行但样式错乱/交互失效客户端静态资源加载失败或 SSR 与客户端 Hydration 不匹配。1. 浏览器开发者工具查看 Console 和 Network 标签页是否有资源加载错误。2. 检查服务器和本地构建的 Node.js 版本是否一致。1. 确保 Nginx 正确代理了静态资源。2. 尝试在服务器上删除.output和node_modules重新npm install和npm run build。3. 检查是否有只在客户端运行的代码在 SSR 阶段被执行。PM2 应用频繁重启应用进程崩溃可能是内存不足、代码错误或端口冲突。pm2 logs nuxt-app --lines 50查看崩溃前的错误日志。1. 根据日志修复代码错误。2. 增加服务器内存或配置 Swap。3. 检查端口 3000 是否被其他进程占用。HTTPS 证书申请失败域名 DNS 解析未生效或服务器 80 端口被防火墙阻止。1.ping your-domain.com检查解析。2.sudo ufw status检查防火墙规则。3. 查看 Certbot 日志。1. 等待 DNS 生效或检查 DNS 设置。2. 确保服务器安全组和本地防火墙开放 80 端口。10. 最佳实践与进阶建议完成基础部署后以下建议能帮助你构建更健壮的生产环境。10.1 环境变量管理永远不要将敏感信息如 API Keys、数据库密码硬编码在代码中。使用环境变量。在项目根目录创建.env文件不要提交到 Git# .env NUXT_API_SECRETyour_super_secret_key_here NUXT_PUBLIC_API_BASEhttps://api.example.com在nuxt.config.ts或组件中通过process.env或useRuntimeConfig()访问。在 PM2 配置中也可以通过env对象注入环境变量。10.2 使用非 root 用户运行出于安全考虑建议创建一个专门的系统用户来运行你的 Node.js 应用而不是直接使用root。# 创建新用户例如 ‘deployer’ sudo adduser deployer # 将项目目录所有权赋予该用户 sudo chown -R deployer:deployer /var/www/your-nuxt-project # 切换到该用户进行后续的 npm install 和 pm2 操作 sudo su - deployer cd /var/www/your-nuxt-project # 然后在此用户下安装依赖、构建、启动 PM2 # 注意PM2 的 startup 命令也需要在此用户下运行10.3 日志管理与监控集中日志将 PM2 和 Nginx 的日志导出到如logrotate管理的文件或发送到远程日志服务如 ELK Stack、Sentry。进程监控除了pm2 monit可以集成 PM2 的 API 到你的监控系统或使用云服务商提供的监控告警。应用性能监控APM对于复杂应用考虑集成像 Sentry错误跟踪、或 OpenTelemetry链路追踪等工具。10.4 自动化部署CI/CD手动部署效率低下且易出错。可以考虑设置简单的 CI/CD 流程使用 Git Hooks在服务器上配置 Git 仓库的post-receive钩子在收到推送后自动执行拉取、安装、构建、重启 PM2 等操作。使用 GitHub Actions / GitLab CI在代码仓库中配置 CI 脚本在合并到主分支后自动通过 SSH 连接到服务器执行部署脚本。使用 Docker将你的 Nuxt 应用 Docker 化在服务器上使用 Docker Compose 管理。这能提供更好的环境一致性。10.5 性能优化Nginx 缓存对于某些不常变化的 SSR 页面可以在 Nginx 层面设置代理缓存极大减轻 Nuxt 应用压力。CDN将/_nuxt/静态资源上传到 CDN并修改nuxt.config.ts中的app.head或runtimeConfig.public来配置资源基础 URL。Nuxt 层优化利用 Nuxt 的useAsyncData、useLazyAsyncData进行数据获取优化合理使用client-only组件。从本地开发到云端部署将 Vue3 Nuxt4 SSR 应用成功上线是一个涉及前端、Node.js 运维和 Linux 系统的综合工程。本文详细拆解了从服务器环境准备、代码部署、构建、进程守护、反向代理到 HTTPS 配置的完整链路并提供了常见问题的排查思路和进阶最佳实践。最关键的是理解这个架构PM2 负责让 Node.js 应用“活”得稳定Nginx 负责对外提供高效、安全的访问通道。掌握了这个核心无论工具如何迭代你都能快速适应。建议你将服务器配置过程脚本化并尽快引入简单的自动化部署流程这将是你从“会部署”到“高效部署”的关键一步。
Vue3 Nuxt4 SSR应用部署指南：Ubuntu服务器配置与PM2+Nginx实战
如果你是一名前端开发者正在使用 Vue3 和 Nuxt4 构建一个现代化的 Web 应用并且希望它拥有更好的 SEO 和首屏加载速度那么服务器端渲染SSR几乎是必经之路。然而从本地开发到将 SSR 应用成功部署到一台 Ubuntu 服务器上这中间的路途往往布满荆棘Node.js 环境、PM2 进程守护、Nginx 反向代理、SSL 证书、防火墙配置……任何一个环节出错你的应用都可能无法访问。网上教程很多但大多只讲单一环节或者版本老旧。当你把 Vue3、Nuxt4、Ubuntu 这几个关键词组合在一起时会发现缺少一份能串联所有步骤、讲清原理、并指出常见深坑的完整指南。这篇文章的目的就是填补这个空白。它不是简单的命令罗列而是基于真实部署经验为你梳理出一条从代码到线上可访问的清晰路径并解释每一步背后的“为什么”。我们将聚焦于一个最经典的部署架构在 Ubuntu 服务器上使用 PM2 管理 Nuxt4 SSR 应用进程并通过 Nginx 作为反向代理和静态资源服务器。你会看到部署 SSR 应用的核心不仅是运行npm run build和npm start更在于如何构建一个稳定、可维护的生产环境。1. 为什么 Nuxt4 SSR 部署比传统 SPA 更复杂在开始动手之前我们必须先理解挑战所在。如果你只部署过 Vue CLI 创建的纯客户端 SPA单页应用那么过程通常很简单运行npm run build将生成的dist文件夹扔到 Nginx 或对象存储配置一下路由回退就完成了。因为 SPA 最终只是一堆静态的 HTML、CSS 和 JS 文件。但 Nuxt4 在启用 SSR 模式后情况发生了根本变化它需要一个 Node.js 运行时环境SSR 意味着首次页面渲染是在服务器端完成的。这需要你的服务器上有一个持续运行的 Node.js 进程来执行 Vue 组件代码、生成 HTML。这个进程就是你的应用服务器。它涉及构建与运行两个阶段构建阶段在服务器或 CI/CD 环境中你需要运行npm run build或nuxi build。这个过程会编译你的 Vue 代码并生成两部分产物客户端 Bundle和 SPA 类似的静态资源_nuxt/目录。服务端 Bundle一个用于 Node.js 环境运行的服务器入口文件通常位于.output目录。运行阶段你需要启动这个服务端 Bundle它会在指定端口如 3000启动一个 HTTP 服务器监听请求动态渲染页面。进程管理是必须的你不能仅仅通过node .output/server/index.mjs来启动服务因为一旦终端关闭进程就结束了。你需要一个像PM2这样的进程守护管理器来保证应用持续运行并在崩溃时自动重启。需要反向代理我们通常不会让用户直接访问 Node.js 服务的端口如http://你的服务器IP:3000。更专业的做法是使用Nginx监听 80/443 端口HTTP/HTTPS然后将请求转发给内部运行的 Node.js 应用。这样做的好处包括负载均衡、静态文件高效服务、SSL 卸载、安全过滤等。所以部署 Nuxt4 SSR 应用本质上是在服务器上搭建一个由“Node.js 应用进程 反向代理网关”构成的微型后端服务集群。理解了这一点后续的所有步骤就都有了清晰的逻辑。2. 环境准备你的服务器与工具清单在开始部署前请确保你拥有并配置好以下资源。这是整个流程的基石。2.1 服务器要求操作系统Ubuntu 20.04 LTS 或 22.04 LTS长期支持版。本文以 Ubuntu 22.04 为例其他版本大同小异。最低配置对于初期项目1核 CPU、2GB 内存的云服务器实例如阿里云、腾讯云、AWS 的轻量应用服务器足够运行。内存尤为重要因为 Node.js 进程和构建过程都比较消耗内存。网络确保服务器的安全组或防火墙规则开放了22端口SSH、80端口HTTP和443端口HTTPS。后续我们会在服务器内部使用 3000 端口这个端口不需要对公网开放。2.2 本地与服务器工具本地机器你需要一个终端工具如 macOS 的 Terminal、Windows 的 PowerShell 或 Git Bash通过 SSH 连接服务器。服务器环境我们将通过 SSH 在服务器上安装一系列工具Node.js npm运行 Nuxt 应用的核心。PM2进程管理。NginxWeb 服务器和反向代理。Git从代码仓库拉取项目可选但推荐。2.3 项目前提你有一个基于 Vue3 和 Nuxt4 开发完成的项目。项目根目录下的nuxt.config.ts中配置了ssr: true这是 Nuxt4 的默认配置除非你显式关闭。你有一个可以访问的代码仓库如 GitHub、GitLab或者已经将项目代码打包准备好。3. 第一步连接服务器与基础环境配置让我们从登录服务器开始搭建起最基本的环境。3.1 SSH 连接服务器使用你的终端通过 SSH 连接到 Ubuntu 服务器。你需要服务器的公网 IP 地址和登录密码或密钥。ssh usernameyour_server_ip # 例如ssh root123.123.123.123连接成功后你将进入服务器的命令行界面。3.2 更新系统与安装基础工具首先更新系统的软件包列表并升级现有软件这是一个好习惯。sudo apt update sudo apt upgrade -y安装一些后续可能需要的工具如curl和vim。sudo apt install curl vim -y3.3 安装 Node.js 与 npmUbuntu 默认的软件源中的 Node.js 版本可能较旧。我们推荐使用 NodeSource 提供的仓库来安装长期支持版LTS。安装 NodeSource 仓库脚本这里安装 Node.js 20.x LTS你可以根据需要选择其他版本curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -安装 Node.js 和 npmsudo apt install -y nodejs验证安装node --version # 应输出 v20.x.x npm --version # 应输出对应的 npm 版本4. 第二步部署你的 Nuxt4 项目代码有几种方式可以将代码放到服务器上我们介绍两种最常用的。4.1 方法一通过 Git 克隆推荐如果你的代码在 Git 仓库中这是最清晰、便于后续更新的方式。在服务器上安装 Gitsudo apt install git -y选择一个目录存放你的项目例如/var/www/cd /var sudo mkdir www cd www克隆你的项目仓库这里以公开仓库为例私有仓库需要配置 SSH 密钥或使用 HTTPS 密码sudo git clone https://github.com/your-username/your-nuxt-project.git cd your-nuxt-project安装项目依赖npm install # 或使用 yarn/pnpm注意确保服务器上的 Node.js 版本符合项目package.json中engines字段的要求。4.2 方法二通过压缩包上传如果你不想在服务器上配置 Git或者只是做一次性的部署。在本地将你的项目目录排除node_modules和.env等敏感文件打包# 在本地项目根目录执行 tar -czf nuxt-project.tar.gz --excludenode_modules --exclude.git --exclude.env .使用scp命令将压缩包上传到服务器scp nuxt-project.tar.gz usernameyour_server_ip:/tmp/回到服务器 SSH 会话解压到目标目录sudo mkdir -p /var/www/nuxt-project sudo tar -xzf /tmp/nuxt-project.tar.gz -C /var/www/nuxt-project cd /var/www/nuxt-project安装项目依赖npm install5. 第三步构建 Nuxt4 SSR 应用代码就位后我们需要在服务器上进行构建生成生产环境所需的文件。确保你在项目根目录下/var/www/your-nuxt-project。运行构建命令。Nuxt4 使用nuxi作为 CLI 工具npm run build会调用它。npm run build这个过程会执行以下操作编译 Vue 组件和 TypeScript如果使用。生成客户端资源打包后的 JS、CSS存放在.output/public/_nuxt。生成服务端 BundleNode.js 服务器代码存放在.output/server。生成nitro.json等配置文件。 构建时间取决于项目复杂度。完成后你会看到.output目录。关键点构建过程需要内存。如果服务器内存较小如 1GB可能会在构建过程中因内存不足而失败。如果遇到这种情况可以考虑增加服务器交换空间Swap。在本地构建然后将.output目录上传到服务器但需注意服务器 Node.js 版本与构建环境一致。使用NITRO_PRESETnode环境变量或调整nuxt.config.ts中的nitro配置来优化构建。6. 第四步使用 PM2 进程守护构建完成后我们不能直接运行npm start了事。我们需要 PM2 来管理这个 Node.js 进程。6.1 安装 PM2sudo npm install -g pm26.2 创建 PM2 生态系统配置文件在项目根目录下创建一个ecosystem.config.cjs文件。这个文件告诉 PM2 如何启动和管理你的应用。// 文件路径/var/www/your-nuxt-project/ecosystem.config.cjs module.exports { apps: [ { name: nuxt-app, // 你的应用名称在 PM2 列表中显示 port: 3000, // Nuxt 服务监听的端口需与后续 Nginx 配置对应 exec_mode: cluster, // 集群模式利用多核CPU instances: max, // 启动与 CPU 核心数相同的实例数或指定数字 script: ./.output/server/index.mjs, // Nuxt4 构建后的入口文件 env: { NODE_ENV: production, // 生产环境 HOST: 0.0.0.0, // 监听所有网络接口 PORT: 3000, }, }, ], };重要解释script这是 Nuxt4 构建后生成的服务端入口文件路径与 Nuxt3/4 的 Nitro 引擎输出结构一致。exec_mode: cluster和instances: max这是 PM2 的集群模式可以启动多个应用实例充分利用多核 CPU 性能并提高并发能力。对于 Nuxt SSR 应用这通常是推荐配置。HOST: 0.0.0.0确保应用监听所有网络接口而不仅仅是本地回环地址(127.0.0.1)这样 Nginx 才能访问到它。6.3 启动应用并设置开机自启使用 PM2 启动配置文件pm2 start ecosystem.config.cjs查看应用状态pm2 status你应该能看到名为nuxt-app的应用状态为online。保存当前 PM2 应用列表。这样当服务器重启后PM2 会自动恢复运行这些应用pm2 save生成系统启动脚本让 PM2 本身也能开机自启针对 Ubuntu 使用systemdpm2 startup systemd执行上述命令后它会输出一行需要你执行的sudo命令复制并运行它。例如sudo env PATH$PATH:/usr/bin /usr/lib/node_modules/pm2/bin/pm2 startup systemd -u your_username --hp /home/your_username完成后你的 Nuxt 应用就已经在后台稳定运行并且服务器重启后也会自动启动。6.4 常用的 PM2 命令pm2 logs nuxt-app # 查看实时日志 pm2 logs nuxt-app --lines 100 # 查看最近100行日志 pm2 stop nuxt-app # 停止应用 pm2 restart nuxt-app # 重启应用 pm2 delete nuxt-app # 从 PM2 列表中删除应用 pm2 monit # 打开监控仪表板7. 第五步配置 Nginx 反向代理现在你的应用在http://localhost:3000或http://服务器内网IP:3000上运行。接下来我们需要配置 Nginx让用户通过域名或服务器IP的 80/443 端口访问。7.1 安装 Nginxsudo apt install nginx -y7.2 创建 Nginx 站点配置文件Nginx 的站点配置文件通常放在/etc/nginx/sites-available/并通过在/etc/nginx/sites-enabled/创建软链接来启用。创建一个新的配置文件以你的域名命名如果没有域名也可以用服务器 IPsudo vim /etc/nginx/sites-available/your-domain.com将your-domain.com替换为你的实际域名或一个标识符如nuxt-app将以下配置粘贴到文件中。这是一个最基础但功能完整的配置它处理了将 HTTP 请求转发到本地的 Nuxt 应用3000端口。高效地直接提供_nuxt静态资源减轻 Node.js 进程负担。设置了一些对 SSR 应用有益的 HTTP 头。# 文件路径/etc/nginx/sites-available/your-domain.com server { listen 80; listen [::]:80; server_name your-domain.com www.your-domain.com; # 改为你的域名或用服务器IP # 静态资源缓存优化直接由 Nginx 处理性能最好 location /_nuxt/ { alias /var/www/your-nuxt-project/.output/public/_nuxt/; expires 1y; add_header Cache-Control public, immutable; gzip_static on; # 如果存在预压缩的 .gz 文件直接使用 } # 其他静态文件如 /favicon.ico, /robots.txt location / { try_files $uri $uri/ proxy; } # 反向代理到 Nuxt 应用 location proxy { 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 很重要确保正确的协议和主机头 proxy_set_header X-Forwarded-Host $host; proxy_set_header X-Forwarded-Port $server_port; } # 可选禁止访问某些敏感文件 location ~ /\.(?!well-known) { deny all; } }关键配置解析server_name你的域名。如果暂时没有域名可以填写服务器公网 IP或者用下划线_表示匹配所有。location /_nuxt/这是 Nuxt 生成的客户端静态资源路径。由 Nginx 直接提供这些文件速度远快于经过 Node.js 进程。proxy_pass http://localhost:3000这是核心将所有非静态文件的请求转发给我们在 PM2 下运行的 Nuxt 应用。proxy_set_header这些指令将客户端的真实 IP、协议等信息传递给后端的 Nuxt 应用对于应用内获取客户端信息至关重要。7.3 启用站点并测试配置创建符号链接以启用该站点sudo ln -s /etc/nginx/sites-available/your-domain.com /etc/nginx/sites-enabled/测试 Nginx 配置语法是否正确sudo nginx -t如果输出syntax is ok和test is successful则说明配置正确。重新加载 Nginx 使配置生效sudo systemctl reload nginx # 或者 sudo nginx -s reload7.4 验证访问现在打开浏览器访问你的服务器 IP 地址或配置的域名前提是 DNS 已解析。你应该能看到你的 Nuxt4 SSR 网站正常显示了。可以通过查看日志来确认请求流向# 查看 Nginx 访问日志 sudo tail -f /var/log/nginx/access.log # 查看 Nuxt 应用日志通过 PM2 pm2 logs nuxt-app8. 第六步配置 HTTPSSSL/TLS 证书为了安全生产环境网站必须使用 HTTPS。我们将使用 Let‘s Encrypt 提供的免费证书并通过certbot工具自动化获取和续签。8.1 安装 Certbotsudo apt install certbot python3-certbot-nginx -y8.2 获取并安装证书运行以下命令Certbot 会自动读取你的 Nginx 配置并引导你完成证书申请和配置更新。sudo certbot --nginx -d your-domain.com -d www.your-domain.com按照提示操作输入你的邮箱用于接收证书到期提醒。同意服务条款。选择是否订阅新闻邮件可选否。Certbot 会自动验证你对域名的控制权通过 HTTP 挑战然后下载证书并修改你的 Nginx 配置文件。完成后你的 Nginx 配置文件会被自动修改添加监听 443 端口的server块并配置好 SSL 证书路径。8.3 验证自动续签Let‘s Encrypt 证书有效期为 90 天Certbot 会设置一个定时任务自动续签。你可以测试自动续签是否正常工作sudo certbot renew --dry-run如果测试成功就无需担心证书过期问题。现在你可以通过https://your-domain.com安全地访问你的网站了。Nginx 也会自动将 HTTP 请求重定向到 HTTPS。9. 常见问题与排查思路部署过程很少一帆风顺。下表列出了你可能遇到的一些典型问题及解决方法。问题现象可能原因排查方式解决方案访问服务器 IP 显示 Nginx 默认页Nginx 默认站点 (default) 未被禁用或你的站点配置未生效。1.sudo nginx -t检查配置。2.ls /etc/nginx/sites-enabled/查看启用了哪些站点。禁用默认站点sudo rm /etc/nginx/sites-enabled/default然后sudo systemctl reload nginx。访问网站出现 502 Bad GatewayNginx 无法连接到后端的 Nuxt 应用PM2 进程。1.pm2 status检查应用是否运行。2.curl http://localhost:3000在服务器内部测试应用是否响应。3. 检查 Nginx 配置中proxy_pass的端口是否与 PM2 配置一致。1. 确保 PM2 应用已启动 (pm2 start)。2. 检查应用是否在正确端口监听 (netstat -tlnp | grep 3000)。3. 检查防火墙是否阻止了本地回环地址的通信通常不会。静态资源JS/CSS404Nginx 配置中location /_nuxt/的alias路径错误。1. 检查alias指向的路径是否存在.output/public/_nuxt目录。2. 查看 Nginx 错误日志sudo tail -f /var/log/nginx/error.log。修正alias路径确保指向构建生成的_nuxt目录的绝对路径。应用运行但样式错乱/交互失效客户端静态资源加载失败或 SSR 与客户端 Hydration 不匹配。1. 浏览器开发者工具查看 Console 和 Network 标签页是否有资源加载错误。2. 检查服务器和本地构建的 Node.js 版本是否一致。1. 确保 Nginx 正确代理了静态资源。2. 尝试在服务器上删除.output和node_modules重新npm install和npm run build。3. 检查是否有只在客户端运行的代码在 SSR 阶段被执行。PM2 应用频繁重启应用进程崩溃可能是内存不足、代码错误或端口冲突。pm2 logs nuxt-app --lines 50查看崩溃前的错误日志。1. 根据日志修复代码错误。2. 增加服务器内存或配置 Swap。3. 检查端口 3000 是否被其他进程占用。HTTPS 证书申请失败域名 DNS 解析未生效或服务器 80 端口被防火墙阻止。1.ping your-domain.com检查解析。2.sudo ufw status检查防火墙规则。3. 查看 Certbot 日志。1. 等待 DNS 生效或检查 DNS 设置。2. 确保服务器安全组和本地防火墙开放 80 端口。10. 最佳实践与进阶建议完成基础部署后以下建议能帮助你构建更健壮的生产环境。10.1 环境变量管理永远不要将敏感信息如 API Keys、数据库密码硬编码在代码中。使用环境变量。在项目根目录创建.env文件不要提交到 Git# .env NUXT_API_SECRETyour_super_secret_key_here NUXT_PUBLIC_API_BASEhttps://api.example.com在nuxt.config.ts或组件中通过process.env或useRuntimeConfig()访问。在 PM2 配置中也可以通过env对象注入环境变量。10.2 使用非 root 用户运行出于安全考虑建议创建一个专门的系统用户来运行你的 Node.js 应用而不是直接使用root。# 创建新用户例如 ‘deployer’ sudo adduser deployer # 将项目目录所有权赋予该用户 sudo chown -R deployer:deployer /var/www/your-nuxt-project # 切换到该用户进行后续的 npm install 和 pm2 操作 sudo su - deployer cd /var/www/your-nuxt-project # 然后在此用户下安装依赖、构建、启动 PM2 # 注意PM2 的 startup 命令也需要在此用户下运行10.3 日志管理与监控集中日志将 PM2 和 Nginx 的日志导出到如logrotate管理的文件或发送到远程日志服务如 ELK Stack、Sentry。进程监控除了pm2 monit可以集成 PM2 的 API 到你的监控系统或使用云服务商提供的监控告警。应用性能监控APM对于复杂应用考虑集成像 Sentry错误跟踪、或 OpenTelemetry链路追踪等工具。10.4 自动化部署CI/CD手动部署效率低下且易出错。可以考虑设置简单的 CI/CD 流程使用 Git Hooks在服务器上配置 Git 仓库的post-receive钩子在收到推送后自动执行拉取、安装、构建、重启 PM2 等操作。使用 GitHub Actions / GitLab CI在代码仓库中配置 CI 脚本在合并到主分支后自动通过 SSH 连接到服务器执行部署脚本。使用 Docker将你的 Nuxt 应用 Docker 化在服务器上使用 Docker Compose 管理。这能提供更好的环境一致性。10.5 性能优化Nginx 缓存对于某些不常变化的 SSR 页面可以在 Nginx 层面设置代理缓存极大减轻 Nuxt 应用压力。CDN将/_nuxt/静态资源上传到 CDN并修改nuxt.config.ts中的app.head或runtimeConfig.public来配置资源基础 URL。Nuxt 层优化利用 Nuxt 的useAsyncData、useLazyAsyncData进行数据获取优化合理使用client-only组件。从本地开发到云端部署将 Vue3 Nuxt4 SSR 应用成功上线是一个涉及前端、Node.js 运维和 Linux 系统的综合工程。本文详细拆解了从服务器环境准备、代码部署、构建、进程守护、反向代理到 HTTPS 配置的完整链路并提供了常见问题的排查思路和进阶最佳实践。最关键的是理解这个架构PM2 负责让 Node.js 应用“活”得稳定Nginx 负责对外提供高效、安全的访问通道。掌握了这个核心无论工具如何迭代你都能快速适应。建议你将服务器配置过程脚本化并尽快引入简单的自动化部署流程这将是你从“会部署”到“高效部署”的关键一步。