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

# VS Code 扩展功能

> 在 VS Code 侧边栏中部署、管理和监控 Square Cloud 应用、数据库和 workspace。

## 部署

### 上传新应用

从命令面板运行 `Square Cloud: 上传新应用`，或点击侧边栏标题栏中的上传图标；账户中还没有应用时，也可以点击 **上传你的第一个应用**。

<Steps>
  <Step title="选择文件夹">
    你打开的工作区文件夹会排在最前面；**浏览...** 可以选择任何其他文件夹。
  </Step>

  <Step title="检查配置">
    该文件夹必须包含 [`squarecloud.app` 或 `squarecloud.config`](/zh/getting-started/config-file) 文件。如果没有，则不会上传任何内容，错误信息中会附上配置文件指南的链接。
  </Step>

  <Step title="确认">
    在任何内容离开你的机器之前，都会弹出对话框请你确认。
  </Step>

  <Step title="压缩并上传">
    文件夹会在应用你的忽略规则后被压缩，并实时显示文件数量；在上传开始之前，你随时可以取消。zip 文件最大为 100 MB。
  </Step>
</Steps>

通知会显示检测到的运行时，并提供 **打开控制台** 和 **复制 ID** 按钮。如果配置文件声明了 `SUBDOMAIN`，应用启动后即可通过 `https://<subdomain>.squareweb.app` 访问。

### 将更改 commit 到现有应用

打开应用的操作菜单（右键单击其卡片，或点击其 ⋯ 按钮），然后选择 **提交**。先选择之后是否重启应用，再选择一个或多个文件，或一个文件夹。文件夹会按照相同的忽略规则压缩，并放入应用中同名的文件夹内。

<Tip>*上传* 会创建一个新应用，并分配新的 ID。*提交* 会将文件发送到已存在的应用，并保留其 ID、域名和配置。</Tip>

### 忽略规则

该扩展和 [Square Cloud CLI](/zh/cli-reference/installation) 读取同一个 [`squarecloud.ignore`](/zh/getting-started/squarecloud-ignore) 文件，使用相同的 `.gitignore` 语法和相同的默认值：除非用 `!` 规则重新包含，否则 `node_modules`、`.git`、`.github`、`.vscode` 和锁文件始终会被排除。扩展不会读取你的 `.gitignore`，因为它经常列出应用运行所需的文件，例如 `.env`。

## 应用

侧边栏顶部显示你的账户：名称、套餐，以及显示套餐内存占用的 RAM 用量条。下方的每个应用都是一张卡片，带有实时状态标签（**在线**、**离线**，状态加载时显示 **检查中**，你点击的操作正在执行时显示为琥珀色）、内存用量，以及运行时的 CPU 用量。点击卡片可查看其 ID、内存、运行时、集群、域名和启动时间。

* 将鼠标悬停在卡片上会显示启动或停止、重启和日志按钮。名称旁边的星标可将应用设为收藏，并使其固定在顶部。
* **右键单击卡片，或点击其 ⋯ 按钮，即可打开完整的操作菜单**，其中的操作按用途分组，破坏性操作排在最后。
* 应用超过 10 个时，列表每次显示 10 个，并提供上一页和下一页箭头；你还可以按名称、域名或 ID 筛选，找到其中任意一个应用。
* 无法执行的操作不会显示：边缘工具只对有域名的应用显示，指标只对内存为 512 MB 或以上的应用显示。

| 操作 | 作用 |
| - | - |
| **启动**、**停止**、**重启** | 发送该操作，并持续跟踪状态，直到状态发生变化。启动正在运行的应用，或停止已停止的应用，会显示为提示信息，而不是错误。 |
| **查看日志** | 将最新日志获取到一个单独的输出通道中，并保留颜色。 |
| **切换实时流** | 在输出通道中打开应用的实时信息流；再次运行即可停止。服务器关闭连接时，扩展会自动重新连接。 |
| **查看 24 小时指标** | 以每 5 分钟一次的采样，输出过去 24 小时的 CPU、内存和网络数据，并附上最新一次采样和平均值。需要 512 MB 或以上的内存。 |
| **下载快照** | 生成一个新的 snapshot，并将 zip 保存到你选择的文件夹。大型应用生成 snapshot 可能需要几分钟：扩展会提示这一点，之后再次运行该命令即可保存。 |
| **恢复快照** | 列出已存储的 snapshot（最新的在前，并显示大小），确认后恢复你选择的那一个。 |
| **环境变量** | 列出、添加、编辑和删除变量，或在确认后清空全部变量。更改会立即生效。 |
| **关联 / 取消关联 GitHub 仓库** | 通过 [Square Cloud GitHub App](/zh/api-reference/endpoint/apps/deploy/github-app-link) 关联一个仓库和分支，这样每次 push 都会部署该应用。 |
| **边缘日志 / 错误 / 性能** | 适用于有域名的应用：选择一个时间范围（1 小时、6 小时、24 小时或 7 天），报告会在输出通道中打开。 |
| **清除边缘缓存** | 确认后清除该应用的全部边缘缓存。 |
| **删除** | 要求你输入应用名称，先创建一个用于恢复的 snapshot，然后再删除。如果该 snapshot 仍在生成中，则不会删除任何内容，并提示你几分钟后重试。 |

## 数据库

**数据库** 部分会列出你的托管数据库及其引擎和内存。右键单击某个数据库，或点击其 ⋯ 按钮，即可使用 **启动**、**停止**、**下载 TLS 证书** 和 **删除**（需输入名称确认）。证书会保存为只有你可以读取的 `.pem` 文件。

**创建数据库** 位于侧边栏的 `...` 菜单、命令面板以及空的数据库部分中。为它指定名称、引擎（`mongo`、`mysql`、`redis` 或 `postgres`）、以 MB 为单位的内存和版本。数据库一经创建，其连接 URL（包含密码）就会被复制到你的剪贴板，同时提供 **复制密码** 按钮。

<Warning>Square Cloud 只会显示一次新数据库的凭据。请将其保存在安全的地方。</Warning>

## Workspace

**工作区** 部分会显示你拥有或加入的每个 workspace，以及其成员数和应用数。右键单击某个 workspace，或点击其 ⋯ 按钮，即可 **离开** 或 **删除** 它（只有所有者可以删除）。**创建工作区** 位于侧边栏的 `...` 菜单、命令面板以及空的工作区部分中。

要加入他人的 workspace，请使用侧边栏 `...` 菜单中的 **复制我的邀请代码**。它会复制你的个人邀请代码：将其发送给 workspace 所有者，对方即可用它添加你。

## 状态与问题

* 平台健康状况显示在侧边栏底部。当 Square Cloud 报告故障时，顶部的横幅会显示相关消息，以及指向[状态页面](https://status.squarecloud.app/)的链接。
* **每种问题都有专属的插图状态：** 无法连接、因速率限制而暂停（附有自动重试倒计时）、维护中、需要重新连接的授权、意外错误，以及没有套餐的账户。每种状态都会提供对应的按钮：**重试**、**连接账户**、**服务状态** 或 **查看套餐**。
* 如果在数据已显示的情况下刷新失败，一个小横幅会提示这一点，并保留上次加载的数据。
* **状态栏项** 会显示是否已连接账户、有多少个应用在线，以及 Square Cloud 是否离线、正在暂停请求或服务降级。将鼠标悬停在其上可查看账户、套餐和服务状态；点击即可刷新。

<Frame>
  <img src="https://raw.githubusercontent.com/squarecloudofc/vscode-extension/main/resources/readme/states.png" alt="侧边栏中的插图状态：离线、带倒计时的速率限制、已过期的登录代码，以及没有套餐的账户" />
</Frame>

## 配置文件 IntelliSense

`squarecloud.app` 和 `squarecloud.config` 可获得完整的编辑器支持，无需安装任何其他内容。

<Frame>
  <img src="https://raw.githubusercontent.com/squarecloudofc/vscode-extension/main/resources/readme/intellisense.png" alt="VS Code 中的一个 squarecloud.app 文件，其中一处错误带有下划线，并显示自动补全提供的运行时列表" />
</Frame>

* **输入时即时校验：** 缺少必填键和重复的键、值的长度、不存在的 `MAIN` 文件、低于最小值或超出套餐剩余可用内存的 `MEMORY`、`SUBDOMAIN` 中的无效字符，以及未知的 `RUNTIME` 或 `VERSION` 值，都会以错误下划线标出。
* **自动补全：** 在空行上补全所有键；在 `=` 之后，为 `MAIN` 补全源文件，为 `RUNTIME` 补全运行时，为 `VERSION` 补全 `recommended` 和 `latest`，为 `AUTORESTART` 补全 `true` 和 `false`，为 `MEMORY` 补全内存大小。
* **快速修复：** 点击 `AUTORESTART`、`VERSION` 或 `RUNTIME` 行上的灯泡，即可一键设置有效值。
* **语法高亮和图标**，适用于 `squarecloud.app`、`squarecloud.config` 和 `squarecloud.ignore`。

有关每个键的说明，请参见[配置文件指南](/zh/getting-started/config-file)。