跳转到主要内容

​
简介

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

​
前置条件

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

​
创建项目

开始之前，请确保你的系统已安装 Node.js (>=20) 和 npm。如果尚未安装，请从官方 Node.js 网站下载。 使用官方初始化工具创建一个新的 Qwik 项目： 
npm create qwik@latest
按照提示选择 Qwik City（完整应用）或 Qwik App（静态），以及你需要的任何集成。

​
安装依赖

创建完成后，进入项目目录并安装依赖： 
cd my-qwik-app
npm install
如果你选择了 Qwik City，项目将包含针对 Node、Cloudflare 等的服务器入口点和适配器。

​
开发项目

启动开发服务器： 
npm run dev
开发服务器通常运行在 http://localhost:5173（Vite 默认端口），或按初始化工具输出中显示的地址运行。 在 src/routes/index.tsx（Qwik City）中创建一个简单页面，或在 src/components/ 中创建组件： 
export default function Index() {
  return <h1>Hello from Qwik!</h1>;
}

​
构建项目

上传之前，先构建你的生产版本输出： 
npm run build
如果你使用带适配器的 Qwik City（例如 @builder.io/qwik-city/middleware/node），你的生产启动命令将指向构建后的服务器入口，通常类似于： 
node build/index.mjs
对于纯静态站点，你可以使用一个服务器。

​
选择生产服务器

要在生产环境中提供你的 Qwik 应用，你需要一个服务器。你可以创建自己的服务器，也可以使用现有的服务器。

​
Express 库

要在 Square Cloud 上部署你的静态项目，请确保服务器正确地提供静态文件。使用 Node.js 搭配 Express 时，一个常见的配置是：
server.js
import express from 'express';
import path from 'path';

const app = express();
const distPath = path.join(import.meta.dirname, 'dist');

app.use(express.static(distPath));

// SPA fallback: serve index.html for any route not matched above
app.use((req, res) => {
  res.sendFile(path.join(distPath, 'index.html'));
});

app.listen(80, () => console.log('Server running on port 80'));
请根据你的项目构建文件夹调整 dist 路径参数。如果它位于 build 或 dist 内的某个文件夹中，请改用相应的路径。

​
Serve 库

​
安装 Serve 库

要安装 serve 库，请在终端中进入你的项目目录并运行以下命令： 
npm install serve@14.2.3
此命令会安装 14.2.3 版本的 serve 库。如果你想安装最新版本，可以省略 @14.2.3。

​
配置启动脚本

安装 serve 库之后，你需要配置项目的启动脚本以使用 serve。为此，打开项目的 package.json 文件并添加一个名为 start:prod 的新脚本： 
"scripts": {
  "start:prod": "serve -s dist -l 80",
  ...
}
在 start:prod 脚本中，serve -s build -l 80 的作用如下：
  • serve：这是启动 serve 服务器的命令。
  • -s dist：-s 选项以单页应用模式提供 dist 目录。这意味着所有未找到的请求都会被重定向到 index.html。dist 目录通常在你运行 npm run build 时创建。
  • -l 80：-l 选项后跟 80，告诉 serve 监听 80 端口。80 端口是 HTTP 流量的默认端口。
请将 dist 参数调整为你的项目构建文件夹。如果它位于 build 或 dist 内的某个文件夹中，请改用该路径。

​
部署

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

​
通过控制面板

1

访问上传页面

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

配置你的环境

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

部署你的项目

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

​
通过 CLI

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

了解更多：如何为 Square Cloud 创建配置文件。

squarecloud.app 文件是一个配置文件，用于配置你的应用；它将用于定义你的环境。
1

安装 CLI

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

进行身份验证

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

上传你的项目

最后，要使用 CLI 将应用部署到 Square Cloud，你需要运行以下命令：
squarecloud upload
或者，如果你手动创建了 zip 文件，可以使用：
squarecloud upload --file <path/to/zip>

​
更多资源

有关 Qwik 的更多信息，请访问官方文档此处。

​
故障排查

​
自定义域名

若要使用自定义域名（例如 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。

​
联系我们

如果你仍然遇到技术问题，我们的专业支持团队可以为你提供帮助。联系我们，我们很乐意协助你解决任何问题。