在 DigitalOcean App Platform 上部署 Next.js 指南 2026

DigitalOcean 的 App Platform 是一种方便的方式来部署 Next.js 应用程序，无需自己管理服务器。但是，Next.js 有多种渲染模式——静态、SSR 和 ISR——每种都需要不同的构建/运行命令配置和 App Platform 上的组件类型。本指南深入讨论 Next.js 部署细节：从构建命令和环境变量到定价层和常见错误及其解决方案。

什么是 App Platform 以及它与 Droplet 的区别？

App Platform 是 DigitalOcean 的平台即服务 (PaaS) 产品，用于从源代码部署应用程序，无需自己管理服务器。它与 Droplet 的根本区别在于，Droplet 是基础设施即服务 (IaaS)——用户必须创建虚拟机、安装 Node.js、配置进程管理器（如 PM2）、设置 Nginx 作为反向代理，并手动申请 SSL 证书。对于 Next.js 来说，这种区别特别重要，因为 Next.js 支持多种渲染模式：静态网站生成 (SSG)、服务器端渲染 (SSR) 和增量静态再生 (ISR)——每一种都需要不同的运行时环境。 当你将指定 "next" 依赖项的存储库推送到 GitHub 并将其连接到 App Platform 时，系统会通过 Cloud Native Buildpacks 自动检测框架并建议合适的组件类型。如果你的应用程序仅包含静态页面（无 API 路由或 SSR），可以将其部署为 "Static Site" 组件，该组件符合免费层资格。但是，如果你的应用程序有 API 路由、getServerSideProps 或具有按需重新验证的 ISR，你必须使用 "Service"（Web Service）组件，该组件持续运行 Node.js 进程以处理请求——此组件类型始终是付费的；没有免费层。 App Platform 的优势包括无需自己修补操作系统、无需防火墙配置，因为 DigitalOcean 处理 TLS 终止、负载平衡和进程崩溃时的自动重启。交换条件是，与 Droplet 相比，灵活性降低——你无法通过 SSH 调整操作系统级配置或安装自定义 Nginx 模块。对于希望快速部署 Next.js、将代码优先于基础设施，且没有需要深度堆栈调优的极高流量的团队，App Platform 显然是比 Droplet 更好的选择。

• App Platform = PaaS（托管），Droplet = IaaS（自管理）
• Static Site 组件仅支持 SSG/静态导出，符合免费层资格
• SSR/API 路由/ISR 需要 Web Service 组件——始终付费

将 GitHub 存储库连接到 App Platform

基于真实使用经验，要将 Next.js 项目连接到 App Platform，请在 cloud.digitalocean.com/apps 处开始并点击创建应用程序。选择 GitHub 作为源（也支持 GitLab 和 Docker Hub，但 GitHub 是 Next.js 最常见的工作流）。如果这是你第一次连接，系统会引导你安装 DigitalOcean GitHub 应用程序，这需要你授权存储库访问——你可以选择 "所有存储库" 或指定个别存储库以增强安全性。 授权后，选择要部署的存储库和分支（通常是 main 或 production）。如果你的项目是单体仓库，Next.js 应用程序在子文件夹中（如 apps/web），你必须指定源目录以匹配该路径。否则，buildpack 将找不到根目录中的 package.json，构建将失败。 接下来，App Platform 扫描存储库以检测框架。当它在 package.json 依赖项中找到 "next" 时，它会自动建议组件类型和默认的构建/运行命令。你可以在实际部署前审查和修改这些。 一个重要的选项是自动部署——启用时，每次你将新提交推送到所选分支，App Platform 都会自动触发构建和部署。这就像一个内置的 CI/CD 流程，无需单独编写 GitHub Actions——非常适合不想维护单独 CI/CD 系统的小型到中型团队。需要更多部署步骤控制的团队（例如首先运行测试套件）可以禁用自动部署，改为使用 doctl apps create-deployment 从外部工作流触发部署。 成功连接存储库后，App Platform 在实时显示构建日志，使调试依赖项或构建脚本错误变得容易，无需等待完整部署。

• 从 cloud.digitalocean.com/apps → 创建应用程序 → GitHub 开始
• 安装 DigitalOcean GitHub 应用程序以授权存储库访问
• 单体仓库必须指定源目录以匹配 package.json 位置
• 启用自动部署以在每次推送时自动构建/部署
• 查看实时构建日志以立即调试问题

为 Next.js 配置构建和运行命令

为 Next.js 在 App Platform 上正常工作，设置正确的构建和运行命令至关重要，因为 buildpack 的默认猜测可能与你的项目结构不匹配。 标准的构建命令是 npm install && npm run build，虽然 buildpack 实际上会自动运行安装，所以 npm run build（在内部调用 next build）就足够了。如果你的项目使用 yarn 或 pnpm，指定匹配的命令，例如 pnpm install && pnpm build，因为 buildpack 根据找到的锁文件选择包管理器（package-lock.json、yarn.lock、pnpm-lock.yaml）。 Web Service 组件的运行命令通常是 npm start，它映射到 package.json 中的 next start——一个常见的错误是忘记 App Platform 通过 $PORT 环境变量动态分配端口，而不是始终使用 3000。你必须更新脚本为 next start -p $PORT，否则健康检查将失败，因为容器未在预期端口上侦听。 对于寻求更小镜像大小和更快冷启动的项目，在 next.config.js 中启用 output: 'standalone'，它将仅必需的文件捆绑到 .next/standalone 中，将运行命令更改为 node .next/standalone/server.js（你必须在构建步骤中手动复制 public/ 和 .next/static，因为独立输出不会自动包含它们）。 始终通过在 package.json 中指定 "engines": {"node": "20.x"} 来固定 Node.js 版本，以防止 buildpack 选择不同的 Node 版本，这可能导致构建行为与测试不同。 对于仅静态导出的部署（无 SSR/API 路由），在 next.config.js 中设置 output: 'export'，使用 next build 作为构建命令，将输出目录指定为 out，并选择 Static Site 作为组件类型——这符合免费层资格但会舍弃所有 SSR/ISR 功能。

• 构建命令：npm run build（调用 next build）
• 运行命令必须绑定 $PORT：next start -p $PORT
• 启用 output: 'standalone' 以减少构建大小和冷启动时间
• 使用 package.json 中的 engines 固定 Node 版本
• 静态导出使用 output: 'export' + 输出目录 out

环境变量和自定义域

App Platform 上的环境变量存在于两个级别：应用级（在所有组件中共享）和组件级（特定于一个服务）。通过设置 > 应用级环境变量中的仪表板或通过 YAML 格式的应用规格配置它们。 对于 Next.js，一个关键的区别是前缀为 NEXT_PUBLIC_ 的变量在构建时被内联到客户端 JavaScript 包中——它们的值被烘焙到静态文件中，对任何打开 DevTools 的人可见。永远不要将此前缀用于秘密或 API 密钥。没有此前缀的变量仅在服务器端可用，例如在 API 路由或 getServerSideProps 中。 另一个常见陷阱：更改 NEXT_PUBLIC_* 值并部署，如果没有推送新提交将不会自动重新构建。App Platform 不会自动重新构建，因为这些值被烘焙到构建中，而不是在运行时注入。你必须通过部署按钮或 CLI 手动触发重新构建。 对于敏感数据（如数据库连接字符串或 API 秘密），在仪表板的环境变量部分中将类型设置为 "Encrypted"（SECRET）而不是 "Plain Text"（GENERAL），防止值作为纯文本出现在构建日志或 UI 中。 对于自定义域，在你的应用程序中转到设置 > 域，点击添加域，然后输入所需的域。系统提供一条 CNAME 或 A/ALIAS 记录在你的 DNS 提供商处配置，指向你的应用程序的默认域（格式：your-app-xxxxx.ondigitalocean.app）。DNS 传播后，App Platform 自动从 Let's Encrypt 颁发 TLS 证书，无需手动 Certbot 设置——HTTPS 在几分钟内准备就绪。

• 分开应用级和组件级环境变量
• NEXT_PUBLIC_ 前缀在构建时嵌入客户端值——永远不要用于秘密
• 更改 NEXT_PUBLIC_* 需要手动重新构建——值更改时不会自动重新构建

定价：静态网站免费 / Web 服务从 $5/月开始

从静态网站过渡到具有 SSR 的 Next.js 时，定价是许多人困惑的地方，因为 App Platform 的免费层仅涵盖 Static Site 组件——每个账户最多 3 个应用程序，每个应用程序 1 GiB 带宽，无费用。这适用于没有 API 路由或 SSR 的静态导出。 但是，如果你的 Next.js 应用程序使用 getServerSideProps、API 路由、中间件或具有按需重新验证的 ISR，你必须部署为 Web Service 组件，没有免费层可用——付款始终是必需的。DigitalOcean 在 2026 年中期停用了旧的基本/专业层名称，改为直接选择容器实例大小。当前选项是： 共享 1 vCPU / 512 MiB RAM / 每月 50 GiB 传输 = $5/月，共享 1 vCPU / 1 GiB RAM / 100 GiB 传输 = $10/月，共享 1 vCPU / 1 GiB RAM / 150 GiB 传输 = $12/月，共享 1 vCPU / 2 GiB RAM / 200 GiB 传输 = $25/月，以及共享 2 vCPU / 4 GiB RAM / 250 GiB 传输 = $50/月。 对于流量适中的小型到中型 Next.js 应用程序，$5/月计划（512 MiB RAM）通常足以进行原型设计或 MVP，但如果你的应用程序在 API 路由中执行繁重的 ISR 缓存或内存密集型操作（如 PDF 生成或图像处理），升级到 1 GiB 或更高以防止内存不足杀死。 请注意：将实例计数设置为大于 1 以实现高流量或零停机部署会立即将成本乘以实例计数。例如，$10/月计划上的 2 个实例总共 $20/月，而不是像单个 Droplet 那样的固定费率——这在根本上是不同的。所有定价均为 2026 年 7 月最新；在承诺前务必在 DigitalOcean 定价页面上验证最新定价。

• 免费层：仅限静态网站，最多 3 个应用程序，每个应用程序 1 GiB 传输
• Web Service 没有免费层——始终需要付款
• 起价计划：$5/月（1 vCPU/512 MiB RAM/50 GiB 传输）

何时应使用此功能（真实用例）

当团队优先考虑发货速度而不是详细的基础设施控制时，App Platform 适合 Next.js 部署——例如需要在推送代码后数分钟内投入生产的 MVP 或副项目、混合静态页面与小型 API 路由（用于联系表单或新闻通讯注册）的营销网站，或没有专门的 DevOps 工程师来管理 Nginx/SSL/进程管理器的小型团队。 另一个极好的用例是拉取请求的预览环境。当 PR 打开时，App Platform 可以自动创建单独的预览部署，让你的团队在合并前在真实 URL 上审查新功能，无需额外的 CI/CD 设置——对于进行基于主干开发或频繁 UI 审查的团队很有价值。 相反，当你需要细粒度的操作系统或网络调优时，App Platform 不是最合适的——例如复杂的自定义 Nginx 重写规则或管理大量 WebSocket 连接，需要连接池调优，当你有非常高的流量，每个请求的成本很重要，使用带 PM2 和 Nginx 的 Droplet 在规模上会更便宜，或当你的应用程序大量依赖 ISR 并需要跨多个实例的共享缓存时，因为 App Platform 容器缺乏共享文件系统——每个实例都有隔离的缓存，可能在多个实例处理流量时向用户显示不一致的数据。 对于对流量扩展不确定的团队，从 App Platform 开始，然后随着要求澄清，迁移到 Droplet 或 Kubernetes，是务实的选择：初始成本低、没有架构锁定，且当真实数字到来时易于重新评估。

• 适合 MVP、营销网站和没有专门 DevOps 的团队
• 支持拉取请求的自动预览环境
• 不适合深度操作系统/网络级调优要求
• 具有多个实例的 ISR 需要小心——缓存未同步

常见错误及其修复方法

在 App Platform 上部署 Next.js 时最常见的错误是由于 Node.js 版本不匹配导致构建失败，特别是在使用特定于较新 Node 版本的语法或依赖项时。通过使用 package.json 中的 engines 字段将版本固定到与本地测试环境匹配来修复此问题。 第二个常见问题是成功部署但应用程序无法访问或健康检查反复失败。根本原因通常是运行命令未绑定到 App Platform 动态分配的 $PORT——容器最终在错误的端口上侦听。始终将启动脚本更新为 next start -p $PORT，永远不要硬编码 3000。 第三个问题涉及环境变量——当缺少 NEXT_PUBLIC_ 前缀时，客户端代码读取未定义的值。服务器变量无论如何配置都不会到达浏览器包。 第四个问题与 ISR 相关：页面显示某些请求中的陈旧内容和其他请求中的新鲜内容，请求落在各自维护单独缓存的不同实例上。解决方案包括如果流量不高则将实例计数减少到 1，或将缓存迁移到外部层（如托管 Valkey 数据库）。 第五个问题出现在单体仓库中：构建超时或意外的长构建持续时间。这发生在源目录未正确指定时，导致 buildpack 为整个单体仓库安装依赖项，而不仅仅是 Next.js 应用程序。精确设置源目录并考虑在构建命令中使用工作区过滤（如 pnpm --filter）来缩小范围。

• 构建因 Node 版本不匹配而失败 → 使用 engines 固定
• 健康检查失败 → 忘记在运行命令中绑定 $PORT
• 客户端无法读取环境变量 → 缺少 NEXT_PUBLIC_ 前缀

最佳实践

生产环境中 Next.js 在 App Platform 上的最佳实践是在 next.config.js 中始终启用 output: 'standalone'，因为与捆绑所有 node_modules 相比，它显著减少构建工件大小和冷启动时间。 调整实例计数以匹配实际工作负载——如果你的应用程序依赖于 ISR 或内存中缓存，请从 1 个实例开始，然后在扩展到多个实例以避免向用户显示不一致的数据之前，考虑将缓存层外部化到托管 Valkey 数据库。 将应用规格存储为 YAML 在你的存储库中，使用 doctl apps create --spec app.yaml 或 doctl apps update 而不是完全通过仪表板配置。这将基础设施视为代码，允许你将其与代码一起进行版本控制，并轻松重新创建或回滚环境。 始终通过将敏感数据（API 密钥、数据库 URL、身份验证秘密）设置为加密类型而不是纯文本，来分开秘密和普通环境变量，并验证没有秘密意外获得 NEXT_PUBLIC_ 前缀。 为每个拉取请求启用预览环境，以便你的团队可以在真实 URL 上审查工作，然后再合并，而不仅仅是审查代码差异——这会更快地捕捉 UI/UX 错误和环境变量错误。 最后，通过 App Platform 的内置功能设置基本监控/告警以在内存使用或重启计数异常增加时通知你。这些是早期警告信号，表明你的当前计划对于真实流量而言太小，然后用户才会遇到中断。

• 始终为生产启用 output: 'standalone'
• 控制实例计数以匹配工作负载——对于缓存重的应用程序特别重要
• 将应用规格存储为存储库中的 YAML（基础设施即代码）
• 为所有秘密使用加密类型

领取 $200 免费额度 →