Next.js 托管：部署 Next.js 应用

简介

要在 Square Cloud 上开发和托管 Next.js 应用，遵循一套结构化的配置和前置条件流程至关重要。本技术指南将涵盖整个过程，从初始设置到生产环境部署。

前置条件

Square Cloud 账户：通过注册页面使用你的邮箱进行注册。
有效套餐：为你的应用提供专属资源和优化的性能。查看我们可用的套餐，选择最适合你需求的方案。

本指南运行在 Node.js 运行时上。已于 2026 年 9 月在 Node.js 24 上使用 Next.js 16 测试。

创建项目

你的电脑上需要安装 Node.js 20.9 或更高版本以及 npm。如果尚未安装，可以从 Node.js 官方网站下载。使用官方初始化工具创建项目：

npx create-next-app@latest my-app

初始化工具会询问 TypeScript、代码检查工具、Tailwind CSS 和 App Router 等选项，然后安装依赖。使用 npm run dev 启动开发服务器，并编辑 app/page.tsx（或 app/page.js）来修改首页。

构建生产版本

npm run build

next build 会将生产构建写入 .next 文件夹。请在你的电脑上运行它：TypeScript、ESLint 和 Tailwind CSS 属于 devDependencies，而 Square Cloud 不会安装它们。

端口和主机

Next.js 无需任何修改：next start 会读取 PORT 环境变量（Square Cloud 将其设为 80），并监听所有网络接口。请保留 package.json 中默认的 start 脚本：

package.json

"scripts": {
  "start": "next start"
}

配置 Square Cloud

在项目根目录创建 squarecloud.app 文件：

squarecloud.app

RUNTIME=nodejs
START=npm run start
MEMORY=1024
VERSION=recommended
DISPLAY_NAME=My Next.js app
SUBDOMAIN=my-next-app

RUNTIME=nodejs 会选择 Node.js 运行时而无需 MAIN 文件，START 则运行 next start。通过控制面板上传时，请设置相同的启动命令。

ZIP 中包含哪些文件

.next/，即生产构建（Square Cloud 会在上传时移除 .next/cache，因此你可以不包含它）。
public/、package.json 和你的 next.config.* 文件。
squarecloud.app。
next start 不会读取你的源代码文件夹（app/ 或 pages/），但上传它们也没有影响。

不要包含 node_modules：Square Cloud 会在首次启动时安装你的 dependencies。

部署并验证

通过控制面板

访问上传页面

访问上传页面并上传你的项目 zip 文件。

配置你的环境

上传 zip 后，你需要为项目配置名称、主文件或运行时环境以及其他设置。
如果你上传的是 Web 项目，请务必选择 “Web Publication” 并为项目设置子域名。

部署你的项目

最后，点击 “Deploy” 按钮，即可将项目托管到 Square Cloud。
部署完成后，你可以在控制面板中监控项目的状态和日志。

确认你的应用已上线

首次部署通常在一分钟内完成。在控制面板中，等待你的应用状态显示为运行中，并检查日志中是否有启动错误。
如果你部署的是网站或 API，请在浏览器中打开 https://<your-subdomain>.squareweb.app，你应该能看到应用正常响应。如果你部署的是机器人，发送一条命令确认它已上线。

应用无法启动？请参见故障排除指南，了解最常见的原因和解决方法。

通过 CLI

要使用此方法，你的项目根目录中需要有一个名为 squarecloud.app 的配置文件。它告诉 Square Cloud 如何运行你的应用。

配置文件指南

了解如何创建定义你应用环境的 squarecloud.app 配置文件。

安装 CLI

安装 Square Cloud CLI。如果你已经安装，运行同一条命令即可更新：

curl -fsSL https://cli.squarecloud.app/install | bash

npm install -g @squarecloud/cli@latest

运行下面的命令。它会打开你的浏览器：在浏览器中批准登录后，CLI 即可使用。无需复制任何 API 密钥。如需在脚本和 CI 中使用，请参阅 CLI 身份验证。

squarecloud auth login

上传你的项目

在项目文件夹中运行下面的命令。CLI 会将当前文件夹打包为 zip（排除 squarecloud.ignore 中列出的内容）并上传：

squarecloud upload

要上传你自己创建的 zip，请通过 --file 传入：

squarecloud upload --file <path/to/zip>

确认你的应用已上线

首次部署通常在一分钟内完成。直接在终端中检查你的应用状态和日志：

squarecloud app status
squarecloud app logs

如果你部署的是网站或 API，请在浏览器中打开 https://<your-subdomain>.squareweb.app，你应该能看到应用正常响应。如果你部署的是机器人，发送一条命令确认它已上线。

应用无法启动？请参见故障排除指南，了解最常见的原因和解决方法。

常见错误

自定义域名

若要使用自定义域名（例如 mysite.com）来代替默认 URL mysite.squareweb.app，你需要 Standard 计划或更高等级。默认 URL 由配置文件中的 SUBDOMAIN 字段决定。要连接你的域名，请参阅如何设置自己的域名。

最低内存要求

网站和 API 的最低要求为 512MB RAM，足以在静态运行时上托管静态构建产物。对于在服务器上渲染页面的应用（Next.js、Nuxt、Angular SSR 等），我们建议至少 1GB RAM。对于更大型的应用，请分配更多 RAM，以防止应用内存耗尽而崩溃。

找不到此站点。

请检查子域名/域名是否与 SUBDOMAIN 字段或自定义域名设置中配置的内容一致。如果你刚上传站点，请等待最多 60 秒，让 Square 启用首次访问。

站点响应超时……

你的服务器必须监听端口 80 和主机 0.0.0.0。Square Cloud 会在你的应用中设置 PORT（80）和 HOST（0.0.0.0）环境变量：请在代码中读取它们，而不要硬编码其他值。只监听 localhost 或 127.0.0.1 的服务器永远收不到请求。

Could not find a production build

next start 找不到 .next 文件夹。请在打包前运行 npm run build，并检查 ZIP 中是否包含 .next。

每次推送时通过 GitHub Actions 部署

Square Cloud GitHub Action 会在 runner 上安装 CLI，因此工作流可以构建你的应用并将其发送到 Square Cloud。将一个 API 密钥保存为仓库 secret SQUARECLOUD_API_KEY，将应用 ID 保存为仓库变量 SQUARECLOUD_APP_ID，然后添加 .github/workflows/deploy.yml：

.github/workflows/deploy.yml

name: Deploy Next.js app

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7

      - uses: actions/setup-node@v7
        with:
          node-version: 24

      - uses: squarecloudofc/github-action@v2
        with:
          token: ${{ secrets.SQUARECLOUD_API_KEY }}
          install-only: true

      - run: npm ci && npm run build

      - run: squarecloud commit ${{ vars.SQUARECLOUD_APP_ID }} --restart

squarecloud commit 会将文件夹（包括新构建的 .next）发送到你的应用，--restart 会重启应用，让新构建上线。将 .next/cache 添加到 squarecloud.ignore 文件中，可以让上传保持精简。更多选项请参阅使用 GitHub Actions 部署。

后续步骤

环境变量

将密钥和设置放在代码之外，并在运行时读取。

自定义域名

在 Standard 及以上计划中，用你自己的域名提供应用。

故障排除

修复无法启动的应用或没有响应的站点。

有关 Next.js 的更多信息，请参阅 Next.js 官方文档。

联系我们

如果你仍然遇到技术问题，我们的专业支持团队可以为你提供帮助。联系我们，我们很乐意协助你解决任何问题，支持质量正是开发者给予 Square Cloud 4.9/5 评分（共 402 条评价）（Google 与 Trustpilot）的重要原因之一。

Bots

网站

API 与后端

数据库

自托管应用

指南

迁移指南

Next.js 托管：部署 Next.js 应用

简介

前置条件

创建项目

构建生产版本

端口和主机

配置 Square Cloud

ZIP 中包含哪些文件

部署并验证

通过控制面板

通过 CLI

配置文件指南

常见错误

自定义域名

最低内存要求

找不到此站点。

站点响应超时……

Could not find a production build

每次推送时通过 GitHub Actions 部署

后续步骤

环境变量

自定义域名

故障排除

联系我们

​简介

​前置条件

​创建项目

​构建生产版本

​端口和主机

​配置 Square Cloud

​ZIP 中包含哪些文件

​部署并验证

​通过控制面板

​通过 CLI

配置文件指南

​常见错误

​自定义域名

​最低内存要求

​找不到此站点。

​站点响应超时……

​Could not find a production build

​每次推送时通过 GitHub Actions 部署

​后续步骤

环境变量

自定义域名

故障排除

​联系我们

简介

前置条件

创建项目

构建生产版本

端口和主机

配置 Square Cloud

ZIP 中包含哪些文件

部署并验证

通过控制面板

通过 CLI

常见错误

自定义域名

最低内存要求

找不到此站点。

站点响应超时……

Could not find a production build

每次推送时通过 GitHub Actions 部署

后续步骤

联系我们