Skip to main content

​
简介

要在 Square Cloud 上开发和托管 ，遵循一套结构化的配置和前置条件流程至关重要。本技术指南将涵盖整个过程，从初始设置到生产环境部署。

​
前置条件

  • Square Cloud 账户：通过注册页面使用你的邮箱进行注册。
  • 有效的付费套餐：为你的应用提供专属资源和优化的性能。查看我们可用的套餐，选择最适合你需求的方案。

​
创建项目

在开始之前，请确保你的系统上已安装 Node.js 和 npm。 如果尚未安装，可以从 Node.js 官方网站 下载。 要创建一个新的 Vite 项目，请运行以下命令：
在上面的命令中，my-vite-app 是你的新项目的名称。请将其替换为你想要的任意项目名称。默认情况下，此命令会创建一个使用 JavaScript 的 Vite 项目。

​
选择特定模板

Vite 允许你为项目选择不同的模板。在创建新项目时，你可以使用 --template 选项指定所需的模板。以下是一些示例： 选择一个模板，例如：react、vue 和 lit。
选择最适合你需求的模板，并根据需要调整项目名称。

​
理解 JavaScript 与 TypeScript 的区别

当你选择 JavaScript 时，Vite 会以默认的 JavaScript 设置来配置项目。另一方面，当你选择 TypeScript 时，Vite 会以 TypeScript 设置来配置项目，包括生成一个 tsconfig.json 文件。

​
构建项目

在上传到生产环境之前，使用 Vite 构建来生成生产产物：
要在本地提供生产版本（对于在部署环境中进行测试很有用），我们推荐使用 vite preview 命令，将应用暴露在所有网络接口和 80 端口上：
你也可以在 package.json 中添加一个脚本来简化操作：
注意：在某些系统上，80 端口需要特殊权限。如果存在限制，请使用其他端口（例如 8080）并在主机/服务上进行映射。

​
选择生产服务器

对于生产环境，你基本上有两种选择：
  • 使用我们的静态 HTML/CSS 运行时，只需将 index.html 重命名为 vite.html。
  • 使用 vite preview 本身（对于测试生产行为，或在直接运行 Node 进程的容器中很有用）。

​
HTML/CSS 运行时

如果你选择静态运行时，请生成构建（npm run build），并将 dist/ 的内容复制到要发送给 Square Cloud 的压缩 zip 文件中。 记得将 index.html 重命名为 vite.html，以便运行时能正确将初始文件识别为 Vite 应用并进行正确的资源处理。

​
在生产环境（或容器中）使用 vite preview

vite preview 提供由 vite build 生成的文件，其行为类似于生产环境的静态服务器。要将应用暴露到网络（例如，在 Square Cloud 上的容器内），请使用：
这会使进程监听所有网络接口（0.0.0.0）和 80 端口。

​
带有 preview 选项的 vite.config.js 示例

​
部署

在准备好项目文件后，你可以将它们发送到 Square Cloud 并托管你的项目。 为此，请创建一个包含所有项目文件的 ZIP 文件。

​
通过控制面板

1

访问上传页面

访问上传页面并上传你的项目 zip 文件。
2

配置你的环境

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

部署你的项目

最后，点击 “Deploy” 按钮，即可将项目托管到 Square Cloud。
部署完成后，你可以在控制面板中监控项目的状态和日志。
正在上传应用到 Square Cloud
4

确认你的应用已上线

首次部署通常在一分钟内完成。在控制面板中，等待你的应用状态显示为运行中，并检查日志中是否有启动错误。
如果你部署的是网站或 API，请在浏览器中打开 https://<your-subdomain>.squareweb.app，你应该能看到应用正常响应。如果你部署的是机器人，发送一条命令确认它已上线。
应用无法启动？请参见故障排除指南，了解最常见的原因和解决方法。

​
通过 CLI

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

配置文件指南

了解如何创建定义你应用环境的 squarecloud.app 配置文件。
1

安装 CLI

首先，你的环境中需要已安装 CLI。如果尚未安装，请在终端中运行以下命令：
如果你已经安装，我们建议对其进行更新。为此，请在终端中运行以下命令：
2

进行身份验证

现在，要进行身份验证并使用其他 CLI 命令，你可以在此处点击 “Request API Key” 找到你的授权密钥。获取授权密钥后，运行以下命令：
3

上传你的项目

最后，要使用 CLI 将应用部署到 Square Cloud，你需要运行以下命令：
或者，如果你手动创建了 zip 文件，可以使用：
4

确认你的应用已上线

首次部署通常在一分钟内完成。直接在终端中检查你的应用状态和日志：
如果你部署的是网站或 API，请在浏览器中打开 https://<your-subdomain>.squareweb.app，你应该能看到应用正常响应。如果你部署的是机器人，发送一条命令确认它已上线。
应用无法启动？请参见故障排除指南，了解最常见的原因和解决方法。

​
故障排查

​
自定义域名

若要使用自定义域名（例如 mysite.com）来代替默认 URL mysite.squareweb.app，你需要 Standard 计划或更高等级。子域名由配置文件中的 SUBDOMAIN 字段定义。

​
最低内存要求

简单网站/API 的最低要求为 512MB RAM。对于使用框架的站点（Next.JS、React、Vue、Angular 等），我们始终建议至少 1GB RAM。对于更大型的应用，请分配更多 RAM，以防止应用内存耗尽而崩溃。

​
找不到此站点。

请检查子域名/域名是否与 SUBDOMAIN 字段或自定义域名设置中配置的内容一致。如果你刚上传站点，请等待最多 60 秒，让 Square 启用首次访问。

​
站点响应超时……

请检查你是否在应用中正确配置了端口 80 和主机 0.0.0.0。我们建议使用 Square 强制注入的环境变量：来自 .env 文件的 PORT 和 HOST。

​
更多资源

有关 Vite 及其工具的更多信息，请访问 Vite 官方文档。你可以在那里找到详细的指南、教程和 API 文档，帮助你充分利用 Vite。

​
联系我们

如果你仍然遇到技术问题，我们的专业支持团队可以为你提供帮助。联系我们，我们很乐意协助你解决任何问题 —— 支持质量正是开发者给予 Square Cloud 4.9/5 评分（共 402 条评价）（Google 与 Trustpilot）的重要原因之一。