部署 Preact 应用

简介

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

前置条件

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

本指南运行在静态运行时或 Node.js 运行时上。已于 2026 年 9 月在 Node.js 24 上使用 Preact 10 和 Vite 8 测试。

创建项目

你的电脑上需要安装 Node.js 和 npm。如果尚未安装，可以从 Node.js 官方网站下载。使用官方初始化工具 create-preact 创建项目：

npm init preact

初始化工具会询问项目文件夹以及 TypeScript、路由和预渲染（SSG）等选项。你不需要安装旧版的 preact-cli。然后进入项目文件夹，如果初始化工具没有安装依赖，请手动安装：

cd <your-project-name>
npm install

使用 npm run dev 启动开发服务器，并编辑 src/index.jsx（或 src/index.tsx）来修改首页。

构建生产版本

npm run build

create-preact 项目使用 Vite 构建，Vite 会将生产文件写入 dist/ 文件夹。

选择托管方式

Preact 构建产物是一个静态站点：由任何 Web 服务器都能提供的 HTML、CSS 和 JavaScript 文件组成。请选择以下方案之一：

静态运行时（推荐）
Express 服务器
serve 包

静态运行时使用由 Square Cloud 管理的 Web 服务器来提供你的构建文件。不会运行任何 Node.js 进程，因此这是托管无服务端代码站点最轻量的方式。

构建站点

运行 npm run build。输出位于 dist 文件夹。

保持客户端路由可用

如果你的应用在浏览器中切换页面而不重新加载（客户端路由），请将 dist/index.html 重命名为 vite.html。静态运行时会用 vite.html 响应所有不是文件的路径，因此刷新 /about 这样的路由仍会加载你的应用。每个页面对应一个 HTML 文件的站点保留 index.html：此时未知路径会返回你的 404.html。请参阅静态运行时如何提供文件。

添加配置文件

在 dist 中创建 squarecloud.app 文件。指向 HTML 文件的 MAIN 会选择静态运行时：

squarecloud.app

MAIN=vite.html
MEMORY=512
VERSION=recommended
DISPLAY_NAME=My website
SUBDOMAIN=mywebsite

如果保留了 index.html，请使用 MAIN=index.html。512 MB 是网站的最低内存。通过控制面板上传时，控制面板会询问这些值并为你生成该文件。

压缩构建输出

压缩 dist 的内容，而不是文件夹本身，使 squarecloud.app 位于 ZIP 的根目录。使用 CLI 时，请在 dist 内运行 squarecloud upload。

ZIP 中的所有内容都会在你的站点上公开。只上传构建输出，切勿上传源代码或 .env 文件。

大多数构建工具每次构建都会清空 dist。请在框架会原样复制到构建中的文件夹（基于 Vite 的项目中为 public/）里保留一份 squarecloud.app，或在每次构建后重复最后三个步骤。

此方案在 Node.js 运行时上运行一个小型 Express 服务器。请将 Express 安装为常规依赖，而不是 devDependency，因为 Square Cloud 不会安装 devDependencies：

npm install express

在项目根目录创建一个 server.mjs 文件。它会提供构建输出文件夹 dist，并对其他任何路径返回 index.html，从而让客户端路由继续正常工作：

server.mjs

import express from 'express';
import path from 'node: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'));
});

// Square Cloud sets PORT=80; 0.0.0.0 accepts connections from outside the container
const port = Number(process.env.PORT) || 80;
app.listen(port, '0.0.0.0', () => console.log(`Server running on port ${port}`));

要在本地试用，请选择一个空闲端口：PORT=3000 node server.mjs。在项目根目录创建 squarecloud.app 文件。Square Cloud 会使用 node server.mjs 启动你的网站：

squarecloud.app

MAIN=server.mjs
MEMORY=512
VERSION=recommended
DISPLAY_NAME=My website
SUBDOMAIN=mywebsite

创建 ZIP 之前请先运行 npm run build。ZIP 中需要包含 server.mjs、package.json、squarecloud.app 和 dist 文件夹，不要包含 node_modules：Square Cloud 会在首次启动时安装依赖。构建工具通常属于 devDependencies，而 Square Cloud 不会安装它们，因此构建必须在你的电脑上完成。

此方案在 Node.js 运行时上运行 serve 包，无需编写任何服务器代码。请将它安装为常规依赖：

npm install serve

在 package.json 的 scripts 中，在已有脚本旁边添加一个 start:prod 脚本：

package.json

"scripts": {
  "start:prod": "serve -s dist"
}

serve -s dist 以单页应用模式提供构建输出文件夹 dist：任何不是文件的路径都会返回 index.html，从而让客户端路由继续正常工作。serve 监听所有网络接口，端口取自 PORT 环境变量，Square Cloud 会将其设为 80（在本地则回退到 3000）。在项目根目录创建 squarecloud.app 文件：

squarecloud.app

RUNTIME=nodejs
START=npm run start:prod
MEMORY=512
VERSION=recommended
DISPLAY_NAME=My website
SUBDOMAIN=mywebsite

RUNTIME=nodejs 会选择 Node.js 运行时而无需 MAIN 文件，START 则会替换默认的启动命令。创建 ZIP 之前请先运行 npm run build。ZIP 中需要包含 package.json、squarecloud.app 和 dist 文件夹，不要包含 node_modules：Square Cloud 会在首次启动时安装依赖。构建工具通常属于 devDependencies，而 Square Cloud 不会安装它们，因此构建必须在你的电脑上完成。

部署并验证

按照你所选方案中的说明创建 ZIP，然后上传：

通过控制面板

访问上传页面

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

配置你的环境

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

部署你的项目

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

确认你的应用已上线

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

应用无法启动？请参见故障排除指南，了解最常见的原因和解决方法。

通过 CLI

要使用此方法，你的项目根目录中需要有一个名为 squarecloud.app 的配置文件。它告诉 Square Cloud 如何运行你的应用。

配置文件指南

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

安装 CLI

安装 Square Cloud CLI。如果你已经安装，运行同一条命令即可更新：

curl -fsSL https://cli.squarecloud.app/install | bash

npm install -g @squarecloud/cli@latest

运行下面的命令。它会打开你的浏览器：在浏览器中批准登录后，CLI 即可使用。无需复制任何 API 密钥。如需在脚本和 CI 中使用，请参阅 CLI 身份验证。

squarecloud auth login

上传你的项目

在项目文件夹中运行下面的命令。CLI 会将当前文件夹打包为 zip（排除 squarecloud.ignore 中列出的内容）并上传：

squarecloud upload

要上传你自己创建的 zip，请通过 --file 传入：

squarecloud upload --file <path/to/zip>

确认你的应用已上线

首次部署通常在一分钟内完成。直接在终端中检查你的应用状态和日志：

squarecloud app status
squarecloud app logs

如果你部署的是网站或 API，请在浏览器中打开 https://<your-subdomain>.squareweb.app，你应该能看到应用正常响应。如果你部署的是机器人，发送一条命令确认它已上线。

应用无法启动？请参见故障排除指南，了解最常见的原因和解决方法。

常见错误

自定义域名

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

最低内存要求

网站和 API 的最低要求为 512MB RAM，足以在静态运行时上托管静态构建产物。对于在服务器上渲染页面的应用（Next.js、Nuxt、Angular SSR 等），我们建议至少 1GB RAM。对于更大型的应用，请分配更多 RAM，以防止应用内存耗尽而崩溃。

找不到此站点。

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

站点响应超时……

你的服务器必须监听端口 80 和主机 0.0.0.0。Square Cloud 会在你的应用中设置 PORT（80）和 HOST（0.0.0.0）环境变量：请在代码中读取它们，而不要硬编码其他值。只监听 localhost 或 127.0.0.1 的服务器永远收不到请求。

刷新某个路由时返回 404

你的应用使用 Preact 路由，而服务器不认识该路由。在静态运行时上，请将 index.html 重命名为 vite.html。上面的 Express 和 serve 方案已经会对未知路径返回 index.html。

后续步骤

环境变量

将密钥和设置放在代码之外，并在运行时读取。

自定义域名

在 Standard 及以上计划中，用你自己的域名提供应用。

故障排除

修复无法启动的应用或没有响应的站点。

有关 Preact 的更多信息，请参阅 Preact 官方文档。

联系我们

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

Bots

网站

API 与后端

数据库

自托管应用

指南

迁移指南

简介

前置条件

创建项目

构建生产版本

选择托管方式

部署并验证

通过控制面板

通过 CLI

配置文件指南

常见错误

自定义域名

最低内存要求

找不到此站点。

站点响应超时……

刷新某个路由时返回 404

后续步骤

环境变量

自定义域名

故障排除

联系我们

​简介

​前置条件

​创建项目

​构建生产版本

​选择托管方式

​部署并验证

​通过控制面板

​通过 CLI

配置文件指南

​常见错误

​自定义域名

​最低内存要求

​找不到此站点。

​站点响应超时……

​刷新某个路由时返回 404

​后续步骤

环境变量

自定义域名

故障排除

​联系我们

简介

前置条件

创建项目

构建生产版本

选择托管方式

部署并验证

通过控制面板

通过 CLI

常见错误

自定义域名

最低内存要求

找不到此站点。

站点响应超时……

刷新某个路由时返回 404

后续步骤

联系我们