快速开始：部署你的第一个应用

本指南部署一个小型 Node.js Web 服务器，带你完整走一遍流程：三个文件、一个 zip、一次上传。机器人或其他语言的步骤也相同。

开始之前

Square Cloud 是一个付费平台，部署需要有效的套餐，这样你的项目从第一天起就运行在生产级基础设施上。创建你的账户，然后选择适合你的方案（可查看各套餐包含的内容）。

注册

如果你以前从未使用过 Square，请注册以开始使用。

创建项目

新建一个文件夹，并在其中创建以下三个文件。

编写应用

index.js 会用一条简短消息响应每个请求。它从 PORT 和 HOST 环境变量中读取端口和主机，Square Cloud 会把它们设置为 80 和 0.0.0.0：

index.js

const http = require("node:http");

const port = process.env.PORT || 3000;
const host = process.env.HOST || "0.0.0.0";

http
  .createServer((req, res) => {
    res.writeHead(200, { "Content-Type": "text/plain" });
    res.end("Hello from Square Cloud!");
  })
  .listen(port, host, () => {
    console.log(`Listening on http://${host}:${port}`);
  });

列出依赖

每个 Node.js 项目都需要一个 package.json：Square Cloud 会在启动应用之前安装其中列出的包。本示例没有依赖，但该文件必须存在，且不能为空。

package.json

{
  "name": "hello-square",
  "version": "1.0.0",
  "private": true,
  "main": "index.js",
  "scripts": {
    "start": "node index.js"
  }
}

添加配置文件

squarecloud.app 告诉 Square Cloud 要运行哪个文件、预留多少内存以及使用哪个运行时版本。SUBDOMAIN 会把应用作为网站发布在 https://<subdomain>.squareweb.app，所以请选一个还没有被占用的名称。

squarecloud.app

MAIN=index.js
MEMORY=512
VERSION=recommended
DISPLAY_NAME=Hello Square
SUBDOMAIN=hello-square-yourname

每个字段的说明见配置文件参考。VS Code 扩展会在你输入时自动补全并检查这个文件。

网站必须监听 80 端口和主机 0.0.0.0。绑定到 localhost、127.0.0.1 或其他端口（例如 3000 或 8080）的服务器无法被访问，网站会显示超时页面。像 index.js 这样读取 PORT 和 HOST，在 Square Cloud 上就能正确运行，在你自己的电脑上仍然使用 3000 端口。

要部署机器人？去掉 SUBDOMAIN，添加 AUTORESTART=true，并把令牌放在环境变量中，绝不要写在代码里。Discord 机器人教程会带你完成一个完整的机器人。

打包项目

使用 CLI 部署？可以跳过本节：squarecloud upload 会自动为你打包文件夹。

选择文件，而不是文件夹

打开项目文件夹，选中其中的所有内容。squarecloud.app 必须位于 zip 的顶层：如果你压缩的是文件夹本身，文件会落在一个子文件夹中，部署会以 MISSING_CONFIG 失败。

创建 zip

Windows
macOS
Linux

右键单击选中的文件，选择 压缩为 ZIP 文件（Windows 11），或 发送到 → 压缩(zipped)文件夹。

右键单击选中的文件并选择压缩，或在该文件夹中运行 zip -r ../app.zip .。

检查大小

zip 最大可达 100 MB。不要包含 node_modules、虚拟环境和构建缓存：依赖会在服务器上安装，而且这些文件夹在部署时本来就会被删除。

部署

在控制面板中上传 zip，或者用 CLI 一条命令完成部署。

通过控制面板

访问上传页面

访问上传页面并上传你的项目 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，你应该能看到应用正常响应。如果你部署的是机器人，发送一条命令确认它已上线。

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

应用运行后，https://hello-square-yourname.squareweb.app（换成你的子域名）会返回 Hello from Square Cloud!。

想在每次推送时自动部署？连接 GitHub 仓库，或使用 GitHub Actions 工作流。

后续步骤

配置文件

squarecloud.app 的每个字段：内存、启动命令、子域名和自动重启。

环境变量

把令牌和连接字符串存放在代码之外。

故障排除

解决上传错误、无法加载的网站和无法启动的应用。

VS Code 扩展

无需离开编辑器即可上传、commit 和查看日志。

适用于你所用语言的指南

每份指南都介绍了对应运行时的依赖文件、启动命令和常见陷阱。

服务

故障排除

Runtimes

平台

Changelog

快速开始：部署你的第一个应用

开始之前

注册

登录

创建项目

打包项目

部署

通过控制面板

通过 CLI

配置文件指南

后续步骤

配置文件

环境变量

故障排除

VS Code 扩展

适用于你所用语言的指南

JavaScript

Bun

Deno

Python

Java

Rust

Elixir

PHP

Go

C#

Ruby

HTML/CSS

​开始之前

注册

登录

​创建项目

​打包项目

​部署

​通过控制面板

​通过 CLI

配置文件指南

​后续步骤

配置文件

环境变量

故障排除

VS Code 扩展

​适用于你所用语言的指南

JavaScript

Bun

Deno

Python

Java

Rust

Elixir

PHP

Go

C#

Ruby

HTML/CSS

开始之前

创建项目

打包项目

部署

通过控制面板

通过 CLI

后续步骤

适用于你所用语言的指南