两种上线方式
本合集目录
本章目录
单册说明:本文件是卷 4 的第 8 章,可独立阅读。前置:第 7 章(数据层与缓存)。本章把同一份代码用两种方式构建、启动、对比,给出"什么时候选哪种"的判断依据。服务器配置的细节留到卷 7。
| 项 | 内容 |
|---|---|
| 所属卷 | 卷 4 · React 与 Next.js(第 8 / 8 章) |
| 前置章节 | 4.7 数据获取、缓存与环境变量 |
| 本章产出 | 一次 out/ 静态导出 + 一次 next start 常驻运行 + 一张能力对照表 |
| 对应代码 | next.config.mjs、components/NotesBrowser.jsx、app/notes/page.js |
| 配图 | 无(后续统一制图) |
| 读完的判定 | 能看着需求说出该选哪种方式,并说出被放弃的那个能力是什么 |
4.8.1 一句话结论:一个"每次现算",一个"一次算好发给大家"
两种方式的差别,可以压缩成一句:
next start:服务器上有个 Node 进程,每个请求来了现算;output: 'export':构建时把每个页面算成一份 HTML,之后只发文件,没有进程。
先看最常见的翻车。你按某篇帖子在 next.config.mjs 里加了一行 output: 'export',然后 npm run build:
Error: Page "/notes/[id]" is missing "generateStaticParams()" so it cannot be used with "output: export" config.
原因不难理解:静态导出要"提前把每个页面都生成出来",可 /notes/[id] 的 id 可能是任意值,构建时它不知道要生成几份。你必须把可能的取值列出来。
这一行报错,就是两种方式的根本区别:常驻进程能处理"请求来了才知道参数"的情况,静态文件不能。
4.8.2 原理与方法
产物长什么样
| 常驻 Node | 静态导出 | |
|---|---|---|
| 构建命令 | next build |
next build(配置 output: 'export') |
| 产物目录 | .next/ |
out/ |
| 还需要什么 | node_modules + package.json |
什么都不需要 |
| 启动方式 | next start -p 3000 |
任意静态服务器指向 out/ |
| 进程 | 必须有,且要守护 | 没有 |
.next/ out/
├─ BUILD_ID ├─ index.html
├─ server/app/ ├─ notes/index.html
├─ static/chunks/ ├─ notes/n1/index.html
└─ package.json 快照 └─ _next/static/
.next/ 里是"怎么渲染"的代码和数据,必须由 Node 执行;out/ 里是"已经渲染好的结果",浏览器直接读。
能力对照:先看你会失去什么
这张表是全章的核心。左边是你想要的能力,右边是它在两种方式下还成不成立。
| 能力 | next start |
output: 'export' |
|---|---|---|
| 静态页面 | 支持 | 支持 |
动态路由 /notes/[id] |
任意 id | 必须用 generateStaticParams 枚举 |
| 服务端取数 | 每次请求都能执行 | 只在构建时执行一次 |
读 cookies() / headers() |
支持 | 不支持(构建时没有请求) |
依赖 searchParams 的页面 |
支持 | 不支持(除非改成客户端处理) |
ISR(revalidate 定时刷新) |
支持 | 不支持,没有进程去刷新 |
| Route Handlers(自己写 API) | 支持,含 POST | 只支持静态的 GET |
| 中间件 Middleware | 支持 | 不支持 |
next/image 优化 |
支持 | 需要 images.unoptimized: true |
| 首字节速度 | 进程算完再发 | 直接读文件,最快 |
| 服务器要求 | 1 核 1G 起,要守护进程 | 对象存储 / CDN 即可 |
| 月成本 | 一台服务器 | 几乎为零 |
| 回滚 | 换回上一版 .next 并重启 |
换回上一版 out/ 目录 |
| 新增一条数据 | 刷新即可见(动态渲染时) | 必须重新构建、重新上传 |
最后一行值得停一下。静态导出不是"部署一次就完事",它把"数据更新"变成了"重新发布"。内容一周改一次没问题,一天改十次就是灾难。
一句话说清 Nginx 的差别
| 方式 | 配置 | 谁在处理请求 |
|---|---|---|
| 反代 | proxy_pass http://127.0.0.1:3000; |
Nginx 转给 Node,Node 现算 |
| 静态 | root /var/www/dudao/out; |
Nginx 直接读磁盘,Node 不在场 |
反代模式下,Nginx 是"前台",Node 是"后台";静态模式下,根本没有后台。所以静态站挂了,通常只是文件权限或路径问题;反代站挂了,第一反应应该是"Node 进程还在吗"(502 就是它不在了)。
卷 7 会把缓冲、超时、头透传、gzip、HTTPS 全部配一遍。这一章只需要记住这两行的分工。
决策表
| 你的情况 | 选 | 理由 |
|---|---|---|
| 要登录、要按用户显示不同内容 | 常驻 | 需要 cookies() 和每次请求渲染 |
| 内容每天多次更新 | 常驻 | 静态导出每次都要重新构建 |
| 纯展示、内容一周一改 | 静态 | 便宜、快、几乎没有运维 |
| 只有对象存储,没有服务器 | 静态 | 这是唯一可行的选项 |
| 需要 ISR、中间件、POST 接口 | 常驻 | 这些能力静态导出都没有 |
| 想先上线,之后再演进 | 静态起步 | 迁到常驻只是加一个进程,代码不用重写 |
| 流量很大、内容稳定 | 静态 + CDN | 静态文件放 CDN 是最省的方案 |
一个容易忽略的点:从静态迁到常驻很容易,反过来很难。 因为常驻版本可能已经用上了 cookies、ISR、Route Handlers,这些在静态导出里都要重写。所以"先静态、后常驻"是安全的路径,反过来不是。
成本、回滚与团队
成本不用背具体数字,记量级:静态站可以放在对象存储加 CDN 上,流量再大也基本是"按量付费的零头";常驻站至少要一台 1 核 1G 的服务器,还要算上你花在守护进程、日志、证书续期上的时间。服务器便宜,运维时间贵。
回滚也不一样。静态:把上一版 out/ 目录换回来,秒级完成,甚至可以两个目录轮流指。常驻:换回上一版 .next/ 再重启进程,中间有几秒不可用,而且要保证上一版的 node_modules 还在。卷 7 会把这两套写成脚本。
还有一个常被忽略的维度:接手的人。静态产物是一堆文件,谁都能部署;常驻站要求接手的人会看进程、会读日志、会重启服务。如果这个项目半年后可能交给别人,静态的长期维护成本更低。
动态路由必须枚举
export async function generateStaticParams() {
const notes = await getNotes();
return notes.map((n) => ({ id: String(n.id) }));
}
这个函数在构建时执行一次,返回所有可能的参数组合。Next 会为每一个组合生成一份 HTML。
它的限制是本质性的:构建时不存在的 id,导不出来。 你今天新增一条摘录,用户访问 /notes/n4 会得到 404,直到你重新构建。这不是 bug,是静态的定义。
顺带说 trailingSlash:
| 配置 | /notes/n1 的产物 |
对服务器的要求 |
|---|---|---|
trailingSlash: false(默认) |
out/notes/n1.html |
try_files 要带 $uri.html |
trailingSlash: true |
out/notes/n1/index.html |
try_files $uri $uri/ 就够,目录自动找 index |
静态导出时建议开 true,少一类路径问题。
4.8.3 动手:两次构建,一次对比
第一步:静态导出(会遇到两个真实的坎)
先改 next.config.mjs:
/** @type {import('next').NextConfig} */
const nextConfig = {
output: 'export',
trailingSlash: true,
images: { unoptimized: true },
};
export default nextConfig;
再把 app/page.js 里的 export const revalidate = 60; 删掉。静态导出没有服务端去定时重算,ISR 在这套模式下不被支持,留着它构建会直接失败。
npm run build。第一个坎来了:
Error: Page "/notes/[id]" is missing "generateStaticParams()" so it cannot be used with "output: export" config.
在 app/notes/[id]/page.js 里补上(它必须和 page.js 在同一个文件里导出,同时把 getNotes 加进已有的 import):
import { getNote, getNotes } from '@/lib/notes';
export async function generateStaticParams() {
const notes = await getNotes();
return notes.map((n) => ({ id: String(n.id) }));
}
再 build。第二个坎:
Error: Page "/notes" cannot be rendered statically because it uses `searchParams`.
这是 4.7 埋下的伏笔:/notes 读了 ?tag=,而静态文件不可能为"任意查询串"各生成一份。两个选择:
- 放弃静态导出,用常驻;
- 把筛选挪到客户端:服务端只发全部摘录,浏览器根据 URL 自己过滤。
这一章两个都要试,所以先走第 2 条。改 app/notes/page.js:
import { Suspense } from 'react';
import { getNotes, getTags } from '@/lib/notes';
import NotesBrowser from '@/components/NotesBrowser';
export default async function NotesPage() {
const [notes, tags] = await Promise.all([getNotes(), getTags()]);
return (
<>
<h1>摘录</h1>
<Suspense fallback={<p className="hint">加载中…</p>}>
<NotesBrowser notes={notes} tags={tags} />
</Suspense>
</>
);
}
components/NotesBrowser.jsx:
'use client';
import Link from 'next/link';
import { useSearchParams } from 'next/navigation';
import NoteList from './NoteList';
export default function NotesBrowser({ notes, tags }) {
const searchParams = useSearchParams();
const activeTag = searchParams.get('tag') ?? 'all';
const visible = activeTag === 'all'
? notes
: notes.filter((n) => n.tags.includes(activeTag));
return (
<>
<nav className="filters">
<Link href="/notes/" className={activeTag === 'all' ? 'active' : ''}>全部</Link>
{tags.map((tag) => (
<Link
key={tag}
href={`/notes/?tag=${encodeURIComponent(tag)}`}
className={activeTag === tag ? 'active' : ''}
>
{tag}
</Link>
))}
</nav>
<NoteList notes={visible} />
</>
);
}
Suspense 不是可选项。少了它,构建会直接失败:
useSearchParams() should be wrapped in a suspense boundary at page "/notes".
因为 useSearchParams 在预渲染时拿不到查询串,Next 要求你提供一个 fallback,好在客户端补上这段内容。
再 build,这次通过。out/ 出现了,检查结构:
ls out
ls out/notes
ls out/notes/n1
你会看到 out/index.html、out/notes/index.html、out/notes/n1/index.html。每个 URL 都对应一个真实文件——这就是"静态"。
起一个静态服务器(不装任何东西):
py -m http.server 4000 -d out # Windows
python3 -m http.server 4000 -d out # macOS / Linux
打开 http://127.0.0.1:4000/,点进列表、点进详情、切换标签、按 F5。全部正常。
注意此时没有任何 Node 进程:http.server 只是把磁盘上的文件读出来发给你。关掉它,页面就打不开了;但只要有任意一个静态服务器指向 out/,它就能跑。
第二步:常驻 Node
把 next.config.mjs 改回去:
/** @type {import('next').NextConfig} */
const nextConfig = {};
export default nextConfig;
同时把 /notes 改回 4.7 的服务端筛选(searchParams 版本),删掉 NotesBrowser 的引用;把 app/notes/[id]/page.js 里的 generateStaticParams 删掉——它是为静态导出加的,留着会把详情页在构建时定死;再把首页的 export const revalidate = 60; 加回去。这一步是为了让你看到"常驻模式不需要为静态导出做妥协"。
npm run build
npm start
npm start 跑的是 next build 写进 package.json 的 next start,默认端口 3000。
这里先埋一个钉子:常驻服务要和 Nginx 配合时,更安全的做法是只监听回环地址——next start -H 127.0.0.1 -p 3000,让外部只能通过 Nginx 进来。图省事监听所有网卡,等于把 3000 端口直接暴露在公网,绕过 HTTPS、限流和你后面要加的一切。卷 7 会回到这一点。
现在做本章最关键的一次对照实验:
- 打开
/notes/n1,记下标题; - 改
data/notes.json里 n1 的标题; - 刷新,标题变了——因为页面是动态的,每次请求都重新读文件;
- 回到静态版本,同样的操作,标题不变,必须重新
npm run build。
同一个改动,两种命运。这就是"每次现算"和"一次算好"的差别,比任何定义都直观。
第三步:自己填一张对比表
| 观察项 | out/ 静态 |
next start |
|---|---|---|
| 有没有常驻进程 | 没有 | 有 |
| 改数据后是否立刻生效 | 否,要重新 build | 是(动态渲染时) |
直接访问 /notes/n1 |
命中一个 html 文件 | Node 渲染 |
| 关掉服务后 | 文件还在,换个服务器就能跑 | 进程没了,502 |
| 产物大小 | 只有 HTML/CSS/JS | 加上 Node 依赖,大一个量级 |
4.8.4 三个坑
坑一:双击 out/index.html 打开,一片白
症状:文件管理器里双击 out/index.html,浏览器地址是 file:///.../out/index.html,页面空白,Console 里一堆 404,资源路径长得像 file:///_next/static/...。
成因:构建产物的资源引用是绝对路径 /_next/...。浏览器在 file:// 协议下会把它解析成盘符根目录,而不是 out/ 目录。另外 file:// 下模块加载、fetch 都受限制。
修法:静态产物必须由 HTTP 服务器提供,不能双击打开。用 py -m http.server -d out 起一个,或者直接部署到 Nginx。这不是配置问题,是协议问题——file:// 本来就不是给应用用的。
坑二:只把 .next 拷到服务器,启动报 next: not found
症状:本地 npm start 正常,传到服务器后执行 npm start:
sh: 1: next: not found
成因:next 命令来自 node_modules/.bin。只拷 .next 目录,没有 package.json 和依赖,自然找不到命令。另一种情况是拷了 package.json 但没执行 npm ci。
修法:服务器上要有完整的项目(package.json、package-lock.json、源码、public/),执行 npm ci && npm run build && npm start。想让产物自带运行时,用 output: 'standalone',它会把需要的 node_modules 裁好放进 .next/standalone,拷过去直接 node server.js——这是卷 7 部署时的推荐做法。
坑三:静态站子路由 404,try_files 少了一段
症状:静态站首页能开,/notes/ 能开,但 /notes/n1/ 404;或者反过来,只有带斜杠的能开。
成因:trailingSlash 与 try_files 不匹配。关掉 trailingSlash 时产物是 notes/n1.html,Nginx 默认只找文件与目录,不会自动补 .html;开着时产物是 notes/n1/index.html,但请求少了尾斜杠就会先 301 再找目录。
修法:两处对齐。开了 trailingSlash,用 try_files $uri $uri/ =404;;没开,用 try_files $uri $uri.html $uri/ =404;。不要两套混用,也不要指望 Nginx 猜。
本章验收
- 亲手撞到
generateStaticParams与searchParams两个构建错误,并各自修好 - 用
http.server跑起out/,关掉 Node 也能访问 - 用
next start跑起同一份代码,改数据后刷新即可见 - 能说出静态导出下"新增一条数据"要付出什么代价
- 能默写两种 Nginx 配置的差别(一行即可)
自测
Q1:为什么静态导出不支持 ISR?
看答案
ISR 的原理是"页面过期后,由服务器在后台重新生成一份"。它需要一个常驻的运行时来接收请求、判断是否过期、触发重算并替换缓存。静态导出之后只有一堆文件,没有任何进程在跑,没人负责重算,所以这个能力不存在。要更新只能重新构建。Q2:一个站要登录才能看自己的收藏,能用静态导出吗?
看答案
不能直接用。登录态在 cookie 里,页面内容因人而异,这是 cookies() 和动态渲染的典型场景,静态导出在构建时拿不到请求,也就拿不到用户身份。可行的折中是:公开部分静态导出,个人中心放在一个独立的常驻服务里,用子路径或子域名分开部署。Q3:为什么说"先静态、后常驻"是安全路径,反过来不是?
看答案
静态版本只用到了"页面 + 客户端交互",迁到常驻只是加一个 Node 进程,代码基本不动。而常驻版本往往已经用上了 cookies、ISR、Route Handlers、中间件,这些能力在静态导出里没有对应物,回退时要重写页面、改数据流,甚至改产品形态。所以演进方向应该是单向的。下一步
卷 4 到此收口:你的「读到」有了组件、状态、路由、服务端渲染和两种上线形态,但数据仍然是本地文件,也没有"用户"这个概念。卷 5 开始动真格——设计接口、写 FastAPI、让前后端第一次握手。