Skip to main content

​
简介

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

​
前置条件

  • Square Cloud 账户：通过注册页面使用你的邮箱进行注册。
  • 有效套餐：为你的应用提供专属资源和优化的性能。查看我们可用的套餐，选择最适合你需求的方案。
本指南运行在 Node.js 运行时上，生成的静态站点则运行在静态运行时上。已于 2026 年 9 月在 Node.js 24 上使用 Nuxt 4 测试。

​
创建项目

你的电脑上需要安装 Node.js 和 npm。如果尚未安装，可以从 Node.js 官方网站 下载。使用官方初始化工具创建项目（它取代了 nuxi init）：
初始化工具会询问模板和包管理器，然后安装依赖。进入项目文件夹并启动开发服务器：
开发服务器监听 http://localhost:3000。编辑 app/app.vue 来修改首页，或创建 app/pages/index.vue 来使用基于文件的路由。

​
构建生产版本

Nuxt 会使用 Nitro 将一个独立的 Node.js 服务器构建到 .output 文件夹中。其入口文件是 .output/server/index.mjs，并且 .output/server 自带所需的依赖。

​
端口和主机

Nuxt 无需任何修改：Nitro 服务器会读取 PORT 和 HOST 环境变量，Square Cloud 将它们设为 80 和 0.0.0.0。

​
配置 Square Cloud

在项目根目录创建 squarecloud.app 文件，并将 MAIN 指向 Nitro 服务器：
squarecloud.app
Square Cloud 会使用 node .output/server/index.mjs 启动它。通过控制面板上传时，请设置相同的主文件。

​
ZIP 中包含哪些文件

  • .output/，即生产构建。
  • package.json、nuxt.config.ts 以及你的源代码文件夹（app/、public/ 和项目中的其他文件夹）：首次启动时，Square Cloud 会运行 npm install，而 Nuxt 项目的 postinstall 脚本（nuxt prepare）需要这些文件。
  • squarecloud.app。
不要包含 node_modules 和 .nuxt：它们会在服务器上重新生成。

​
用静态生成代替服务器

如果所有页面都可以在构建时生成，请运行 npm run generate 代替 npm run build。Nuxt 会将一个静态站点写入 .output/public，静态运行时无需 Node.js 进程即可提供它： 静态运行时使用由 Square Cloud 管理的 Web 服务器来提供你的构建文件。不会运行任何 Node.js 进程，因此这是托管无服务端代码站点最轻量的方式。
1

构建站点

运行 npm run build。输出位于 .output/public 文件夹。
2

保持客户端路由可用

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

添加配置文件

在 .output/public 中创建 squarecloud.app 文件。指向 HTML 文件的 MAIN 会选择静态运行时：
squarecloud.app
如果保留了 index.html，请使用 MAIN=index.html。512 MB 是网站的最低内存。通过控制面板上传时，控制面板会询问这些值并为你生成该文件。
4

压缩构建输出

压缩 .output/public 的内容，而不是文件夹本身，使 squarecloud.app 位于 ZIP 的根目录。使用 CLI 时，请在 .output/public 内运行 squarecloud upload。
ZIP 中的所有内容都会在你的站点上公开。只上传构建输出，切勿上传源代码或 .env 文件。
大多数构建工具每次构建都会清空 .output/public。请在框架会原样复制到构建中的文件夹（基于 Vite 的项目中为 public/）里保留一份 squarecloud.app，或在每次构建后重复最后三个步骤。
nuxt generate 会为每个页面预渲染一个 HTML 文件并生成 404.html，因此请保留 index.html（不要重命名为 vite.html）。

​
部署并验证

​
通过控制面板

1

访问上传页面

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

配置你的环境

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

部署你的项目

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

确认你的应用已上线

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

​
通过 CLI

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

配置文件指南

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

安装 CLI

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

登录

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

上传你的项目

在项目文件夹中运行下面的命令。CLI 会将当前文件夹打包为 zip（排除 squarecloud.ignore 中列出的内容）并上传：
要上传你自己创建的 zip，请通过 --file 传入：
4

确认你的应用已上线

首次部署通常在一分钟内完成。直接在终端中检查你的应用状态和日志：
如果你部署的是网站或 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 的服务器永远收不到请求。

​
Cannot find module .output/server/index.mjs

ZIP 中缺少构建产物。请运行 npm run build，并检查 .output 文件夹是否位于 ZIP 的根目录，与 squarecloud.app 并列。

​
后续步骤

环境变量

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

自定义域名

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

故障排除

修复无法启动的应用或没有响应的站点。
有关 Nuxt 的更多信息，请参阅 Nuxt 官方文档。

​
联系我们

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