简介
要在 Square Cloud 上开发和托管 WhatsApp 机器人,遵循一套结构化的配置和前置条件流程至关重要。本技术指南将涵盖整个过程,从初始设置到生产环境部署。前置条件
本指南运行在 Node.js 运行时上。创建项目
你需要在手机上安装 WhatsApp,才能将机器人链接到你的账户。如果你还没有该应用,请访问 WhatsApp 官方网站 下载并设置。- Node.js 检查:确认你的系统已安装 Node.js。否则,请从 Node.js 官方网站 下载。
- 项目初始化:运行初始化命令来搭建一个新的 Node.js 项目:
Terminal
- 安装依赖:安装机器人功能所需的核心库:
Terminal
开发机器人
编写包含机器人基础结构的index.js 文件:
index.js
配置 Square Cloud
在项目根目录、index.js 旁边创建 squarecloud.app 文件。它告诉 Square Cloud 如何运行你的机器人:
squarecloud.app
MEMORY是机器人的内存(单位 MB)。whatsapp-web.js 会运行一个无头 Chromium 浏览器,因此至少分配 1024 MB。AUTORESTART=true会在机器人崩溃时重新启动它。请参阅自动重启的工作方式。- 没有
SUBDOMAIN:机器人不提供网页。
ZIP 中包含什么
index.js和其他源文件。package.json。squarecloud.app。
node_modules:Square Cloud 会在机器人启动时安装依赖。也不要包含在你电脑上运行时生成的 .wwebjs_auth 和 .wwebjs_cache 文件夹,这样机器人会在 Square Cloud 上链接自己的会话。如果你使用 CLI 上传,请在 squarecloud.ignore 文件中列出这两个文件夹。
部署并验证
创建上面所述的 ZIP,然后上传:通过控制面板
1
访问上传页面
访问上传页面并上传你的项目 zip 文件。
2
配置你的环境
上传 zip 后,你需要为项目配置名称、主文件或运行时环境以及其他设置。
如果你上传的是 Web 项目,请务必选择 “Web Publication” 并为项目设置子域名。
如果你上传的是 Web 项目,请务必选择 “Web Publication” 并为项目设置子域名。
3
部署你的项目
最后,点击 “Deploy” 按钮,即可将项目托管到 Square Cloud。
部署完成后,你可以在控制面板中监控项目的状态和日志。
部署完成后,你可以在控制面板中监控项目的状态和日志。

4
确认你的应用已上线
首次部署通常在一分钟内完成。在控制面板中,等待你的应用状态显示为运行中,并检查日志中是否有启动错误。
如果你部署的是网站或 API,请在浏览器中打开
如果你部署的是网站或 API,请在浏览器中打开
https://<your-subdomain>.squareweb.app,你应该能看到应用正常响应。如果你部署的是机器人,发送一条命令确认它已上线。
通过 CLI
要使用此方法,你的项目根目录中需要有一个名为squarecloud.app 的配置文件。它告诉 Square Cloud 如何运行你的应用。
配置文件指南
了解如何创建定义你应用环境的
squarecloud.app 配置文件。1
安装 CLI
安装 Square Cloud CLI。如果你已经安装,运行同一条命令即可更新:
2
登录
运行下面的命令。它会打开你的浏览器:在浏览器中批准登录后,CLI 即可使用。无需复制任何 API 密钥。如需在脚本和 CI 中使用,请参阅 CLI 身份验证。
3
上传你的项目
4
确认你的应用已上线
首次部署通常在一分钟内完成。直接在终端中检查你的应用状态和日志:如果你部署的是网站或 API,请在浏览器中打开
https://<your-subdomain>.squareweb.app,你应该能看到应用正常响应。如果你部署的是机器人,发送一条命令确认它已上线。
链接你的 WhatsApp 账户
在 Square Cloud 控制面板中打开应用日志。首次启动时,机器人会在日志中打印一个二维码:在手机上打开 WhatsApp,进入 Linked devices > Link a device 并扫描它。出现WhatsApp client successfully initialized! 消息即确认会话已激活。然后从另一个号码向已链接的 WhatsApp 账户发送 !ping,并确认它回复 pong - Bot working correctly!。
LocalAuth 会将会话保存在 .wwebjs_auth 文件夹中,因此重启后无需新的二维码即可重新连接。要链接另一个号码,请删除该文件夹并重启应用。
常见错误
无法扫描二维码
二维码是用文本字符绘制的,而且 WhatsApp 会定期更换它,所以请扫描最新的那一个。如果手机无法识别,请缩小页面直到整个二维码都显示在屏幕上,或将控制面板切换为深色主题。WhatsApp Web 更新后无法登录
使用npm install whatsapp-web.js@latest 更新该库并重新部署。避免通过 webVersionCache 选项固定旧的 WhatsApp Web 版本:过时的版本往往会导致登录失败。
机器人内存不足
whatsapp-web.js 会运行一个无头 Chromium 浏览器,它需要内存。请将MEMORY 保持在 1024 MB 或以上,或者改用无需浏览器即可运行的 Baileys。
使用 Baileys 代替 whatsapp-web.js
Baileys 是一个替代库,它通过 WebSocket 直接连接到 WhatsApp 的多设备 API,无需启动无头浏览器。由于没有 Chromium/Puppeteer 实例需要运行,它比 whatsapp-web.js 使用的内存明显更少。 Baileys 通过useMultiFileAuthState 将会话(creds.json 文件和密钥)保存在 auth 文件夹中。Square Cloud 会在重启之间保留你应用的文件,因此只有在你退出登录或删除该文件夹后,才需要重新扫描二维码。与 .wwebjs_auth 一样,不要把本地的 auth 文件夹放进 ZIP。
- 安装该库:
Terminal
- 使用
makeWASocket和useMultiFileAuthState创建一个index.js文件,用于加载和持久化会话:
index.js
MEMORY 值:
squarecloud.app
后续步骤
应用无法启动
修复缺少模块、内存错误和其他启动失败问题。
Evolution API
运行一个可同时管理多个实例的 WhatsApp API。
机器人托管
了解 Square Cloud 为 7×24 小时运行的机器人提供的服务。

