> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 如何创建你的 squarecloud.app 配置文件

> 了解如何创建你的 Square Cloud 配置文件

## 什么是配置文件？

配置文件是一个包含应用参数的文件，例如主文件、内存、版本以及其他设置。该文件用于在 Square Cloud 平台上配置和部署你的应用。

```systemd squarecloud.app theme={null}
MAIN=main_file.js
DISPLAY_NAME=I am the configuration file
MEMORY=512
VERSION=recommended
```

## 创建配置文件

创建配置文件非常简单：只需创建一个名为 `squarecloud.app` 或 `squarecloud.config` 的文件，并在其中添加配置参数即可。

<Steps>
  <Step title="选择扩展名">
    配置文件可以有两种扩展名：**.app** 或 **.config**。你可以使用 `squarecloud.app` 或 `squarecloud.config`，随你喜好。提示：使用 **.app** 有助于推广 Square Cloud。🥰😂
    <Info>在 **macOS** 上，我们推荐使用 **.config** 扩展名。</Info>
    <Warning>注意：**.app** 或 **.config** 指的是**文件扩展名**，而不是文件名。</Warning>
  </Step>

  <Step title="创建文件">
    使用所选的扩展名创建一个文件，并在其中添加配置参数。
  </Step>
</Steps>

## 配置参数

下面列出了配置文件中可用的所有配置参数。

| 参数              | 类型      | 可编辑 | 限制     | 用途                                   |
| --------------- | ------- | :-: | ------ | ------------------------------------ |
| `MAIN*`         | String  |  ❌  | 32 字符  | 定义应用的主文件。例如：`index.js`、`main.py` 等。  |
| `VERSION*`      | String  |  ❌  | -      | 语言版本（例如：`recommended`）。              |
| `MEMORY*`       | Integer |  ✅  | -      | 内存量，单位为兆字节。                          |
| `DISPLAY_NAME*` | String  |  ✅  | 32 字符  | 应用的显示名称。                             |
| `RUNTIME`       | String  |  ❌  | -      | 运行时环境。例如：`typescript`、`nodejs`、`go`。 |
| `DESCRIPTION`   | String  |  ✅  | 280 字符 | 应用的描述/元数据。                           |
| `AUTORESTART`   | Boolean |  ✅  | -      | 自动重启（`true` 或 `false`）。              |
| `START`         | String  |  ✅  | 256 字符 | 自定义启动命令。                             |
| `SUBDOMAIN`     | String  |  ✅  | 63 字符  | 网站子域名（如适用）。                          |

<Info>可编辑参数（✅）可以在部署后于控制面板中修改。不可编辑参数（❌）需要完整重新上传应用才能更改。</Info>

## 配置参数详解

下面详细说明了你可以在配置文件中使用的配置参数。

<Steps>
  <Step title="MAIN [*]" icon="file">
    **类型**：String | **可编辑**：❌ | **限制**：32 字符

    定义应用的主文件。

    ```systemd theme={null}
    MAIN=index.js
    ```

    ```systemd theme={null}
    MAIN=src/loaders/index.js
    ```

    <Info>设置此参数后，运行时环境将根据主文件的扩展名进行推断</Info>
    <Tip>如果你使用了 START 参数，此设置将被**忽略**。</Tip>
  </Step>

  <Step title="MEMORY [*]" icon="memory">
    **类型**：Integer | **可编辑**：✅ | **限制**：最低 256MB（机器人）、512MB（网站）

    定义你的应用将使用的内存量。

    ```systemd theme={null}
    MEMORY=256
    ```

    <Info>该值必须以兆字节（MB）为单位指定。</Info>
  </Step>

  <Step title="VERSION [*]" icon="arrow-up-9-1">
    **类型**：String | **可编辑**：❌ | **取值**：`recommended`、`latest` 或特定版本
    <Tip>为获得最佳稳定性，我们推荐使用 `recommended`。</Tip>

    定义应用的语言版本。

    ```systemd theme={null}
    VERSION=recommended
    ```

    | 语言                 | `recommended` | `latest` |
    | ------------------ | ------------- | -------- |
    | Node.js \[JS & TS] | 24.15.0       | 26.1.0   |
    | Python             | 3.13.13       | 3.14.5   |
    | Java               | JDK 25        | JDK 25   |
    | Elixir             | 1.19.5        | 1.19.5   |
    | Rust               | 1.95.0        | 1.95.0   |
    | Ruby               | 4.0.4         | 4.0.4    |
    | PHP                | 8.5.6         | 8.5.6    |
    | Go                 | 1.26.3        | 1.26.3   |
    | .NET/C#            | 10.0.8        | 10.0.8   |
  </Step>

  <Step title="DISPLAY_NAME [*]" icon="text">
    **类型**：String | **可编辑**：✅ | **限制**：32 字符

    定义应用的显示名称。

    ```systemd theme={null}
    DISPLAY_NAME=Admin BOT
    ```
  </Step>

  <Step title="DESCRIPTION" icon="text">
    **类型**：String | **可编辑**：✅ | **限制**：280 字符

    定义应用的描述。

    ```systemd theme={null}
    DESCRIPTION=This bot is designed to help you with your daily tasks.
    ```
  </Step>

  <Step title="AUTORESTART" icon="rotate">
    **类型**：Boolean | **可编辑**：✅ | **取值**：`true`、`false` | **默认值**：`false`

    定义应用在失败时是否应自动重启。

    ```systemd theme={null}
    AUTORESTART=true
    ```
  </Step>

  <Step title="SUBDOMAIN" icon="globe">
    **类型**：String | **可编辑**：✅ | **限制**：63 字符 | **默认值**：`undefined`

    定义你网站的子域名（仅适用于 Web 应用）。

    ```systemd theme={null}
    SUBDOMAIN=mysite
    ```

    <Note>最终 URL 将为：`mysite.squareweb.app`</Note>
  </Step>

  <Step title="RUNTIME" icon="server">
    **类型**：String | **可编辑**：❌

    手动定义运行时环境。

    ```systemd theme={null}
    RUNTIME=nodejs
    ```

    请查看下方接受的取值和环境。

    | 环境         | RUNTIME                |
    | ---------- | ---------------------- |
    | Nodejs     | `nodejs`、`javascript`  |
    | TypeScript | `typescript`           |
    | Python     | `python`               |
    | C#/Dotnet  | `c#`、`dotnet`、`csharp` |
    | Elixir     | `elixir`               |
    | Java       | `java`                 |
    | Rust       | `rust`                 |
    | Ruby       | `ruby`、`rb`            |
    | PHP        | `php`                  |
    | Golang     | `go`、`golang`          |
    | HTML/CSS   | `static`、`html`        |

    <Warning>如果设置了此参数，你就无需设置 MAIN；改为设置一个自定义的 START 命令即可。</Warning>
  </Step>

  <Step title="START" icon="play">
    **类型**：String | **可编辑**：✅ | **限制**：256 字符 | **默认值**：`undefined`

    定义自定义启动命令。

    ```systemd theme={null}
    START=npm run start
    ```

    <Warning>此参数会**覆盖**默认的 MAIN 行为。</Warning>
  </Step>
</Steps>

## 机器人配置示例

以下是一些机器人的配置示例：

```systemd theme={null}
# Required parameters.
MAIN=index.js
MEMORY=512
VERSION=recommended
DISPLAY_NAME=Robin bot
```

```systemd theme={null}
# Example with all parameters.
MAIN=index.js
MEMORY=512
VERSION=recommended
DISPLAY_NAME=Robin bot
DESCRIPTION=This bot was created to help with your daily tasks.
START=npm run start
AUTORESTART=true
```

## 网站配置示例

以下是一些网站的配置示例：

<Info>网站 URL 将为：`mysite.squareweb.app`</Info>

```systemd theme={null}
# Example with all parameters.
MAIN=index.js
MEMORY=1024
VERSION=recommended
DISPLAY_NAME=My site
DESCRIPTION=My site is really cool!
SUBDOMAIN=mysite
START=npm run build && npm run start
AUTORESTART=true
```

<Info>将 `next.config.js` 作为 MAIN 仅用于让系统将该项目识别为 JavaScript 或 TypeScript 项目（另一个 .ts/.tsx 文件）</Info>

```systemd theme={null}
# Example for a Next.js site.
MAIN=next.config.js
MEMORY=2048
VERSION=recommended
DISPLAY_NAME=Next.js site
DESCRIPTION=This site was built with Next.js.
SUBDOMAIN=nextjs
START=npm run build && npm run start
AUTORESTART=true
```