跳到正文
零到全栈 · 卷 4 · 从页面到应用

两种上线方式

本合集目录
本章目录

单册说明:本文件是卷 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=,而静态文件不可能为"任意查询串"各生成一份。两个选择:

  1. 放弃静态导出,用常驻;
  2. 把筛选挪到客户端:服务端只发全部摘录,浏览器根据 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 会回到这一点。

现在做本章最关键的一次对照实验:

  1. 打开 /notes/n1,记下标题;
  2. 改 data/notes.json 里 n1 的标题;
  3. 刷新,标题变了——因为页面是动态的,每次请求都重新读文件;
  4. 回到静态版本,同样的操作,标题不变,必须重新 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、让前后端第一次握手。

→ 卷5-01-API是什么.md