Skip to main content
Python 运行时可以运行机器人、API、网站和脚本。Square Cloud 会用 pip 安装你的依赖，并使用 Python 3 启动应用。

​
开始之前

  • 你的电脑上需要安装 Python。如果尚未安装，可以从 Python 官方网站 下载。
  • 一个 Square Cloud 账户：使用邮箱或 GitHub 注册。
  • 一个有效的计划。查看计划并选择适合你项目的计划。

​
配置 Square Cloud

如果你通过控制面板上传应用，可以跳过本节：控制面板会自动为你创建 squarecloud.app 配置文件。

配置文件参考

squarecloud.app 文件告诉 Square Cloud 如何运行你的应用：主文件、内存、运行时版本、名称，以及网站所用的子域名。
每种应用的完整配置文件：
squarecloud.app

​
Square Cloud 运行什么

  • 如果配置文件中未定义 START 字段，Square Cloud 将执行 python MAIN 来运行 MAIN 中指定的 Python 文件。如果配置文件中定义了 START 字段，则会直接执行其中的值。有关配置文件参数的更多信息，请访问配置参数。
  • 在启动应用之前，Square Cloud 会使用 pip 安装你的依赖：存在 requirements.txt 时运行 pip install -r requirements.txt，否则运行 pip install .，从你的 pyproject.toml 中读取依赖。Square Cloud 不会运行 Poetry。

​
网站和 API 的端口与主机

Square Cloud 会将 PORT 环境变量设为 80，将 HOST 设为 0.0.0.0。你的服务器必须在该端口和所有网络接口上监听：向 Uvicorn 传入 --host 0.0.0.0 --port 80，向 Gunicorn 传入 --bind 0.0.0.0:80，或在代码中读取 int(os.environ.get("PORT", 80))。请使用 Gunicorn 或 Uvicorn 等生产服务器运行 Web 应用，而不是框架自带的开发服务器。

​
准备项目

​
必需文件

  • squarecloud.app，位于 ZIP 的根目录。
  • 你的主文件，例如 main.py。
  • 一个依赖文件：requirements.txt，或者在没有 requirements.txt 时使用 pyproject.toml。两者都没有的上传会以 INVALID_DEPENDENCY 失败。
配置文件（squarecloud.app）必须位于 zip 文件的根目录中。否则，Square Cloud 在部署时将无法找到它。

​
不需要包含的文件

  • .venv：你本地的虚拟环境。Square Cloud 会自行为服务器的系统安装依赖。
  • __pycache__：Python 会重新生成的编译文件。
  • ffmpeg：它已在 Square Cloud 环境中预装。
  • poetry.lock：Square Cloud 使用 pip 安装依赖，不会运行 Poetry，因此永远不会读取此文件。

​
框架指南

Django

Flask

FastAPI

要调优生产 Web 服务器，请参阅如何使用 Gunicorn。

​
故障排除

当在配置文件中定义为应用 “main” 的文件不存在、书写错误或路径不正确时，会出现此错误。例如，如果你的主文件位于某个文件夹内，请指定 folder/file.py。
托管一个机器人所需的最低内存为 256MB，托管网站/API 则为 512MB。不过，根据应用的大小和复杂程度，可能需要分配更多的内存，以避免应用因内存耗尽而崩溃。
其他问题请参阅故障排除。

​
部署

​
通过控制面板

1

访问上传页面

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

配置你的环境

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

部署你的项目

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

确认你的应用已上线

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

​
通过 CLI

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

配置文件指南

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

安装 CLI

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

登录

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

上传你的项目

在项目文件夹中运行下面的命令。CLI 会将当前文件夹打包为 zip（排除 squarecloud.ignore 中列出的内容）并上传：
要上传你自己创建的 zip，请通过 --file 传入：
4

确认你的应用已上线

首次部署通常在一分钟内完成。直接在终端中检查你的应用状态和日志：
如果你部署的是网站或 API，请在浏览器中打开 https://<your-subdomain>.squareweb.app，你应该能看到应用正常响应。如果你部署的是机器人，发送一条命令确认它已上线。
应用无法启动？请参见故障排除指南，了解最常见的原因和解决方法。

​
后续步骤

环境变量

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

自定义域名

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

故障排除

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

​
联系我们

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