> ## 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.

# 在 Square Cloud 上使用 Deno 快速开始

> 了解如何在 Square Cloud 上使用 Deno 快速开始

## 🚀 简介

* 在开始之前，您可以选择在项目中使用 Deno 运行时。如果您本地还没有安装 Deno，可以有两种主要方案：

* 通过 npm 安装（推荐，以便在 deploy 期间与 `npx` 兼容）：

```bash theme={null}
npm install deno
```

* 或者通过官方安装程序安装 Deno（请查阅 Deno 文档以获取原生安装说明）。

* 通过将 `deno` 添加为依赖项，您就可以在 `squarecloud.app` 的 `START` 字段中使用 `npx deno` 来用 Deno 启动您的应用程序。有关 `START` 的示例，请参见下文“启动应用程序”部分。

* 接下来，您需要在 Square Cloud 上创建一个账户，可以通过[登录页面](https://squarecloud.app/zh/signup)完成。您可以使用邮箱、GitHub 或两者结合来创建账户。

* 最后，您的账户需要拥有一个有效的付费套餐。您可以在[这里](https://squarecloud.app/zh/pricing)查看我们的套餐并根据需要购买。

## ⚙️ squarecloud.app 文件配置

<Note>
  如果你通过 Square Cloud 网站上传应用，可以忽略本节内容。网站会自动为你创建 `squarecloud.app` 配置文件。
</Note>

<Card title="了解更多：如何为 Square Cloud 创建配置文件。" icon="link" href="https://docs.squarecloud.app/zh/getting-started/config-file">
  squarecloud.app 文件是一个配置文件，用于配置你的应用；它用来定义名称、描述、
  版本、主文件等内容。
</Card>

## ▶️ 如何启动您的应用程序

* 若要在 Square Cloud 的 Node.js 环境中使用 Deno 运行时，请先将 `deno` 包添加到您的项目中（例如 `npm install deno`），以便运行时环境中可以使用 `npx deno` 命令。
* 然后，在您的 `squarecloud.app` 中设置 `START` 字段，填入使用 Deno 启动应用程序的命令。示例：

```squarecloud.app OR .config theme={null}
START=npx deno run --allow-net --allow-env main.ts
```

如果您使用在 `deno.json` 中定义的任务，可以这样启动：

```
START=npx deno task start
```

* 请根据您应用程序的需要调整权限（`--allow-net`、`--allow-env`、`--allow-read` 等）。

* 请记住：如果定义了 `START` 字段，其中的值将被直接执行。有关配置文件参数的更多信息，请访问[配置参数](https://docs.squarecloud.app/zh/getting-started/config-file#configuration-parameters)。

* 如果您在 Deno 中使用 npm 模块且 `node_modules` 文件夹不存在，Square Cloud 将运行 `npm install --no-package-lock --no-audit --no-fund` 来安装依赖并清理 `.npm` 文件夹。

如果您打算将 Deno 作为运行时使用，我们建议将 `deno` 添加为依赖项（`npm install deno`），以确保在 deploy 期间运行时环境中可以使用 `npx deno`。在您更倾向于使用原生 Deno 安装程序的项目中，请在采用此方案前检查兼容性和您的构建需求。

## 🖥️ 准备项目

### 📁 必要的配置文件

在为在 Square Cloud 上 deploy 准备您的 Deno 项目时，请确保将配置文件（`squarecloud.app/.config`）和您应用程序的必要文件包含在一个 zip 文件中。

<Warning>配置文件（`squarecloud.app/.config`）必须位于 zip 文件的根目录下。否则，Square Cloud 将无法在 deploy 期间找到它。</Warning>

#### 🗑️ 上传前需排除的文件

* `node_modules`：仅在您使用 npm 模块时才需要；否则请勿上传，以减小上传体积。
* `package-lock.json`：当检测到使用 npm 时，生产环境将根据 `package.json` 安装依赖。
* `deno_dir` 或 `.cache/deno`：Deno 缓存目录；deploy 不需要。

### 🤔 为什么要排除这些文件？

在上传项目前排除 `node_modules`、`package-lock.json` 和 Deno 缓存有以下几个原因：

1. **安装一致性：** 不上传 `node_modules` 可确保依赖由生产环境安装，从而得到一致的构建结果，避免本地系统的差异。

2. **最新的安装：** 生产环境将安装 `package.json` 中列出的依赖的最新兼容版本（如适用），或使用 `deno.json` 中定义的远程导入。

3. **减小上传体积：** 不包含这些目录可减小上传文件的体积，加快上传过程，使 deploy 更加高效。

这样做，您就能确保您的 Deno 应用程序为在 Square Cloud 上托管做好了最佳准备。

### 📄 必需文件

托管您的 Deno 项目需要以下三个文件：

* [squarecloud.app/.config](https://docs.squarecloud.app/zh/getting-started/config-file)
* mainFile.ts/.js（主文件示例）
* deno.json 或 deno.jsonc（权限和任务的定义）。如果使用 npm 模块，还需包含 [package.json](./how-to-create-your-package-json)。

## 💡 故障排查

<AccordionGroup>
  <Accordion title="主文件无效或已损坏" icon="file" iconType="solid">
    当在配置文件中被定义为应用程序 "main" 的文件不存在、拼写错误或路径
    有误时，就会出现此错误。例如，如果您的主文件位于某个文件夹内，
    您必须填写 `folder/file.ts` 或 `folder/file.js`。
  </Accordion>

  <Accordion title="内存不足" icon="memory" iconType="solid">
    托管一个机器人所需的最低 RAM 为 256MB，而托管一个
    网站/API 则为 512MB。不过，视您应用程序的规模和复杂度而定，
    可能建议分配更大的 RAM，以避免应用程序耗尽内存并崩溃。
  </Accordion>
</AccordionGroup>

## 📤 如何托管您的项目

现在您已经为 Deno 项目准备好了所有文件，下一步就是将它们上传到 Square Cloud 并让您的应用程序上线。上传方式有多种，我们将介绍其中两种：通过控制面板或通过 CLI。

### 通过控制面板

<Steps>
  <Step title="访问上传页面">
    访问[上传页面](https://squarecloud.app/zh/dashboard/new)并上传你的项目 zip 文件。
  </Step>

  <Step title="配置你的环境">
    上传 zip 后，你需要为项目配置名称、主文件或运行时环境以及其他设置。\
    如果你上传的是 Web 项目，请务必选择 "Web Publication" 并为项目设置子域名。
  </Step>

  <Step title="部署你的项目">
    最后，点击 "Deploy" 按钮，即可将项目托管到 Square Cloud。\
    部署完成后，你可以在控制面板中监控项目的状态和日志。

    <Frame>
      <img src="https://cdn.squarecloud.app/docs/articles/dashboard/uploading.gif" alt="正在上传应用到 Square Cloud" style={{ borderRadius: "0.2rem" }} />
    </Frame>
  </Step>
</Steps>

### 通过 CLI

要使用此方法，你需要在项目根目录中创建一个名为 `squarecloud.app` 的配置文件。该文件将包含项目所需的配置。

<Card title="了解更多：如何为 Square Cloud 创建配置文件。" icon="link" href="/zh/getting-started/config-file">
  squarecloud.app 文件是一个配置文件，用于配置你的应用；它将用于定义你的环境。
</Card>

<Steps>
  <Step title="安装 CLI">
    首先，你的环境中需要已安装 CLI。如果尚未安装，请在终端中运行以下命令：

    ```
    npm install -g @squarecloud/cli
    ```

    如果你已经安装，我们建议对其进行更新。为此，请在终端中运行以下命令：

    <Tabs>
      <Tab title="Windows">
        ```bash theme={null}
        squarecloud update
        ```
      </Tab>

      <Tab title="Linux、macOS 和 WSL">
        ```bash theme={null}
        curl -fsSL https://cli.squarecloud.app/install | bash
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="进行身份验证">
    现在，要进行身份验证并使用其他 CLI 命令，你可以在[此处](https://squarecloud.app/zh/account/security)点击 "Request API Key" 找到你的授权密钥。获取授权密钥后，运行以下命令：

    ```bash theme={null}
    squarecloud auth login
    ```
  </Step>

  <Step title="上传你的项目">
    最后，要使用 CLI 将应用部署到 Square Cloud，你需要运行以下命令：

    ```bash theme={null}
    squarecloud upload 
    ```

    或者，如果你手动创建了 zip 文件，可以使用：

    ```bash theme={null}
    squarecloud upload --file <path/to/zip> 
    ```
  </Step>
</Steps>

## 联系我们

如果你仍然遇到**技术问题**，我们的**专业支持团队**可以为你提供帮助。[**联系我们**](https://squarecloud.app/zh/support)，我们很乐意协助你解决任何问题。