Skip to main content

​
什么是配置文件？

配置文件告诉 Square Cloud 如何运行你的应用：启动哪个文件、预留多少内存、使用哪个运行时版本，以及网站要发布在哪个子域名上。它是一个纯文本文件，每行一个 KEY=VALUE 键值对。
squarecloud.app

​
创建配置文件

在项目根目录创建一个名为 squarecloud.app 或 squarecloud.config 的文件，两个名称的作用相同。上传 zip 时，该文件必须位于 zip 的顶层，而不是某个子文件夹中，否则部署会以 MISSING_CONFIG 失败。
在 macOS 上，我们推荐使用 squarecloud.config 这个名称。
VS Code 扩展会在你输入时自动补全下面的每个键，并为无效的值加上下划线。

​
配置参数

MEMORY、VERSION 和 DISPLAY_NAME 始终必填。除非设置了 RUNTIME，否则 MAIN 也是必填的。 可修改的参数在部署后可以在控制面板中更改。更改不可修改的参数需要重新上传应用。

​
MAIN

启动应用的文件，路径相对于项目根目录。
  • 文件扩展名决定运行时：.js 在 Node.js 上运行，.ts 在 TypeScript 上运行，.py 在 Python 上运行，依此类推。
  • 该文件必须存在于你上传的内容中，且不能为空。
  • 最多 32 个字符：字母、数字、_、.、/ 和 -，不能有空格。
缺少 MAIN（且未设置 RUNTIME）会以 MISSING_MAIN 失败；文件不存在、没有扩展名或不符合上述规则时，会以 INVALID_MAIN 失败。

​
MEMORY

为应用预留的 RAM，单位为 MB。它同时决定应用的 vCPU 和带宽。
该值必须不低于你的项目类型的最低要求，且不能超过你的套餐剩余可用的 RAM。否则部署会以 INSUFFICIENT_MEMORY 失败。

​
VERSION

运行时版本：recommended 或 latest。其他任何值（包括具体的版本号）都会让部署以 INVALID_VERSION 失败。
除非你需要只有最新版本才有的功能，否则请使用 recommended。每个值对应的版本列在运行时版本表中。

​
DISPLAY_NAME

在控制面板、CLI 和 API 中显示的名称。
最多 32 个字符：不带重音的字母、数字、空格、- 和 _。其他字符（例如带重音的字母、中文或 emoji）会以 INVALID_DISPLAY_NAME 失败。

​
DESCRIPTION

应用的简短描述，最多 280 个字符（超出时为 INVALID_DESCRIPTION）。

​
AUTORESTART

在应用崩溃后自动重启它。可取 true 或 false，默认为 false，因此请为机器人以及任何必须保持在线的应用开启它。
只有同时满足以下所有条件时，才会自动重启：
  • 应用以状态码 1 退出，这是 Node.js 和 Python 中未处理错误的常见退出码。
  • 应用已经运行了至少 60 秒，因此一启动就崩溃的应用不会被循环重启。
  • 在过去一小时内没有被自动重启过。
  • 日志中没有显示重启也无法修复的错误：无效的机器人令牌、缺少模块、语法错误或 TypeScript 类型错误，或者依赖安装失败。
重启可以让应用在临时错误后保持在线，但根本的 bug 仍需要在代码中修复。另请参阅帮助中心关于自动重启的文章。

​
SUBDOMAIN

把应用发布为网站，地址为 https://<subdomain>.squareweb.app。
  • 最多 63 个字符：字母、数字和连字符，不能以连字符开头或结尾。名称会以小写形式保存。
  • 已被使用、被保留（例如 admin 或 api）或无效的名称会以 INVALID_SUBDOMAIN 失败。
  • 网站比机器人需要更多 RAM：参见最低 RAM。
  • 你的服务器必须监听 80 端口和主机 0.0.0.0（参见网站无法加载）。
请在第一次上传时就决定应用是否是网站。网站的子域名之后可以更改，但不能移除（CANNOT_SET_SUBDOMAIN）。没有设置 SUBDOMAIN 就部署的应用无法变成网站：请设置 SUBDOMAIN 后把它作为新应用重新上传。
要在你自己的域名上提供网站，请参阅帮助中心的如何设置你自己的域名。

​
RUNTIME

显式指定运行时，而不是根据 MAIN 的扩展名推断。未知的值会以 INVALID_RUNTIME 失败。
设置了 RUNTIME 后可以省略 MAIN。这种情况下，还请设置 START：大多数运行时是通过运行 MAIN 文件来启动应用的。

​
START

自定义启动命令。它会替换默认命令（默认命令运行你的 MAIN 文件）。
  • 最多 256 个字符（超出时为 INVALID_START）。
  • 在命令运行之前，依赖仍会照常安装。
  • 每次启动时都会从文件中读取该命令，因此你可以在控制面板中编辑 squarecloud.app 并重启来更改它。
只调用项目中存在的脚本。例如，如果 Express 应用的 package.json 中没有 build 脚本，START=npm run build && npm run start 就会失败。默认命令够用时，请省略 START。

​
ID

这个键不需要你自己编写。执行 squarecloud upload 后，Square Cloud CLI 会把 ID=<app ID> 添加到该文件中，让 squarecloud commit 等后续命令知道要操作哪个应用。Square Cloud 在部署时会忽略它。

​
示例

​
机器人

squarecloud.app

​
网站或 API

squarecloud.app
该网站的地址为 https://mysite.squareweb.app。

​
Next.js

需要构建步骤的框架要使用 START。这里的 MAIN 只用于选择 Node.js 运行时，所以请把它指向你实际的配置文件（例如 next.config.mjs）；构建和启动脚本来自 package.json。
squarecloud.app

​
后续步骤

环境变量

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

squarecloud.ignore

选择 CLI 和 VS Code 在上传时排除哪些文件。

运行时

版本、依赖文件，以及每个运行时如何启动你的应用。

故障排除

每种部署错误的含义及解决方法。