Nuxt 4应用部署在香港服务器,Node.js版本与生产入口怎么配

发布人:A5数据发布时间:2026-10-18 09:43阅读量:137

在香港服务器上首次上线 Nuxt 4,生产运行方式应与本地开发区分开:服务器先执行 npm run build,再由 Node.js 启动编译后的 .output/server/index.mjs,而不是长期运行 npm run dev。

Node.js 版本建议跟随项目锁定的兼容范围选择偶数版本。下面以 Ubuntu 22.04/24.04、Node.js 22 LTS、Nginx 和 systemd 为例;如果项目的 package.json 明确要求 Node.js 20,则将示例中的 22 替换为项目允许的 Node.js 20 版本。公网入口由 Nginx 监听 80/443,Nuxt 只绑定 127.0.0.1:3000,这样可以避免直接暴露应用进程。

准备条件与部署边界

以下步骤适用于 Nuxt 4 的 SSR 或带服务端 API 的 Node.js 部署模式,服务器条件包括:

  • 一台香港地域的 Linux 云服务器或独立服务器。
  • 操作系统为 Ubuntu 22.04、Ubuntu 24.04 或相近的 Debian 系发行版。
  • 已拥有一个解析到服务器公网 IP 的域名,例如 app.example.com。
  • 具备 sudo 权限。
  • 项目中存在 package.json 和对应锁文件,例如 package-lock.json。
  • 项目可以在本地通过 npm run build 构建成功。
  • 云平台安全组只开放必要端口,通常为 SSH 管理端口、80 和 443;不需要对公网开放 3000。

这里使用 npm 作为示例。如果项目实际使用 pnpm 或 Yarn,应按照项目中的 pnpm-lock.yaml、yarn.lock 和 packageManager 字段执行对应命令,不要混用锁文件。

Nuxt 4 生产入口是:

/srv/nuxt-app/current/.output/server/index.mjs

实际启动命令为:

node .output/server/index.mjs

current 是后面创建的当前版本软链接,便于发布新版本和回滚。香港服务器的地域不会改变 Nuxt 的启动方式,只会影响用户到服务器之间的网络链路和 DNS 解析位置。

对于需要在香港落地 Nuxt 4 SSR、接口服务或业务后台的场景,A5数据提供香港物理服务器资源,覆盖入门建站、Xeon Gold 与 AMD EPYC 等配置,并配备 SSD 或 NVMe 存储及不同内存规格,可承载 Node.js 应用、数据库和多任务运行。香港产品同时提供 CN2 与国际带宽方案,便于结合访问区域与业务链路构建生产环境。

第一步:创建应用用户和目录

不建议使用 root 直接运行 Node.js 进程。先创建专用用户和版本目录:

sudo adduser --disabled-password --gecos "" nuxtapp
sudo mkdir -p /srv/nuxt-app/releases
sudo chown -R nuxtapp:nuxtapp /srv/nuxt-app

上述命令不会删除现有项目;如果服务器已经有同名用户或目录,应先检查:

id nuxtapp
sudo ls -la /srv/nuxt-app

如果用户已存在,只需要确认目录归属:

sudo chown -R nuxtapp:nuxtapp /srv/nuxt-app

预期结果是 /srv/nuxt-app 可以由 nuxtapp 用户读写,而其他普通用户没有不必要的写入权限。

第二步:确认 Nuxt 4 与 Node.js 版本

先查看项目声明的运行条件:

cd /path/to/your/nuxt-project

node --version
npm --version
npm pkg get engines
npm pkg get packageManager

如果 engines 有输出,应优先遵循项目声明。例如:

{
  "node": ">=20"
}

表示 Node.js 20 及以上版本通常符合范围;如果项目写的是:

{
  "node": "^20.19.0"
}

则不要直接切换到 Node.js 22,除非项目依赖已经验证支持该版本。

Nuxt 4 一般使用 Node.js 20 或更高版本。生产环境建议选择偶数 LTS 线路,并固定具体版本,避免服务器重新安装时自动获得不同的小版本。下面以 Node.js 22 为示例,如果项目要求 Node.js 20,则将安装命令中的 22 改为 20。

如果服务器还没有统一的 Node.js 管理方式,可以使用 nvm 安装:

sudo -iu nuxtapp bash -lc '
set -e
curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source "$HOME/.nvm/nvm.sh"
nvm install 22
nvm alias default 22
node --version
npm --version
'

示例输出可能类似:

v22.x.x
10.x.x

这里的版本号仅用于说明格式,不代表服务器的实际执行结果。安装完成后,确认 systemd 应使用哪个 Node.js 二进制文件:

sudo -iu nuxtapp bash -lc '
source "$HOME/.nvm/nvm.sh"
readlink -f "$(command -v node)"
'

示例输出:

/home/nuxtapp/.nvm/versions/node/v22.x.x/bin/node

后续 systemd 配置中的 ExecStart 必须填写这条命令返回的完整路径。systemd 不会自动读取交互式 shell 的 nvm 初始化脚本,直接写 node 可能导致服务启动失败。

如果服务器已经由系统包管理器安装 Node.js,则使用:

command -v node
readlink -f "$(command -v node)"
node --version

不要在同一台服务器上同时维护多个没有明确用途的 Node.js 安装路径,否则容易出现命令行版本与 systemd 版本不一致。

第三步:上传代码并创建发布目录

每次发布使用一个独立目录,便于保留上一版。创建本次发布目录:

RELEASE_DIR="/srv/nuxt-app/releases/$(date +%Y%m%d-%H%M%S)"
sudo -iu nuxtapp mkdir -p "$RELEASE_DIR"
echo "$RELEASE_DIR"

示例:

/srv/nuxt-app/releases/20250308-143000

将项目源码上传到该目录。源码至少应包含:

  • package.json
  • 对应的锁文件
  • nuxt.config.ts 或 nuxt.config.js
  • 页面、组件和服务端代码
  • 构建所需的配置文件

如果使用 Git,可以执行类似命令:

sudo -iu nuxtapp git clone --depth 1 --branch main \
  https://example.com/your-repository.git \
  "$RELEASE_DIR"

如果使用本地构建后上传,则不要只上传 .nuxt 目录。生产运行需要通过服务器或构建流水线生成完整的 .output 目录。

进入发布目录,确认 Node.js 和锁文件:

sudo -iu nuxtapp bash -lc "
set -e
cd '$RELEASE_DIR'
source \"\$HOME/.nvm/nvm.sh\"
node --version
test -f package.json
test -f package-lock.json
"

如果项目使用 pnpm 或 Yarn,应将锁文件检查改为对应文件,不要为了通过检查而手工创建一个无关的 package-lock.json。

第四步:安装依赖并构建 Nuxt 4

npm 项目使用 npm ci 安装依赖。该命令要求 package-lock.json 与 package.json 保持一致,适合首次生产部署:

sudo -iu nuxtapp bash -lc "
set -e
cd '$RELEASE_DIR'
source \"\$HOME/.nvm/nvm.sh\"
npm ci
npm run build
test -f .output/server/index.mjs
"

命令成功时,最后的 test 不会输出内容,并且退出状态为 0。可以进一步查看构建结果:

sudo -iu nuxtapp bash -lc "
cd '$RELEASE_DIR'
du -sh .output
ls -l .output/server/index.mjs
"

Nuxt 4 的 Node.js 生产入口必须来自构建后的 .output/server/index.mjs。以下命令不适合作为生产服务入口:

npm run dev
nuxi dev

它们用于开发环境,通常会启用热更新、开发调试能力和不同的资源处理方式。

如果项目构建失败,应先根据错误信息处理 Node.js、锁文件或依赖问题,不要直接删除锁文件后重新安装。删除锁文件可能改变依赖版本,使本地和生产环境产生新的差异。

构建成功后,将当前版本切换到新发布目录:

sudo -iu nuxtapp ln -sfnT "$RELEASE_DIR" /srv/nuxt-app/current
sudo readlink -f /srv/nuxt-app/current

预期结果应指向本次发布目录:

/srv/nuxt-app/releases/20250308-143000

如果原来不存在 current,这是首次创建;如果已经存在,应先记录旧链接,便于后续回滚。

第五步:配置运行时环境变量

Nuxt 的运行时配置应与源码分离,尤其是数据库密码、API 密钥和第三方服务凭据。创建 systemd 使用的环境文件:

sudo install -o root -g root -m 600 /dev/null /etc/nuxt-app.env
sudoedit /etc/nuxt-app.env

可以使用以下结构:

NODE_ENV=production
NITRO_HOST=127.0.0.1
NITRO_PORT=3000
NUXT_PUBLIC_SITE_URL=https://app.example.com
NUXT_PUBLIC_API_BASE=https://api.example.com
# NUXT_API_SECRET=请填写实际密钥

其中:

  • NITRO_HOST=127.0.0.1 表示只允许本机访问 Nuxt。
  • NITRO_PORT=3000 表示应用监听本机 3000 端口。
  • NUXT_PUBLIC_ 开头的变量会进入客户端可访问的公共配置,不应放置密码。
  • 私有配置应使用 NUXT_ 开头,并在 runtimeConfig 中配置对应字段。
  • NUXT_PUBLIC_SITE_URL 的值应与实际域名一致,不要将示例域名直接用于生产。

例如,项目配置可以类似:

export default defineNuxtConfig({
  runtimeConfig: {
    apiSecret: '',
    public: {
      siteUrl: '',
      apiBase: ''
    }
  }
})

对应环境变量为:

NUXT_API_SECRET=实际私有密钥
NUXT_PUBLIC_SITE_URL=https://app.example.com
NUXT_PUBLIC_API_BASE=https://api.example.com

变量名称必须和 runtimeConfig 层级对应。修改 /etc/nuxt-app.env 后需要重启 systemd 服务,已经运行的 Node.js 进程不会自动读取新值。

如果项目在构建阶段直接读取 process.env,相关变量还需要在 npm run build 时提供。更适合生产部署的方式是使用 Nuxt runtimeConfig,这样同一份构建产物可以通过不同环境文件运行。

第六步:创建 systemd 生产服务

先确认 Node.js 的绝对路径:

sudo -iu nuxtapp bash -lc '
source "$HOME/.nvm/nvm.sh"
readlink -f "$(command -v node)"
'

编辑服务文件:

sudoedit /etc/systemd/system/nuxt-app.service

内容如下:

[Unit]
Description=Nuxt 4 production application
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=nuxtapp
Group=nuxtapp
WorkingDirectory=/srv/nuxt-app/current
EnvironmentFile=/etc/nuxt-app.env
ExecStart=/home/nuxtapp/.nvm/versions/node/v22.x.x/bin/node /srv/nuxt-app/current/.output/server/index.mjs
Restart=on-failure
RestartSec=5
KillSignal=SIGTERM
TimeoutStopSec=30
NoNewPrivileges=true
PrivateTmp=true

[Install]
WantedBy=multi-user.target

ExecStart 中的 v22.x.x 只是示例占位符,必须替换为前面 readlink -f "$(command -v node)" 返回的实际版本路径。不能在 systemd 中写成带通配符的路径,例如:

ExecStart=/home/nuxtapp/.nvm/versions/node/v22.*/bin/node ...

systemd 不会展开这种通配符。

加载并启动服务:

sudo systemctl daemon-reload
sudo systemctl enable --now nuxt-app
sudo systemctl status nuxt-app --no-pager

预期状态包含:

Active: active (running)

查看应用日志:

sudo journalctl -u nuxt-app -n 50 --no-pager
sudo journalctl -u nuxt-app -f

另开一个终端确认监听端口:

sudo ss -lntp | grep ':3000'

理想结果是 Node.js 监听 127.0.0.1:3000。如果显示为 0.0.0.0:3000,应用仍可运行,但不符合本例中只通过 Nginx 暴露的收敛方式,应检查 NITRO_HOST 是否生效。

第七步:先进行本机访问验证

在配置 Nginx 前,先确认 Nuxt 应用本身正常:

curl -I http://127.0.0.1:3000/

根据页面和路由实现,常见结果为:

HTTP/1.1 200 OK

如果首页需要特定 Host,也可以:

curl -i \
  -H 'Host: app.example.com' \
  http://127.0.0.1:3000/

本机访问成功说明 Node.js、Nuxt 构建产物和基础运行时配置基本正常。此时不要急着排查 DNS 或证书问题,因为公网入口尚未配置。

如果本机访问失败,先查看:

sudo systemctl status nuxt-app --no-pager
sudo journalctl -u nuxt-app -n 100 --no-pager
sudo ss -lntp | grep ':3000'

第八步:配置 Nginx 作为生产入口

安装 Nginx:

sudo apt update
sudo apt install -y nginx

创建站点配置:

sudoedit /etc/nginx/sites-available/nuxt-app

写入以下内容:

第八步:配置 Nginx 作为生产入口配图

server {
    listen 80;
    listen [::]:80;

    server_name app.example.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;

        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_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        proxy_read_timeout 60s;
    }
}

将 app.example.com 替换为实际域名。启用配置:

sudo ln -s /etc/nginx/sites-available/nuxt-app \
  /etc/nginx/sites-enabled/nuxt-app

如果软链接已经存在,不要重复创建;先检查:

sudo ls -l /etc/nginx/sites-enabled/nuxt-app

先测试配置,再重新加载:

sudo nginx -t
sudo systemctl reload nginx

只有 nginx -t 显示语法检查成功时才执行 reload。Nginx 配置有误时不要强制重启,否则可能使已有站点同时中断。

此时,域名的 A 记录应指向香港服务器公网 IPv4 地址。如果服务器配置了可用 IPv6,再设置 AAAA 记录;没有 IPv6 服务时不要仅因为域名平台支持就添加错误的 AAAA 记录。

检查 DNS:

dig +short A app.example.com
dig +short AAAA app.example.com

确认解析完成后,访问:

curl -I http://app.example.com/

如果本机 3000 端口正常而域名访问出现 502,问题通常位于 Nginx 到 Node.js 之间;如果域名解析不到服务器,则先处理 DNS,不要修改 Nuxt 代码。

第九步:配置 HTTPS 证书

生产域名通常应使用 HTTPS。使用 Certbot 配置 Nginx 证书前,先备份站点配置:

sudo cp -a /etc/nginx/sites-available/nuxt-app \
  "/etc/nginx/sites-available/nuxt-app.bak.$(date +%Y%m%d-%H%M%S)"

安装 Certbot:

sudo apt install -y certbot python3-certbot-nginx

申请并写入 Nginx 配置:

sudo certbot --nginx -d app.example.com

Certbot 可能会自动增加 HTTPS 监听和 HTTP 到 HTTPS 的跳转。完成后验证:

curl -I https://app.example.com/
sudo nginx -t
sudo certbot renew --dry-run

证书申请前,80 端口必须能够从公网访问;如果域名尚未解析到香港服务器,HTTP 校验通常会失败。

证书配置属于 Nginx 层,Nuxt 仍然只需要监听 127.0.0.1:3000。不要为了配置 HTTPS 而让 Node.js 直接监听 443,除非项目明确需要由应用自行管理证书。

常见失败处理

Node.js 版本不匹配

如果出现 Unsupported engine、依赖安装失败或原生模块编译错误,先执行:

sudo -iu nuxtapp bash -lc '
source "$HOME/.nvm/nvm.sh"
node --version
npm --version
cd /srv/nuxt-app/current
npm pkg get engines
'

处理顺序如下:

  1. 读取项目 engines.node 要求。
  2. 使用对应的 Node.js 主版本。
  3. 保留原锁文件。
  4. 删除当前发布目录中的 node_modules 后重新执行 npm ci。
  5. 重新执行 npm run build。

不要通过 npm install --force 或忽略引擎检查来掩盖版本不兼容。

systemd 返回 203/EXEC

这通常表示 ExecStart 的 Node.js 路径错误,或者文件不可执行。检查:

sudo -iu nuxtapp bash -lc '
source "$HOME/.nvm/nvm.sh"
readlink -f "$(command -v node)"
'
sudo systemctl cat nuxt-app

将 unit 文件中的路径改为实际输出后执行:

sudo systemctl daemon-reload
sudo systemctl restart nuxt-app

Nginx 返回 502

按由外到内的顺序检查:

sudo systemctl status nginx --no-pager
sudo nginx -t
sudo systemctl status nuxt-app --no-pager
sudo ss -lntp | grep ':3000'
curl -I http://127.0.0.1:3000/
sudo tail -n 50 /var/log/nginx/error.log

不同结果的含义:

  • 本机 3000 访问失败:优先检查 Nuxt 服务和构建产物。
  • 本机 3000 成功,Nginx 报 502:检查 proxy_pass、端口和服务重启状态。
  • Nginx 本身未运行:检查配置语法和端口占用。
  • 外部域名无法连接但本机正常:检查 DNS、安全组和服务器防火墙。

环境变量修改后没有生效

确认环境文件权限和内容:

sudo stat /etc/nuxt-app.env
sudo grep -E '^(NODE_ENV|NITRO_HOST|NITRO_PORT|NUXT_PUBLIC_)' \
  /etc/nuxt-app.env

不要使用 cat 直接打印包含密钥的完整环境文件。修改后必须重启:

sudo systemctl restart nuxt-app
sudo journalctl -u nuxt-app -n 50 --no-pager

如果变量是构建阶段读取的,而不是通过 runtimeConfig 读取,则还需要重新执行构建。

端口被其他进程占用

sudo ss -lntp | grep ':3000'

如果 3000 已被其他服务使用,可以将环境文件中的端口改为 3001:

NITRO_PORT=3001

同时修改 Nginx:

proxy_pass http://127.0.0.1:3001;

然后分别执行:

sudo nginx -t
sudo systemctl restart nuxt-app
sudo systemctl reload nginx

端口修改会影响当前请求转发,适合在首次部署或维护窗口执行;不要只改其中一侧。

结果检查

部署完成后,可以按下表逐项验证:

检查对象验证命令或方式合格表现
Node.js 版本node --version、检查 systemd ExecStart命令行版本与服务使用版本一致
Nuxt 构建产物test -f /srv/nuxt-app/current/.output/server/index.mjs命令无输出且退出码为 0
systemd 服务systemctl is-active nuxt-app输出 active
本机应用curl -I http://127.0.0.1:3000/返回应用预期的 200 或业务允许的 3xx
监听范围ss -lntp | grep ':3000'优先显示 127.0.0.1:3000
Nginx 配置nginx -t显示 syntax is ok 和 test is successful
HTTP 入口curl -I http://app.example.com/返回预期状态码或跳转到 HTTPS
HTTPS 入口curl -I https://app.example.com/证书有效,页面返回正常
日志journalctl -u nuxt-app、Nginx error log无持续重启、端口或模块错误
外部端口云安全组检查对公网开放 80/443,3000 未开放

回滚方案

发布新版本前,记录当前版本:

sudo readlink -f /srv/nuxt-app/current

如果新版本已经切换但出现页面错误,可以先保留故障版本日志,再选择上一版本目录:

sudo ls -1dt /srv/nuxt-app/releases/*

将 PREVIOUS_RELEASE 替换为已确认可用的旧目录:

PREVIOUS_RELEASE="/srv/nuxt-app/releases/20250308-120000"

sudo -iu nuxtapp ln -s "$PREVIOUS_RELEASE" \
  /srv/nuxt-app/current.rollback

sudo -iu nuxtapp mv -Tf \
  /srv/nuxt-app/current.rollback \
  /srv/nuxt-app/current

sudo systemctl restart nuxt-app
curl -I http://127.0.0.1:3000/

确认本机访问恢复后,再检查公网入口:

curl -I https://app.example.com/
sudo journalctl -u nuxt-app -n 50 --no-pager

如果问题来自 Nginx 配置而不是 Nuxt 版本,使用部署前的备份恢复前应再次保留当前文件,并执行配置检查:

sudo cp -a /etc/nginx/sites-available/nuxt-app \
  /etc/nginx/sites-available/nuxt-app.failed

sudo cp -a /etc/nginx/sites-available/nuxt-app.bak.YYYYMMDD-HHMMSS \
  /etc/nginx/sites-available/nuxt-app

sudo nginx -t
sudo systemctl reload nginx

覆盖配置前应确认备份文件名和内容,避免将其他站点的配置误写入当前服务。回滚完成后,不要立即删除故障发布目录;至少保留其构建产物和 systemd 日志,待确认问题原因后再清理。

验收时重点确认:

  • Node.js 主版本符合项目 engines 要求。
  • systemd 使用的是实际 Node.js 绝对路径。
  • .output/server/index.mjs 存在并能被服务启动。
  • Nuxt 仅监听本机端口,3000 没有对公网开放。
  • Nginx 能将域名请求转发到 Nuxt。
  • DNS、HTTPS 证书和 HTTP 跳转均正常。
  • /etc/nuxt-app.env 权限为 600,私有变量未进入客户端配置。
  • 新版本异常时,旧版本软链接、环境文件和 Nginx 配置均可恢复。

本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/4310.html

相关推荐