将 Next.js 部署到不同平台
了解哪些 Next.js 功能需要特定的平台能力,以及如何选择合适的部署目标。
Next.js 在组件层面将静态和动态内容视为一个连续体。该模型中的不同功能需要不同的平台能力。本页帮助你了解平台需要支持哪些能力,以及如何配置部署。
最低要求#
要运行 Next.js,你的平台只需要一个 Node.js 服务器。就这么简单。
单个 next start 进程就能正确处理每一项 Next.js 功能:Server Components、ISR、PPR、Cache Components、Server Actions、Proxy 和 after()。像 PPR 和 Server Components 这样的功能需要流式传输支持来逐步交付内容(没有它,响应会被缓冲并作为一个整体发送,这仍然可用,但会失去流式传输的性能优势)。额外的基础设施(CDN 缓存、边缘计算、共享缓存)主要用于提升性能和多实例一致性。在多实例部署中,共享缓存和标签协调可减少实例之间的陈旧数据分歧。唯一的额外依赖是 sharp 包,它是图片优化所必需的。
功能保真度与性能保真度#
在评估平台对 Next.js 的支持时,区分两个层次会有所帮助:
功能保真度意味着每一项 Next.js 功能都能正常工作。适配器测试套件就是契约:如果某个平台的适配器通过了测试,它就支持 Next.js。这是二元的:要么通过,要么不通过。
性能保真度意味着功能达到其最佳性能特征。例如 PPR 的静态外壳以 CDN 延迟而非源站延迟提供服务,或者 ISR 即时提供陈旧内容并在亚秒级传播重新验证。性能保真度是一个连续体,每个平台会根据其架构以不同方式实现。
达到功能保真度的平台就是 Next.js 完全支持的部署目标。性能保真度是平台之间拉开差距的地方,并且会随着时间的推移逐步提升。
请从这个角度看待下面的功能矩阵:"需要流式传输"和"推荐共享缓存"描述的是功能保真度所需的能力。"边缘拼接"是一种性能保真度优化。
功能支持矩阵#
不同功能需要不同的基础设施能力。"边缘拼接"一列是性能优化,而非正确性要求。所有功能都可以在单台源站服务器上正常工作。
| 功能 | 流式传输 | 共享缓存 | 边缘拼接 | 备注 |
|---|---|---|---|---|
| Server Components | 需要 | 否 | 否 | 基础流式传输支持 |
| ISR(基于时间) | 否 | 推荐 | 否 | 无需共享缓存即可按实例工作 |
| ISR(按需) | 否 | 推荐 | 否 | 多实例场景下标签传播需要共享缓存 |
| 部分预渲染 | 需要 | 推荐 | 可选 | 请参阅 PPR 平台指南 |
Cache Components (use cache) | 需要 | 推荐 | 否 | 共享缓存可实现跨实例一致性 |
| Proxy / Middleware | 否 | 否 | 否 | 运行在边缘或源站 |
| Server Actions | 需要 | 否 | 否 | 带流式响应的 POST 请求 |
after() | 否 | 否 | 否 | 需要优雅关闭支持 |
需要流式传输意味着平台必须支持分块传输编码或 HTTP/2 流式传输,并且不得在将响应发送给客户端之前对其进行缓冲。
推荐共享缓存意味着多个服务器实例可以从共享缓存后端进行协调中受益。对于 ISR 和服务器响应缓存,请使用 cacheHandler。对于 'use cache' 条目,请使用 cacheHandlers。没有共享缓存时,每个实例独立维护自己的缓存——功能在每个实例上仍然可以正常工作,但重新验证事件不会跨实例传播。
CDN 基础设施兼容性#
下表列出了每个主要 CDN 的基础设施原语。这些是可用的构建模块,而非现成的集成:
| CDN | 边缘计算 | 键值 / 标签 | Blob 存储 | PPR 恢复 |
|---|---|---|---|---|
| Cloudflare | Workers | KV | R2 | 是(worker) |
| Akamai | EdgeWorkers | EdgeKV | 对象存储 | 是(worker) |
| Amazon CloudFront | Lambda@Edge | KeyValueStore | S3 | 是(Lambda) |
| Fastly | Compute | KV Store | 对象存储 | 是(WASM) |
| Azure | Functions | 托管 Redis | Blob 存储 | 是(server) |
| Google Cloud | Cloud Run | 多种 KV | Cloud Storage | 是(server) |
这些是可用的构建模块,而非现成的集成。如今大多数社区适配器将 Next.js 部署为 Docker 容器或 Node.js 服务器,并未利用边缘 KV 或 PPR 恢复等 CDN 特有的原语。请参阅部署页面,了解当前的适配器列表。有关 CDN 特定的缓存注意事项(包括 Vary 对自定义标头的已知限制),请参阅 CDN 缓存。
适配器#
Next.js 提供了部署适配器 API,使平台能够针对其基础设施定制 Next.js 应用的构建和部署方式。适配器在构建时运行,从标准的 Next.js 构建产出特定平台的输出。任何人都可以使用公开 API 构建适配器,无需特殊权限。
适配器 API 加上 Next.js 缓存接口构成了完整的平台集成界面。适配器处理构建时输出,而 cacheHandler 和 cacheHandlers 涵盖不同的运行时缓存路径。cacheHandler(单数)涵盖服务器缓存路径,如 ISR、路由处理器、经过补丁的 fetch/unstable_cache 以及图片优化。cacheHandlers(复数)配置 'use cache' 指令的后端。
已验证的适配器#
已验证的适配器是指满足以下两个条件的适配器:
- 开源。 适配器源代码公开可用,以便社区和 Next.js 团队检查、贡献和验证它。
- 运行兼容性测试套件。 平台提供一种方式,针对其适配器运行完整的 Next.js 兼容性测试套件。这让人清楚地了解哪些功能可用、哪些正在进行中以及哪些地方仍有缺口。
已验证的适配器托管在 Next.js GitHub 组织下,在 Next.js 文档中列为受支持的部署目标,并由各自的平台团队维护。不存在私有的框架钩子或集成路径:Vercel 的适配器与其他所有适配器使用相同的公开 API。
对于已验证的适配器以及正通过生态系统工作组努力达成验证状态的平台,Next.js 团队承诺:
- 协同测试。 在重大版本发布之前,我们与平台团队合作运行兼容性测试套件,并尽早发现问题。
- 提前体验。 适配器作者可以在 RFC 和候选发布阶段提前获取 API 变更。
- 直接支持。 当适配器契约需要更新时,我们直接与适配器团队合作。
小知识: 平台可以在相同的公开 API 和测试套件上构建闭源适配器。但是,闭源适配器不会被列为已验证,因为 Next.js 团队无法验证其无法检查的内容。
关于基础设施要求的说明#
Next.js 的渲染模型将静态/动态边界放在组件层面,而不是路由层面。更细粒度的边界为开发者提供了更大的灵活性,代价是对托管平台提出更广泛的要求。这是一个深思熟虑的权衡:本页中的基础设施要求之所以存在,是因为渲染模型所带来的能力。