将 Next.js 部署到 Sevalla 是做什么的？

Sevalla（Kinsta 旗下）是一个 PaaS 平台，为 Next.js 提供两种托管产品：

Application Hosting：运行真实的 Node.js 服务器。适用于 SSR、路由处理器（API 路由）、代理（原中间件）、ISR（revalidate）、服务器操作或 WebSocket。
Static Site Hosting：为静态导出的输出（output: 'export'）提供服务。不包含任何服务器端代码。每个公司限创建 100 个静态站点。

首先要正确做出这个决定，这将决定后续所有步骤。

第 0 步：决定使用哪种托管产品

在开始任何其他操作之前，请检查仓库：

读取 next.config.js / next.config.ts / next.config.mjs，查看是否有 output: 'export' 或 output: 'standalone'。
在代码库中搜索：app/api/、pages/api/、proxy.ts 或 proxy.js（Next.js 16）、middleware.ts 或 middleware.js（Next.js 15 及更早版本）、"use server"、getServerSideProps、revalidate（ISR）、NextResponse，或在服务器端使用的任何数据库或认证客户端。
决定：
- 如果存在上述任何一项：使用 Application Hosting（需要服务器）。跳至第 1 步。
- 如果都不存在，且内容是纯静态的、营销或博客类：Static Site Hosting 更简单且更便宜。请阅读 references/static-hosting.md。
- 如果不确定，或者用户希望将来使用动态功能：默认为 Application Hosting。它能完成静态托管能做的一切。

如果确实难以判断，请向用户提一个问题：“这个应用需要实时服务器（API 路由、ISR、认证、数据库调用）还是完全是静态内容？” 不要默默地猜测，因为错误的选择意味着需要重做整个部署。

同时检查仓库中是否有数据库客户端（Prisma、Drizzle、pg、mysql2、Mongoose、redis、ioredis）以及文件上传功能。如果找到，请在执行第 3 步之前阅读 references/data-services.md。

第 1 步：选择构建策略（Application Hosting）

Sevalla 使用四种策略之一构建基于 Git 的应用：

Nixpacks，默认选项。对于标准的 Next.js 应用，零配置。除非有理由不使用，否则请使用它。
Railpack，Nixpacks 的继任者。同样零配置。对于新应用是一个不错的选择。使用 API 字段 build_type: "railpack" 进行设置。
Dockerfile，当用户想要一个小的、可重现的镜像、拥有自动检测工具难以处理的单体仓库、或明确要求 Docker 时使用。
Buildpacks（pack）。For Next.js，很少需要。

在编写任何配置之前，请阅读 references/app-hosting.md。其中包含确切的 package.json 脚本、推荐的 Dockerfile、nixpacks.toml 覆盖项以及单体仓库的 构建路径 设置。不要根据通用的 Next.js 知识手动编写 Dockerfile 或 nixpacks.toml。Sevalla 有特定约束（如下所述），通用指南不会提及。

第 2 步：准备仓库（Sevalla 约束）

这些问题几乎每个首次部署都会遇到。在部署之前，请逐一检查所有项目：

从 $PORT 读取端口并绑定到 0.0.0.0。 Web 进程的默认端口是 8080，Sevalla 会通过 PORT 变量传递它。只有 80 和 443 端口对互联网开放，Sevalla 会将它们路由到 $PORT。使用 Nixpacks 或 Railpack 时，启动脚本必须为 next start -p ${PORT:-8080} -H 0.0.0.0。简单的 next start 会监听 3000 端口。
NEXT_PUBLIC_* 变量在构建时被内联。 在构建之前，将它们创建为构建时变量（is_buildtime: true）。稍后添加的变量需要新的部署，而不是重启。
文件系统是临时的。 应用在运行时写入磁盘的任何内容（上传、生成的文件、磁盘缓存）在每次重新部署或重启时都会丢失。请使用对象存储，或者如果应用确实需要本地磁盘写入（例如 SQLite 或自托管 CMS），则使用持久化磁盘。参见 references/data-services.md。
output: 'standalone' 仅与 Dockerfile 配合使用。 next start 不使用独立构建包，Next.js 会警告 "next start" does not work with "output: standalone" configuration。因此，使用 Nixpacks 或 Railpack 时，不要设置 output。使用 Dockerfile 时，设置 output: 'standalone'。
不要提交 node_modules 或 .next。 提交的 node_modules 文件夹是 Sevalla 上构建失败的有据可查的原因。
固定 Node.js 版本。 Nixpacks 默认使用 Node 18，而 Next.js 16 需要 Node 20.9 或更高版本。在 package.json 中设置 "engines": { "node": "22.x" }，或设置构建时变量 NIXPACKS_NODE_VERSION=22。
单体仓库：将 构建路径（API 字段 build_path）设置为 Next.js 应用所在的文件夹，例如 apps/web。使用 Dockerfile 时，还需设置 docker_context 和 dockerfile_path。
package.json 的 name：不要使用 "node" 或 "js" 作为包名。这已被证明会破坏 Sevalla 构建。
变量值中的双引号 必须转义为 \"。未转义的引号会被丢弃或导致发布失败。
密钥（数据库 URL、API 密钥）应放入 Sevalla 环境变量。切勿提交包含真实密钥的 .env 文件。

第 3 步：部署

按顺序使用第一个可用的选项：

Sevalla MCP 服务器（https://mcp.sevalla.com/mcp）。它有两个工具：search 在规范中查找 API 端点，execute 运行调用 sevalla.request({ method, path, body }) 的 JavaScript。请使用下表中的 API 路径。
sevalla CLI，在每个命令后加上 --json，以便读取 ID。使用 npm install -g @sevalla/cli（Node 22+）或 brew install sevalla-hosting/tap/sevalla 安装。使用 sevalla login（浏览器中的设备授权）登录，或设置 SEVALLA_API_TOKEN。
REST API，位于 https://api.sevalla.com/v3，使用 Bearer API 密钥。

如果以上都没有，请告诉用户如何添加 MCP 服务器（请参阅 https://docs.sevalla.com/quick-starts/coding-agents/overview 的编码代理快速入门），或者为他们提供 references/dashboard.md 中的控制台操作步骤。只有首次登录才需要用户操作。

Application Hosting

#	操作	API（MCP `execute` 或 REST）	CLI
1	选择位置	`GET /resources/clusters`	`sevalla resources clusters --json`
2	创建应用	`POST /applications` 包含 `display_name`、`cluster_id`、`source`（已连接的 GitHub、GitLab 或 Bitbucket 仓库使用 `privateGit`，公共 URL 使用 `publicGit`）、`git_type`、`repo_url`、`default_branch`	`sevalla apps create --name <name> --cluster <cluster-id> --source privateGit --git-type github --repository https://github.com/<owner>/<repo> --branch <branch> --json`
3	设置构建策略和构建路径（如果不是默认值）	`PATCH /applications/{id}` 包含 `build_type`（`nixpacks`、`railpack`、`dockerfile`、`pack`）和 `build_path`	`sevalla apps update <app-id> --build-type railpack --json`。CLI 没有构建路径标志：`sevalla apps update <app-id> --data '{"build_path":"apps/web"}' --json`
4	添加环境变量	`POST /applications/{id}/env-vars` 包含 `key` 和 `value`。`is_runtime` 和 `is_buildtime` 均默认为 `true`，这对于 `NEXT_PUBLIC_*` 是正确的。	`sevalla apps env-vars create <app-id> --key <KEY> --value "<value>"`（在构建时和运行时都可用）
5	连接数据库（如果有）	参见 `references/data-services.md`
6	部署	`POST /applications/{id}/deployments`。创建应用不会自动启动部署。	`sevalla apps deployments trigger <app-id> --branch <branch> --json`

如果步骤 2 对于 privateGit 仓库返回 HTTP 500，最可能的原因是 Sevalla 的 GitHub 应用无法访问该仓库。API 不会说明这一点。使用 sevalla git providers --json 检查：settings_url 会打开 GitHub 应用安装页面。用户（或 GitHub 组织的所有者）必须授予应用对仓库的访问权限。如果用户不是组织的所有者，则需要所有者添加。然后重试步骤 2。

新应用的自动部署功能是关闭的。如果用户希望每次推送都触发部署，请使用 PATCH /applications/{id} 设置 auto_deploy: true（仅适用于 privateGit）。

对于 Static Site Hosting，请按照 references/static-hosting.md 操作。创建一个静态站点会自动启动其首次部署。

第 4 步：验证

一个已开始的部署并不代表一个能正常运行的部署。在告知用户完成之前，请完成以下所有操作：

等待构建完成。 每 15 到 30 秒轮询 GET /applications/{id}/deployments/{deployment_id}（CLI：sevalla apps deployments get <deployment-id> --app-id <app-id> --json），直到 status 变为 success 或 failed。其他可能的状态有 waiting、inProgress、cancelled 和 skipped。
如果构建失败，请阅读构建日志。 GET /applications/{id}/deployments/{deployment_id}/logs（CLI：sevalla apps deployments logs ...）。将错误与 references/app-hosting.md 中的故障排除表进行匹配，修复问题，然后重新部署。不要在没有读取日志的情况下进行第二次猜测。以部署 status 而非日志严重性来判断成功： 正常的构建输出写入 stderr，在成功构建中会显示为 "severity": "error"。
找到实时 URL。 GET /applications/{id}/domains（CLI：sevalla apps domains list --app-id <app-id> --json）。每个应用在首次成功部署后都会获得一个免费的 *.sevalla.app 域名。
请求该 URL。 期望在 / 和一个路由处理器（如果应用有的话）上返回 HTTP 200。502 错误或超时通常意味着服务器没有在 $PORT 和 0.0.0.0 上监听。
如果应用返回错误，请阅读运行时日志。 GET /applications/{id}/runtime-logs（CLI：sevalla apps logs runtime <app-id>）。

然后告知用户实时 URL、你配置的内容以及他们需要自己完成的任何操作（例如，为自定义域名添加 DNS 记录）。

第 5 步：可选后续步骤

自定义域名：sevalla apps domains add <app-id> --name example.com。用户必须添加 Sevalla 返回的 DNS 记录。包含 SSL。
扩展：sevalla apps processes update <process-id> --app-id <app-id> --instances <n>。对于多个实例，不要将持久化磁盘用于共享状态。请使用对象存储或数据库。
回滚：sevalla apps deployments rollback <app-id> --deployment-id <id>。

参考文件

references/app-hosting.md：package.json 脚本、Nixpacks 和 Railpack 说明、推荐的 Dockerfile、单体仓库设置、故障排除表。
references/static-hosting.md：静态导出设置和针对 Static Site Hosting 的部署。
references/data-services.md：数据库、对象存储和持久化磁盘，以及它们的连接详情如何到达应用。
references/dashboard.md：在 Sevalla 仪表板中执行相同步骤的操作指南，供人工操作。

将 Next.js 部署到 Sevalla