简介
要在 Square Cloud 上开发和托管 Flask 应用，遵循一套结构化的配置和前置条件流程至关重要。本技术指南将涵盖整个过程，从初始设置到生产环境部署。前置条件
本指南运行在 Python 运行时上。已于 2026 年 9 月在 Python 3.13 上使用 Flask 3 测试。创建项目
你的电脑上需要安装 Python 和 pip。如果尚未安装，可以从 Python 官方网站 下载 Python。安装 Flask 和生产服务器 Gunicorn：app.py 文件：
app.py
PORT=5000 python app.py，然后打开 http://localhost:5000。
然后在 requirements.txt 文件中列出依赖。Square Cloud 会在启动应用之前用 pip 安装它们：
requirements.txt
选择生产服务器
app.run() 使用的 Flask 内置服务器仅用于开发。在生产环境中，请通过下面的 START 命令用 WSGI 服务器 Gunicorn 运行你的应用：app:app 表示“app.py 中的 app 对象”。
Gunicorn
Gunicorn 是一个用于 UNIX 的 Python WSGI HTTP 服务器。它采用预派生（pre-fork）工作进程模型，会派生多个工作进程来处理请求。
这使它成为在生产环境中运行 Python Web 应用的绝佳选择。
端口和主机
START 命令会将 Gunicorn 绑定到 0.0.0.0:80：即所有网络接口，以及 Square Cloud 路由到你应用的端口。app.run() 这一行也会读取 PORT，供本地运行使用。
配置 Square Cloud
在项目根目录创建squarecloud.app 文件：
squarecloud.app
MAIN=app.py 会选择 Python 运行时，START 则替换默认的 python app.py。python -m gunicorn 会运行 pip 安装的 Gunicorn，无论它位于哪个文件夹。通过控制面板上传时，请设置相同的主文件和启动命令。
ZIP 中包含哪些文件
app.py和你的其他源代码文件。requirements.txt。squarecloud.app。
.venv 和 __pycache__：Square Cloud 会自行安装你的依赖。
部署并验证
通过控制面板
1
访问上传页面
访问上传页面并上传你的项目 zip 文件。
2
配置你的环境
上传 zip 后，你需要为项目配置名称、主文件或运行时环境以及其他设置。
如果你上传的是 Web 项目，请务必选择 “Web Publication” 并为项目设置子域名。
如果你上传的是 Web 项目，请务必选择 “Web Publication” 并为项目设置子域名。
3
部署你的项目
最后，点击 “Deploy” 按钮，即可将项目托管到 Square Cloud。
部署完成后，你可以在控制面板中监控项目的状态和日志。
部署完成后，你可以在控制面板中监控项目的状态和日志。
4
确认你的应用已上线
首次部署通常在一分钟内完成。在控制面板中，等待你的应用状态显示为运行中，并检查日志中是否有启动错误。
如果你部署的是网站或 API，请在浏览器中打开
如果你部署的是网站或 API，请在浏览器中打开
https://<your-subdomain>.squareweb.app，你应该能看到应用正常响应。如果你部署的是机器人，发送一条命令确认它已上线。
通过 CLI
要使用此方法，你的项目根目录中需要有一个名为squarecloud.app 的配置文件。它告诉 Square Cloud 如何运行你的应用。
配置文件指南
了解如何创建定义你应用环境的
squarecloud.app 配置文件。1
安装 CLI
安装 Square Cloud CLI。如果你已经安装，运行同一条命令即可更新：
2
登录
运行下面的命令。它会打开你的浏览器：在浏览器中批准登录后，CLI 即可使用。无需复制任何 API 密钥。如需在脚本和 CI 中使用，请参阅 CLI 身份验证。
3
上传你的项目
4
确认你的应用已上线
首次部署通常在一分钟内完成。直接在终端中检查你的应用状态和日志：如果你部署的是网站或 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 的服务器永远收不到请求。No module named gunicorn
requirements.txt 中缺少 gunicorn。请添加它并重新上传该文件。
后续步骤
环境变量
将密钥和设置放在代码之外，并在运行时读取。
自定义域名
在 Standard 及以上计划中，用你自己的域名提供应用。
故障排除
修复无法启动的应用或没有响应的站点。