香港服务器部署Next.js网站,如何区分静态导出与Node运行模式?

发布人:A5数据发布时间:2026-10-12 10:07阅读量:125

上线后的目标状态应当很明确:域名通过 HTTPS 访问香港服务器,Nginx 接收公网请求;如果项目采用静态导出,Nginx 直接读取 out 目录,不需要运行 Node.js 进程;如果项目依赖服务端渲染、登录会话或动态接口,则由 Node.js 运行 Next.js,Nginx 将请求转发到本机应用端口。两种模式可以使用同一台服务器,但构建产物、启动方式和验收标准不同。

准备条件:先决定服务器应该运行什么配图

区分它们不能只看“页面是否看起来是静态的”,也不能看到 .next 目录就认定需要启动服务。应当先检查项目使用的功能和 next.config 配置,再选择部署路径。以下操作以 Ubuntu 24.04 LTS、Nginx、systemd 和与项目兼容的 Node.js 22.x 为环境,分别完成静态导出和 Node 运行模式的上线。

一、准备条件:先决定服务器应该运行什么

1. 用功能需求判断部署模式

静态导出是把网站构建为可直接分发的 HTML、JavaScript、CSS 等文件;Node 运行模式则保留 Next.js 服务端,允许在收到请求后执行服务端逻辑。

核对内容静态导出Node 运行模式
典型用途企业展示站、文档站、构建时生成的内容页面登录系统、个性化页面、动态业务网站
配置与产物配置 output: 'export',通常生成 out/默认构建生成 .next/,本文使用 next start
生产启动方式Nginx 读取静态文件Node.js 进程运行 Next.js
请求时服务端渲染不支持支持
接口处理可以调用独立后端;自身不能提供请求时动态接口可以运行 API Routes、动态 Route Handlers 等
图片优化通常使用外部优化服务,或关闭内置优化可以使用 Next.js 默认图片优化服务
内容更新更新内容后重新构建、发布可按项目设计采用动态渲染或缓存更新

判断时重点检查以下条件:

  • 页面是否需要在服务器上读取当前用户的 Cookie、会话或请求头。
  • 是否使用 getServerSideProps、Server Actions,或需要请求时执行的接口。
  • 动态路由是否能够在构建时列出全部路径。
  • 是否依赖 ISR、请求时重定向、运行时中间件等服务端能力。
  • 图片是否依赖 Next.js 默认的服务端优化功能。

存在上述服务端依赖时,不要为了简化部署强行使用静态导出。构建时无法确定的动态路径,也不能靠 Nginx 的回退规则补出来。

另一方面,使用 App Router、Server Components 或动态路由,并不自动意味着必须运行 Node.js。只要相关页面能够在构建时完成渲染,并满足静态导出的限制,仍然可以导出。最终应以配置、构建结果和业务行为共同判断。

2. 确认服务器与项目条件

本文约定以下目录:

/srv/nextsite/
├── source/                  # 待发布源码
├── releases/
│   ├── 20260701-120000/      # 示例版本目录
│   └── 20260702-120000/
└── current -> releases/某版本

current 是 Nginx 或 systemd 使用的当前版本入口。每次发布建立新目录,不直接覆盖线上目录,便于回滚。

上线前应准备:

  • 可通过 SSH 管理的 Ubuntu 24.04 LTS 香港服务器。
  • 一个已指向服务器公网地址的域名,本文用 site.example.com 占位。
  • 可信的项目源码、package.json 和 package-lock.json。
  • 已安装且与项目兼容的 Node.js 22.x、npm。
  • 云侧访问规则允许 TCP 80、443;SSH 管理端口保留可用。
  • Node 模式的 3000 端口仅用于本机访问,不开放公网。

Node.js 应通过可信软件源或校验过的发行包安装,并使用该版本线中经过安全维护的补丁版本。不要仅因为命令能够执行,就认为运行环境已经符合项目要求。

先核验:

lsb_release -ds
node --version
npm --version
command -v node
command -v npm

进入源码目录,检查项目声明:

cd /srv/nextsite/source
npm pkg get engines scripts

本文使用 npm;已有其他包管理器锁文件的项目,应沿用原来的包管理器,不要临时生成另一套依赖树。Next.js 和相关依赖也应使用已经检查过安全更新的版本。

香港服务器的位置不改变 Next.js 的部署机制,但会影响依赖下载、外部 API 和数据库访问。尤其是 Node 模式,服务器到数据库的延迟可能直接进入页面响应时间;静态导出则主要在构建阶段访问内容源。

A5数据提供中国香港物理服务器租用,覆盖入门建站、Xeon Gold与AMD EPYC等配置,配备SSD或NVMe存储,并提供CN2及国际带宽选择,可为Next.js静态站点分发、Node.js服务端运行,以及数据库、接口服务和多任务应用提供相应的计算、存储与网络资源基础。

3. 安装 Nginx并建立应用账户

以下命令需要管理员权限。安装 Nginx 可能启用默认监听;已有网站的服务器,应先检查端口与站点配置,不直接覆盖原配置。

sudo apt update
sudo apt install -y nginx ca-certificates curl

sudo adduser --system --group \
  --home /srv/nextsite \
  --shell /bin/bash nextsite

sudo install -d -o nextsite -g nextsite -m 0755 \
  /srv/nextsite/source \
  /srv/nextsite/releases

若 nextsite 用户或目录已经存在,先检查其用途,不重复修改。不要对整个 /srv 执行递归权限变更。

构建和运行使用 nextsite 账户,避免以 root 执行项目的 npm 脚本。上传源码时排除本地 node_modules、.next、out 和不应上传的密钥文件。

二、分步操作:共用发布目录,分开配置运行方式

1. 建立新版本并安装依赖

切换到应用账户:

sudo -u nextsite -H bash

以下发布命令在这个 shell 中连续执行:

set -e

REL=$(date +%Y%m%d-%H%M%S)
RELEASE="/srv/nextsite/releases/$REL"

install -d "$RELEASE"
cp -a /srv/nextsite/source/. "$RELEASE"/
cd "$RELEASE"

npm ci
node -p "require('next/package.json').version"

npm ci 按锁文件安装依赖。若它报告锁文件不一致,应在开发环境修正并重新提交,不要在生产服务器临时改成 npm install 来绕过问题。

构建阶段通常需要开发依赖,因此不要预先使用 npm ci --omit=dev。首次上线可保留完整依赖,后续再验证能否裁剪。

2. 分支 A:构建静态导出版本

在项目现有配置中合并以下设置,不要直接覆盖已有配置文件。下面以 next.config.mjs 为例:

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export',
  trailingSlash: true,
  images: {
    unoptimized: true,
  },
};

export default nextConfig;

三个配置分别表示:

  • output: 'export':构建时生成静态导出文件。
  • trailingSlash: true:让页面通常以目录中的 index.html 形式输出,便于 Nginx 按目录访问。
  • images.unoptimized: true:不使用需要 Next.js 服务端的默认图片优化。

已有外部图片优化方案时,应按项目方案配置,不必统一关闭所有图片处理。

执行构建和产物检查:

npm run build
test -d out
find out -maxdepth 2 -type f | head -n 20

查看首页以及一个真实的内部页面。例如项目有 /about/,应能在导出目录找到对应页面:

test -f out/index.html
test -f out/about/index.html

第二条命令只适用于确实存在 /about/ 的项目,应替换成自己的路由。

构建成功并不代表所有业务功能都可用。静态站点中的表单、登录或数据查询若调用独立后端,仍需检查接口地址、跨域策略和认证方式。

3. 分支 B:构建 Node 运行版本

Node 模式不要保留 output: 'export'。本文也不采用 output: 'standalone',因为 standalone 需要另一套产物整理和启动方式,不能与这里的 next start 步骤混用。

常规脚本可以是:

{
  "scripts": {
    "build": "next build",
    "start": "next start"
  }
}

保留项目原有且确有需要的其他脚本,然后执行:

npm run build
test -f .next/BUILD_ID
test -f node_modules/next/dist/bin/next

此模式需要保留完整的应用运行目录,包括 .next、public、必要配置和依赖。不要只复制 .next/static,也不要只复制首页 HTML。

环境变量还要区分两个阶段:

  • NEXT_PUBLIC_* 通常在构建时写入客户端代码,修改后需要重新构建。
  • 服务端变量可以在运行时提供,但若构建阶段也读取它们,就必须在构建时安全注入。

数据库密码、令牌等不能写入 NEXT_PUBLIC_*。不要把生产密钥提交到源码仓库,也不要通过日志输出环境变量全文。

4. 切换当前版本入口

无论选择哪种模式,完成构建后再切换 current。首次上线前确认:current 如果存在,必须是符号链接,不是正在使用的实体目录。

以下操作会改变网站文件入口。旧目录不会被删除,但 Node 模式还需要重启进程才能真正载入新代码。单次发布期间不要并行执行另一轮切换。

继续在应用账户的 shell 中执行:

if [ -L /srv/nextsite/current ]; then
  readlink -f /srv/nextsite/current > "$RELEASE/previous-path.txt"
elif [ -e /srv/nextsite/current ]; then
  echo "current 不是符号链接,停止发布"
  exit 1
fi

ln -s "$RELEASE" "/srv/nextsite/.current-$REL"
mv -Tf "/srv/nextsite/.current-$REL" /srv/nextsite/current

临时链接和正式链接位于同一文件系统,重命名可避免先删旧链接再建新链接造成的空窗。但它不等于整个发布过程无中断,Node 进程重启、旧客户端资源请求仍需另外考虑。

记录本次 RELEASE 路径,然后退出应用账户:

printf '本次版本:%s\n' "$RELEASE"
exit

5. 为 Node 模式建立 systemd 服务

静态导出跳过本步骤。

先建立运行时环境文件。若文件已存在,应备份后编辑,不能覆盖:

sudo install -d -m 0750 /etc/nextsite

if ! sudo test -e /etc/nextsite/runtime.env; then
  sudo install -m 0600 /dev/null /etc/nextsite/runtime.env
fi

sudoedit /etc/nextsite/runtime.env

内容示例:

NODE_ENV=production

业务需要的服务端变量可另行加入。此文件由 systemd 读取,不是 shell 脚本,不要混入 shell 命令。

创建 /etc/systemd/system/nextsite.service:

[Unit]
Description=Next.js website
After=network.target

[Service]
Type=simple
User=nextsite
Group=nextsite
WorkingDirectory=/srv/nextsite/current
Environment="PATH=/usr/local/bin:/usr/bin:/bin"
EnvironmentFile=/etc/nextsite/runtime.env
ExecStart=/usr/bin/env node /srv/nextsite/current/node_modules/next/dist/bin/next start --hostname 127.0.0.1 --port 3000
Restart=on-failure
RestartSec=5
TimeoutStopSec=30
UMask=0027

[Install]
WantedBy=multi-user.target

构建和运行必须解析到同一套兼容的 Node.js。若 Node 安装在其他目录,应明确调整 PATH,不要依赖交互式 shell 的版本管理器初始化。

启动并核验:

sudo systemctl daemon-reload
sudo systemctl enable nextsite
sudo systemctl restart nextsite
sudo systemctl status nextsite --no-pager

curl -I http://127.0.0.1:3000/
sudo ss -lntp | grep ':3000'

监听地址应为 127.0.0.1:3000。后续发布执行 restart 会造成短暂服务中断,应安排发布窗口;本文的单实例流程不承诺无中断切换。

6. 配置 Nginx:二选一,不混用

配置文件统一使用 /etc/nginx/sites-available/nextsite.conf。若它已经存在,先保存副本:

sudo install -d -m 0700 /var/backups/nextsite

if sudo test -e /etc/nginx/sites-available/nextsite.conf; then
  sudo cp -a /etc/nginx/sites-available/nextsite.conf \
    "/var/backups/nextsite/nextsite.conf.$(date +%Y%m%d-%H%M%S)"
fi

备份路径应记录到发布记录中。本次修改只针对该站点,不删除其他站点或默认配置。

静态导出配置:

server {
    listen 80;
    server_name site.example.com;

    root /srv/nextsite/current/out;
    index index.html;

    access_log /var/log/nginx/nextsite.access.log;
    error_log /var/log/nginx/nextsite.error.log;

    location / {
        try_files $uri $uri/ =404;
    }

    error_page 404 /404.html;

    location = /404.html {
        internal;
    }
}

此配置与前面的 trailingSlash: true 对应。不要随意使用 try_files $uri /index.html:那是常见的单页应用回退方式,可能把不存在的 Next.js 页面错误地返回为首页,并掩盖真实的 404。

Node 运行配置:

server {
    listen 80;
    server_name site.example.com;

    access_log /var/log/nginx/nextsite.access.log;
    error_log /var/log/nginx/nextsite.error.log;

    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_buffering off;
    }
}

关闭响应缓冲有利于流式响应及时传给客户端。这里没有启用 Nginx 页面缓存,避免把登录用户或个性化内容误缓存为共享页面。

保存所选配置后,首次上线建立站点链接:

sudo ln -s /etc/nginx/sites-available/nextsite.conf \
  /etc/nginx/sites-enabled/nextsite.conf

sudo nginx -t
sudo systemctl reload nginx

如果链接已经存在,先检查目标,不重复创建。只有 nginx -t 成功才执行 reload;失败时修正或恢复配置,现有 Nginx 进程通常仍使用旧配置。

7. 完成 HTTPS

先把所有示例域名替换为自己控制的真实域名,并确认 DNS 已生效。配置了 AAAA 记录时,IPv6 也必须能够到达服务器,否则部分访问和证书验证可能失败。

可通过 Certbot 的 Nginx 插件申请证书:

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d site.example.com
sudo certbot renew --dry-run

运行前备份站点配置,因为插件会调整 TLS 和跳转配置。申请失败时先保留可用配置,按验证提示检查 DNS、80 端口与域名归属,不要反复改动整套网络规则。

HTTPS 完成后,再备份一次最终配置,作为之后发布和回滚的基线。不要为了回滚应用代码而退回不加密的 HTTP。

三、结果验证:页面能打开只是第一项

先在服务器验证 Nginx,再从外部网络验证域名:

curl -I -H 'Host: site.example.com' http://127.0.0.1/
curl -I https://site.example.com/

HTTP 返回跳转到 HTTPS、HTTPS 返回正常页面,才说明入口链路基本成立。还应分别核验下面两组结果。

静态导出的验收

  • 首页和至少两个内部页面可以直接访问。
  • 在内部页面刷新浏览器,不会出现 Nginx 404。
  • 不存在的路径返回 404,而不是首页和 200。
  • 浏览器中 JavaScript、CSS、图片请求正常,没有 /_next/static/ 资源错误。
  • 独立后端接口可访问,登录或表单功能没有因跨域配置失败。

静态模式不需要 nextsite 服务处于运行状态,也不需要监听 3000 端口。若服务器原来运行过 Node 模式,确认没有其他站点使用该服务后,再停止旧服务。

Node 模式的验收

  • systemctl is-active nextsite 返回 active。
  • 3000 端口只监听回环地址。
  • 动态页面、登录态、接口和表单分别通过验证。
  • 图片优化功能若被使用,应检查相关图片请求。
  • 服务重启后可以恢复访问,日志没有持续崩溃或重启。

可查看近期运行日志:

sudo journalctl -u nextsite -n 100 --no-pager
sudo tail -n 50 /var/log/nginx/nextsite.error.log

验收应包含业务动作,不能只对首页执行一次 curl。例如登录后访问个人页面,确认不会看到其他用户内容;访问需要数据库的页面,确认实际查询路径正常。

四、失败处理:按公网入口、Nginx、应用顺序排查

域名超时,但服务器本机访问正常

先检查 DNS 是否指向正确地址,再检查云侧访问规则、系统防火墙和 IPv6。此时重装 Next.js 通常没有意义。

调整防火墙前应保存现有规则,并确认控制台或其他恢复通道可用。只放行网站确实需要的端口,不为排障把 3000 端口暴露到公网,也不要清空整套规则。

Nginx 返回 502

502 通常意味着 Nginx 无法正常获取上游响应。依次检查:

失败处理:按公网入口、Nginx、应用顺序排查配图

sudo systemctl status nextsite --no-pager
curl -I http://127.0.0.1:3000/
sudo journalctl -u nextsite -n 100 --no-pager
  • 本机 3000 也访问失败:检查服务启动、Node 路径、构建产物和运行时变量。
  • 本机 3000 正常,域名仍是 502:检查 Nginx 上游地址、端口和错误日志。
  • 进程反复退出:先处理应用错误,不要只缩短自动重启间隔。

静态页面返回 403 或深层页面 404

403 先检查目录权限和入口文件。Nginx 需要读取文件,并能够遍历父目录:

namei -l /srv/nextsite/current/out/index.html
sudo -u www-data test -r /srv/nextsite/current/out/index.html

不要用 chmod -R 777 解决权限问题。只修正受影响目录的读取、遍历权限,变更前记录原权限。

深层页面 404 则检查导出目录是否存在相应 HTML,以及 Nginx 路径规则是否与 trailingSlash 设置一致。不存在的动态路由应回到项目构建配置处理,不是给 Nginx 添加首页回退就能解决。

构建失败、卡住或进程被终止

先读错误输出,再看系统资源:

free -h
df -h /srv/nextsite
sudo journalctl -k -n 100 --no-pager

报静态导出不支持某项功能,应改用 Node 模式或调整功能;出现内存不足,应考虑在资源更充足的构建环境生成兼容产物,或增加构建资源。不要把关闭类型检查、忽略构建错误作为上线方案。

发布后资源 404,或环境变量没有更新

资源 404 可能由上传不完整、旧浏览器引用旧版本文件或缓存策略不当引起。检查构建产物和浏览器请求,不要仅刷新首页就判定恢复。

若修改的是 NEXT_PUBLIC_*,需要重新构建;若修改的是纯运行时服务端变量,需要重启服务,并确认该变量没有在构建阶段被固化。

五、回滚:恢复上一版文件,也恢复对应运行方式

回滚的前提是保留上一版完整目录,并记录当时的 Nginx 配置、环境变量和启动模式。若发布涉及数据库迁移,代码回滚不一定能撤销数据库变化,应先确认旧版本与当前数据结构兼容。

以下命令以应用账户执行,只把 current 指回上一版,不删除新版本:

sudo -u nextsite -H bash
set -e

CURRENT=$(readlink -f /srv/nextsite/current)
OLD=$(cat "$CURRENT/previous-path.txt")

case "$OLD" in
  /srv/nextsite/releases/*) ;;
  *) echo "上一版路径不符合约定,停止回滚"; exit 1 ;;
esac

test -d "$OLD"

ROLLBACK_LINK="/srv/nextsite/.rollback-$(date +%Y%m%d-%H%M%S)"
ln -s "$OLD" "$ROLLBACK_LINK"
mv -Tf "$ROLLBACK_LINK" /srv/nextsite/current

exit

首次上线没有上一版记录时,不能执行这组回滚命令。

随后按旧版本模式处理:

回滚:恢复上一版文件,也恢复对应运行方式配图

  • 静态导出回滚:同一配置下通常无需重启 Nginx,但应重新检查页面和资源。
  • Node 模式回滚:执行 sudo systemctl restart nextsite,检查日志和动态功能。
  • 跨模式回滚:同时恢复对应的 Nginx 配置和服务状态;先建立可用上游,再切换转发配置。

恢复 Nginx 配置前,先备份当前文件,再把发布记录中的明确备份路径复制回去。执行 sudo nginx -t 成功后才 reload。不要用通配符盲目选择某个备份,也不要把已经启用的 HTTPS 意外撤销。

旧版本目录不要在刚上线后立即清理。应至少覆盖既定观察与回滚窗口,并考虑仍在访问网站的客户端可能继续请求上一版静态资源。

上线验收检查清单

  • [ ] 已根据请求时服务端能力选择模式,而不是只看页面外观。
  • [ ] 静态模式存在完整 out/;Node 模式存在完整构建产物与依赖。
  • [ ] Node.js、Next.js 和依赖版本兼容,并已检查相关安全更新。
  • [ ] 构建和运行使用非 root 账户,生产密钥没有进入客户端代码。
  • [ ] 域名、IPv4/IPv6、80/443 端口与 HTTPS 均已验证。
  • [ ] Node 模式只监听本机 3000 端口,由 systemd 管理。
  • [ ] 首页、内部页面刷新、404、静态资源和业务接口分别通过验收。
  • [ ] 已验证登录态、图片和外部数据源等实际使用的功能。
  • [ ] 当前版本、上一版路径和配置备份已经记录。
  • [ ] 回滚步骤与当前模式对应,不依赖临时重建旧版本。

静态导出的上线交付物是可由 Nginx 分发的文件;Node 模式的上线交付物则是能够持续运行、具备正确环境变量和依赖的 Next.js 服务。把这两个目标分清,部署、验收和回滚才会沿着同一条路径执行。

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

相关推荐