简介
要在 Square Cloud 上开发和托管 Django 应用,遵循一套结构化的配置和前置条件流程至关重要。本技术指南将涵盖整个过程,从初始设置到生产环境部署。前置条件
本指南运行在 Python 运行时上。已于 2026 年 9 月在 Python 3.13 上使用 Django 6 测试。创建项目
你的电脑上需要安装 Python 和 pip。如果尚未安装,可以从 Python 官方网站 下载 Python。安装库
安装 Django、生产服务器 Gunicorn,以及用于提供静态文件的 WhiteNoise:开发项目
创建一个新的 Django 项目并进入其文件夹:manage.py 以及包含 settings.py、urls.py 和 wsgi.py 的 mysite/ 包。要添加一个基础路由,请编辑 mysite/urls.py:
mysite/urls.py
为生产环境配置设置
永远不要在代码中硬编码密钥。在mysite/settings.py 中,从环境变量读取密钥和生产环境标志,信任你网站的 HTTPS 源,并启用 WhiteNoise。生成的其余设置保持不变:
mysite/settings.py
mysite.squareweb.app 替换为你的子域名或自定义域名。然后通过控制面板或使用 squarecloud app env set,在应用中设置以下环境变量:
要在本地运行项目,请在终端中设置
DJANGO_SECRET_KEY(任意值)和 DJANGO_DEBUG=True,然后运行 python manage.py runserver。manage.py 旁边的 requirements.txt 文件中列出依赖。Square Cloud 会在启动应用之前用 pip 安装它们。其中至少需要列出:
requirements.txt
选择生产服务器
Django 内置的开发服务器(runserver)不适合用于生产环境。请使用面向生产的 WSGI 服务器 Gunicorn,并由下面的 START 命令启动它。有关 worker 设置和其他选项,请参阅 Gunicorn 指南:
Gunicorn
Gunicorn 是一个用于 UNIX 的 Python WSGI HTTP 服务器。它采用预派生(pre-fork)工作进程模型,会派生多个工作进程来处理请求。
这使它成为在生产环境中运行 Python Web 应用的绝佳选择。
端口和主机
下面的START 命令会将 Gunicorn 绑定到 0.0.0.0:80:即所有网络接口,以及 Square Cloud 路由到你应用的端口。Django 本身没有需要修改的端口设置。
配置 Square Cloud
在manage.py 旁边创建 squarecloud.app 文件:
squarecloud.app
collectstatic将你的静态文件复制到STATIC_ROOT,由 WhiteNoise 从那里提供这些文件。migrate应用待执行的数据库迁移。数据库已是最新时,它不会做任何事。python -m gunicorn mysite.wsgi --bind 0.0.0.0:80在 80 端口和所有网络接口上提供mysite项目的 WSGI 应用。
MAIN=manage.py 会选择 Python 运行时。通过控制面板上传时,请设置相同的主文件和启动命令。
ZIP 中包含哪些文件
manage.py以及包含你的应用和模板的mysite/包。requirements.txt。squarecloud.app。
manage.py、requirements.txt 和 squarecloud.app 必须位于 ZIP 的根目录。不要包含 .venv、__pycache__、staticfiles/(每次启动时由 collectstatic 重新生成)以及本地的 db.sqlite3。
部署并验证
通过控制面板
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 的服务器永远收不到请求。KeyError: ‘DJANGO_SECRET_KEY’
缺少该环境变量。请按照为生产环境配置设置中的说明设置DJANGO_SECRET_KEY,然后重启应用。
Bad Request (400)
你打开的地址不在DJANGO_ALLOWED_HOSTS 中。请将你的子域名或自定义域名添加进去,然后重启应用。
后续步骤
环境变量
将密钥和设置放在代码之外,并在运行时读取。
自定义域名
在 Standard 及以上计划中,用你自己的域名提供应用。
故障排除
修复无法启动的应用或没有响应的站点。

