將 Next.js 部署到 Sevalla
Sevalla (Kinsta 旗下) 是一個 PaaS，為 Next.js 提供兩種託管產品：
- 應用程式託管 執行真實的 Node.js 伺服器。 需要 SSR、路由處理器 (API 路由)、代理 (舊稱中介軟體)、ISR (
revalidate)、伺服器動作或 WebSocket。 - 靜態網站託管 提供靜態匯出的輸出 (
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，或任何在伺服器端使用的資料庫或驗證客戶端。 - 決定：
- 如果存在上述任何一項：使用 應用程式託管 (需要伺服器)。 前往步驟 1。
- 如果都不存在，且是純靜態內容、行銷或部落格：靜態網站託管 更簡單且更便宜。 閱讀
references/static-hosting.md。 - 如果不確定，或使用者稍後想要動態功能：預設使用應用程式託管。 它可以做到靜態託管能做的所有事情。
如果確實模棱兩可，請問使用者一個問題：「這個應用程式需要一個即時伺服器 (API 路由、ISR、驗證、資料庫呼叫) 還是完全是靜態內容？」 不要默默地猜測，因為錯誤的選擇意味著要重做整個部署。
同時檢查存放庫中是否有資料庫客戶端 (Prisma、Drizzle、pg、mysql2、Mongoose、redis、ioredis) 以及檔案上傳。 如果找到，請在步驟 3 之前閱讀 references/data-services.md。
步驟 1：選擇建置策略 (應用程式託管)
Sevalla 使用四種策略之一來建置基於 Git 的應用程式：
- Nixpacks，預設值。 對於標準 Next.js 應用程式無需配置。 除非有理由不使用，否則請使用它。
- Railpack，Nixpacks 的後繼者。 同樣無需配置。 對於新應用程式來說是個不錯的選擇。 使用 API 欄位
build_type: "railpack"進行設定。 - Dockerfile，當使用者想要一個小而可重現的映像檔、有一個自動偵測建置器難以處理的 monorepo，或者要求使用 Docker 時。
- Buildpacks (
pack)。 很少需要為 Next.js 使用。
在撰寫任何配置之前，請先閱讀 references/app-hosting.md。 它包含確切的 package.json 指令碼、建議的 Dockerfile、nixpacks.toml 覆蓋以及 monorepo 的 Build path 設定。 不要根據一般的 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。 - Monorepo：將 Build path (API 欄位
build_path) 設定為 Next.js 應用程式的資料夾，例如apps/web。 使用 Dockerfile 時，也要設定docker_context和dockerfile_path。 package.json名稱：不要使用"node"或"js"作為套件名稱。 已知這會破壞 Sevalla 的建置。- 變數值中的雙引號必須跳脫為
\"。 未跳脫的引號會被丟棄或導致推出失敗。 - 機密 (資料庫 URL、API 金鑰) 應放入 Sevalla 環境變數中。 切勿提交包含真實機密的
.env檔案。
步驟 3：部署
使用第一個可用的選項，按此順序：
- Sevalla MCP 伺服器 (
https://mcp.sevalla.com/mcp)。 它有兩個工具：search在規格中尋找 API 端點，execute執行 JavaScript 來呼叫sevalla.request({ method, path, body })。 使用下表中的 API 路徑。 sevallaCLI，在每個指令上加上--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 中的儀表板步驟。 只有第一次登入才需要使用者操作。
應用程式託管
| # | 動作 | API (MCP execute 或 REST) | CLI |
|---|---|---|---|
| 1 | 選擇位置 | GET /resources/clusters | sevalla resources clusters --json |
| 2 | 建立應用程式 | POST /applications 搭配 display_name、cluster_id、source (privateGit 用於已連結的 GitHub、GitLab 或 Bitbucket 存放庫，publicGit 用於公開 URL)、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)。
對於靜態網站託管，請改為遵循 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、monorepo 設定、疑難排解表。references/static-hosting.md：靜態匯出設定和靜態網站託管的部署。references/data-services.md：資料庫、物件儲存和持久性磁碟，以及它們的連線詳細資訊如何到達應用程式。references/dashboard.md：在 Sevalla 儀表板中的相同步驟，供人員操作。