部署 Fastify API

简介

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

前置条件

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

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

创建项目

你的电脑上需要安装 Node.js 和 npm。如果尚未安装，可以从 Node.js 官方网站下载。创建一个带有 package.json 的项目文件夹，启用 ES 模块并安装 Fastify：

mkdir my-fastify-api
cd my-fastify-api
npm init -y
npm pkg set type=module
npm install fastify

然后创建 app.js 文件：

app.js

import Fastify from 'fastify';

const fastify = Fastify({ logger: true });

fastify.get('/', async () => {
  return 'Hello World!';
});

// Fastify listens only on localhost unless you pass a host.
// Square Cloud sets PORT=80; 0.0.0.0 accepts connections from outside the container.
try {
  await fastify.listen({ port: Number(process.env.PORT) || 80, host: '0.0.0.0' });
} catch (err) {
  fastify.log.error(err);
  process.exit(1);
}

要在你的电脑上运行，请选择一个空闲端口：PORT=3000 node app.js，然后打开 http://localhost:3000。

端口和主机

Fastify 需要在 listen() 中同时设置这两项。默认情况下它只监听 localhost，因此来自容器外部的请求永远无法到达，你的站点会超时。host: '0.0.0.0' 让它监听所有网络接口，而 process.env.PORT 在 Square Cloud 上为 80。

配置 Square Cloud

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

squarecloud.app

MAIN=app.js
MEMORY=512
VERSION=recommended
DISPLAY_NAME=My Fastify API
SUBDOMAIN=my-fastify-api

Square Cloud 会使用 node app.js 启动你的 API。通过控制面板上传时，请将 app.js 设为主文件。

ZIP 中包含哪些文件

app.js 和你的其他源代码文件。
package.json。
squarecloud.app。

不要包含 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 的服务器永远收不到请求。

后续步骤

环境变量

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

自定义域名

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

故障排除

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

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

联系我们

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

Bots

网站

API 与后端

数据库

自托管应用

指南

迁移指南

简介

前置条件

创建项目

端口和主机

配置 Square Cloud

ZIP 中包含哪些文件

部署并验证

通过控制面板

通过 CLI

配置文件指南

常见错误

自定义域名

最低内存要求

找不到此站点。

站点响应超时……

后续步骤

环境变量

自定义域名

故障排除

联系我们

​简介

​前置条件

​创建项目

​端口和主机

​配置 Square Cloud

​ZIP 中包含哪些文件

​部署并验证

​通过控制面板

​通过 CLI

配置文件指南

​常见错误

​自定义域名

​最低内存要求

​找不到此站点。

​站点响应超时……

​后续步骤

环境变量

自定义域名

故障排除

​联系我们

简介

前置条件

创建项目

端口和主机

配置 Square Cloud

ZIP 中包含哪些文件

部署并验证

通过控制面板

通过 CLI

常见错误

自定义域名

最低内存要求

找不到此站点。

站点响应超时……

后续步骤

联系我们