Nuxt 4应用部署在香港服务器,Node.js版本与生产入口怎么配
在香港服务器上首次上线 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
写入以下内容:

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
'
处理顺序如下:
- 读取项目
engines.node要求。 - 使用对应的 Node.js 主版本。
- 保留原锁文件。
- 删除当前发布目录中的
node_modules后重新执行npm ci。 - 重新执行
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



