简介
要在 Square Cloud 上开发和托管 X (Twitter) 机器人,遵循一套结构化的配置和前置条件流程至关重要。本技术指南将涵盖整个过程,从初始设置到生产环境部署。前置条件
本指南运行在 Node.js 运行时上。创建项目
身份验证和机器人操作需要一个有效的 X (Twitter) 账户。如果你还没有账户,请在 X 官方网站 注册。访问 API 还需要一个 X 开发者账户。请通过 X 开发者门户 申请访问权限。
在 X 上创建机器人应用
1
打开开发者门户
- 前往 X 开发者门户。
- 使用你的 X (Twitter) 账户登录。
- 如果这是你第一次使用,请完成开发者访问申请流程。
2
创建项目
- 在控制面板中,点击 “Create Project”。
- 为你的项目选择一个名称(例如 “Square Cloud Bot”)。
- 选择最合适的用例(例如 “Making a bot”)。
- 提供机器人的详细描述。
- 确认创建项目。
3
创建应用
- 在已创建的项目中,点击 “Create App”。
- 为你的应用定义一个唯一的名称。
- 确认创建应用。
- 记下生成的 App ID 以备后续参考。
4
生成 API 密钥
- 导航到应用的 “Keys and tokens” 部分。
- 在 “Consumer Keys” 部分,点击 “Regenerate” 以生成:
- API Key (Consumer Key)
- API Secret Key (Consumer Secret)
- 重要:请立即复制并保存这些密钥,因为你将无法再次查看它们。
5
设置应用权限
- 前往 “App permissions” 部分。
- 点击 “Edit” 以修改权限。
- 选择 “Read and write” 以允许你的机器人发布推文。
- 如有必要,选择 “Read and write and Direct message” 以启用私信功能。
- 保存更改。
6
生成访问令牌
- 返回 “Keys and tokens” 部分。
- 在 “Access Token and Secret” 部分,点击 “Generate”。
- 确认生成令牌。
- 复制并保存:
- Access Token
- Access Token Secret
- 警告:关闭页面后,这些令牌将无法再次查看。
7
检查你的凭据
- 确认你拥有全部 4 个所需凭据:
- API Key (Consumer Key)
- API Secret Key (Consumer Secret)
- Access Token
- Access Token Secret
- 将这些凭据存储在安全的位置
- 重要:切勿公开分享或暴露这些凭据
开发机器人
- Node.js 检查:确认你的系统已安装 Node.js。如果没有,请从 Node.js 官方网站 下载。
- 项目初始化:运行以下命令创建一个新的 Node.js 项目:
Terminal
- 安装依赖:安装机器人所需的库:
Terminal
- 凭据:代码从环境变量读取这四个凭据,因此它们永远不会出现在代码中。要在你的电脑上测试机器人,请将它们放入
.env文件,并使用node --env-file=.env index.js启动机器人:
.env
- 创建主文件:编写包含机器人基础结构的
index.js文件:
index.js
配置 Square Cloud
在项目根目录、index.js 旁边创建 squarecloud.app 文件。它告诉 Square Cloud 如何运行你的机器人:
squarecloud.app
MEMORY是机器人的内存(单位 MB)。机器人至少需要 256 MB;512 MB 则留有增长空间。AUTORESTART=true会在机器人崩溃时重新启动它。请参阅自动重启的工作方式。- 没有
SUBDOMAIN:机器人调用 X API,不提供网页。
设置凭据
安全提示:切勿将 API 凭据直接写入代码中。始终在 Square Cloud 上使用环境变量。
API_KEY:你的 X API 密钥API_SECRET_KEY:你的 X API 密钥密文ACCESS_TOKEN:你的访问令牌ACCESS_TOKEN_SECRET:你的访问令牌密文
- 控制面板:在上传页面打开 Advanced configuration 并添加这四个变量。对于已部署的机器人,请在应用的 Environment Variables 页面添加它们,然后重启机器人。
- CLI:上传机器人后(参见部署并验证),立即使用
squarecloud app env set从本地.env文件加载它们并重启机器人:
ZIP 中包含什么
index.js和其他源文件。package.json。squarecloud.app。
node_modules:Square Cloud 会在机器人启动时安装依赖。也不要包含你的 .env 文件:如果你使用 CLI 上传,请在 squarecloud.ignore 文件中添加一行 .env,让 CLI 跳过它。
部署并验证
创建上面所述的 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,你应该能看到应用正常响应。如果你部署的是机器人,发送一条命令确认它已上线。
测试机器人
部署完成后,在 Square Cloud 控制面板中检查应用日志,确认出现Bot successfully initialized! 消息,以确认机器人已正确通过身份验证。然后用另一个账户发布一条带有 !ping 并提及该机器人的推文(例如 @your_bot !ping),并确认它在几分钟内在 X 上回复 Pong! 🤖 X Bot working correctly!。机器人启动之前发布的提及会被跳过。
常见错误
Request failed with code 401
日志中显示Error verifying bot:,后面跟着这个错误。四个凭据之一错误或缺失。请从 “Keys and tokens” 部分重新复制它们,设置这四个变量,然后重启机器人。
回复时出现 Request failed with code 403
机器人能通过身份验证,但无法发布内容。访问令牌是在应用只有只读权限时生成的。请在应用权限中设置 “Read and write”,重新生成 Access Token and Secret,更新ACCESS_TOKEN 和 ACCESS_TOKEN_SECRET,然后重启机器人。
Request failed with code 429
机器人达到了 X API 的速率限制。请等待一段时间再发送下一个请求,并按照速率限制中的方式分散调用。进阶
下面的代码片段用于扩展index.js:将它们添加到文件中,并在机器人需要的地方调用。
话题标签监控
定时发布
速率限制
X (Twitter) 有严格的速率限制。请实现相应的控制以避免超出这些限制:错误处理
后续步骤
应用无法启动
修复缺少模块、内存错误和其他启动失败问题。
环境变量
管理机器人的凭据和其他密钥。
Node.js 运行时
Square Cloud 如何运行 Node.js 应用。

