香港服务器部署Next.js网站,如何区分静态导出与Node运行模式?
上线后的目标状态应当很明确:域名通过 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 无法正常获取上游响应。依次检查:

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



