Skip to main content
不要把机器人令牌、API 密钥和数据库密码写进源代码。把它们设置为应用的环境变量，你的代码就能像读取其他变量一样在运行时读取它们。

​
设置变量

环境变量属于单个应用。它们在重启和 commit 后依然保留，但新的上传会创建一个不带这些变量的新应用，因此需要在新应用上重新设置。
  1. 在控制面板中打开你的应用，进入 Settings → Environment Variables。
  2. 添加每个键和值，或导入一个现有的 .env 文件。
  3. 点击 Save。控制面板会询问是否重启应用：请重启，让应用读取新的值。
在控制面板中上传新应用时，也可以在上传界面、首次启动之前添加变量。
变量在应用启动时加载。任何更改之后都要重启应用，否则它会继续使用旧的值运行。

​
在代码中读取

变量缺失时立即失败，可以在日志中留下清晰的消息，而不是之后出现令人困惑的错误（例如令牌无效）。

​
Square Cloud 为你设置的变量

你的应用启动时已经定义了以下变量：
不要在网站上覆盖 PORT 或 HOST：平台只能访问监听 80 端口和主机 0.0.0.0 的服务器。
由于 NODE_ENV 为 production，npm install 会跳过 devDependencies。如果你的 START 命令需要构建项目（例如使用 typescript 或 vite），请把这些构建工具列在 package.json 的 dependencies 下。

​
变量如何传递到应用

Square Cloud 把变量保存在应用内的 .squarecloud/.env 文件中，并在每次应用启动时用 shell 加载它们，时间点在安装依赖、运行 START 命令或 MAIN 文件之前。这带来两个结果：
  • 名称应使用字母、数字和下划线，且不能以数字开头。
  • 值如果包含空格或 $、&、;、| 等 shell 字符，必须加引号，否则 shell 会截断或展开它们。控制面板和 squarecloud app env set 会自动加引号。在 VS Code 扩展或 API 中，请自己用单引号包裹这类值：输入 'p@ss word$1'，或在 API 请求体中发送 "PASSWORD": "'p@ss word$1'"。
限制为每个应用 256 个变量，名称最多 1,024 个字符，值最多 4,096 个字符。静态网站（HTML/CSS）不支持环境变量，会返回 STATIC_APP_ENV_NOT_SUPPORTED。

​
让密钥远离你的上传

如果你的代码自己加载 .env 文件（例如使用 dotenv），这个文件就必须包含在上传中。此时如果在 squarecloud.ignore 中列出 .env，应用启动时就拿不到密钥，机器人会因令牌无效而失败。 更安全的做法：按上面的方法，把 .env 中的每个值都移到应用的环境变量中。设置好之后，就可以把 .env 排除在上传和 Git 仓库之外。dotenv 不会覆盖已经存在的变量，因此同一份代码在你的电脑和 Square Cloud 上都能正常运行。
永远不要把令牌或密码提交到公开仓库。如果发生泄露，请在服务提供方处吊销它（例如在 Discord Developer Portal 中重置机器人令牌），然后在这里设置新的值。

​
后续步骤

配置文件

设置 squarecloud.app 的 MAIN、MEMORY、START 等字段。

托管 Discord 机器人

部署一个从环境变量读取令牌的机器人。

Discord 机器人错误

解决令牌无效、缺少 intents 以及机器人掉线等问题。

数据库连接错误

使用 DATABASE_URL 和正确的 SSL 设置进行连接。