简介
要在 Square Cloud 上开发和托管 Phoenix 应用，遵循一套结构化的配置和前置条件流程至关重要。本技术指南将涵盖整个过程，从初始设置到生产环境部署。前置条件
本指南运行在 Elixir 运行时上。创建项目
你的电脑上需要安装 Erlang/OTP 和 Elixir。如果尚未安装，请参阅 Elixir 官方安装指南。安装 Phoenix 项目生成器并创建项目：--no-ecto 会创建一个不带数据库的项目，这是最容易部署的配置。如果需要 Ecto，请去掉该选项，然后参阅环境变量来设置数据库地址。启动开发服务器：
http://localhost:4000。
构建生产版本
Square Cloud 会在应用启动时构建它：在运行你的START 命令之前，它会用 mix deps.get 获取依赖。随后，下面的 START 命令会以生产模式（MIX_ENV=prod）编译应用，用 mix assets.deploy 构建并摘要化资源，然后启动服务器。你无需在自己的电脑上构建任何内容，ZIP 中存放的是项目源代码。
首次启动会编译依赖并下载资源工具（esbuild 和 Tailwind），因此需要几分钟。之后的启动会复用已编译的文件。
端口和主机
无需任何修改：在生产环境中，生成的config/runtime.exs 会读取 PORT 环境变量（Square Cloud 将其设为 80），并监听所有网络接口。
环境变量
在控制面板中或使用squarecloud app env set 设置以下环境变量：
配置 Square Cloud
在项目根目录创建squarecloud.app 文件：
squarecloud.app
MAIN=mix.exs 告诉 Square Cloud 该项目运行在 Elixir 上，START 则替换默认的 mix run --no-halt。mix phx.server 会启动 Web 服务器，因此你不需要 PHX_SERVER。使用 Ecto 的项目可以在 mix phx.server 之前加上 MIX_ENV=prod mix ecto.migrate && ，在每次启动时执行迁移。
ZIP 中包含哪些文件
mix.exs和mix.lock。config/、lib/、assets/、priv/以及其他源代码文件夹。squarecloud.app。
_build/（其中是为你的电脑编译的文件）和 deps/：Square Cloud 会重新获取依赖，并在 Linux 上编译所有内容。
更喜欢使用 release？在 Windows 或 macOS 上构建的 release 无法在运行 Linux 的 Square Cloud 上运行：请在 Linux 上构建，例如在 WSL 中。它的启动脚本是
_build/prod/rel/my_app/bin/my_app，因此命令为 START=PHX_SERVER=true _build/prod/rel/my_app/bin/my_app start；PHX_SERVER=true 会让 release 启动 Web 服务器。请在 ZIP 中保留 mix.exs 和 mix.lock，因为 Square Cloud 会在 START 之前运行 mix deps.get。部署并验证
通过控制面板
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 的服务器永远收不到请求。environment variable SECRET_KEY_BASE is missing
按照环境变量中的说明设置SECRET_KEY_BASE，然后重启应用。
LiveView 不断重新连接
PHX_HOST 与浏览器中的地址不一致。请将其设置为你的子域名或自定义域名，然后重启应用。
后续步骤
环境变量
将密钥和设置放在代码之外，并在运行时读取。
自定义域名
在 Standard 及以上计划中，用你自己的域名提供应用。
故障排除
修复无法启动的应用或没有响应的站点。