> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.
# 环境变量与密钥
> 通过控制面板、CLI 或 API 把令牌、API 密钥和连接字符串存为 Square Cloud 环境变量，并在代码中读取。
不要把机器人令牌、API 密钥和数据库密码写进源代码。把它们设置为应用的环境变量，你的代码就能像读取其他变量一样在运行时读取它们。
## 设置变量
环境变量属于单个应用。它们在重启和 commit 后依然保留，但新的上传会创建一个不带这些变量的新应用，因此需要在新应用上重新设置。
1. 在[控制面板](https://squarecloud.app/zh/dashboard)中打开你的应用，进入 **Settings** → **Environment Variables**。
2. 添加每个键和值，或导入一个现有的 `.env` 文件。
3. 点击 **Save**。控制面板会询问是否重启应用：请重启，让应用读取新的值。
在控制面板中上传新应用时，也可以在上传界面、首次启动之前添加变量。
在项目文件夹中运行这些命令。CLI 会操作 `squarecloud.app` 中 `ID` 所指的应用。要操作其他应用，请传入 `--app `（对于 `list`，把 ID 作为参数传入）。
```bash theme={"system"}
# 添加或更新变量（其他变量保持不变）
squarecloud app env set DISCORD_TOKEN=your-token LOG_LEVEL=info
# 发送本地 .env 文件中的每一行
squarecloud app env set --from-file .env
# 列出当前变量
squarecloud app env list
# 移除一个变量
squarecloud app env remove LOG_LEVEL
# 重启以应用更改
squarecloud app restart
```
`squarecloud app env replace` 会在确认后用你传入的变量替换整套变量。所有命令和标志请参阅[用 CLI 管理环境变量](/zh/cli-reference/environment-variables)；安装 CLI 并登录请参阅 [CLI 快速开始](/zh/cli-reference/quickstart)。
在 [Square Cloud 扩展](/zh/vscode-extension/features)中，右键单击侧边栏中的应用并选择 **环境变量**，即可列出、添加、编辑或删除变量。之后请重启应用以应用更改。
使用具有 `envs:write` scope 的 API 密钥，把变量发送到 [`POST /v2/apps/{app_id}/envs`](/zh/api-reference/endpoint/apps/envs/add_n_edit)：
```bash theme={"system"}
curl -X POST "https://api.squarecloud.app/v2/apps/YOUR_APP_ID/envs" \
-H "Authorization: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"envs": {"DISCORD_TOKEN": "your-token"}}'
```
同一路径还可以[列出](/zh/api-reference/endpoint/apps/envs/get)（`GET`）、[替换](/zh/api-reference/endpoint/apps/envs/overwrite)（`PUT`）和[移除](/zh/api-reference/endpoint/apps/envs/remove)（`DELETE`）变量。API 不会重启应用：之后请调用[重启端点](/zh/api-reference/endpoint/apps/restart)。
变量在应用启动时加载。任何更改之后都要重启应用，否则它会继续使用旧的值运行。
## 在代码中读取
```javascript Node.js theme={"system"}
const token = process.env.DISCORD_TOKEN;
if (!token) {
throw new Error("DISCORD_TOKEN is not set");
}
```
```python Python theme={"system"}
import os
token = os.environ.get("DISCORD_TOKEN")
if not token:
raise RuntimeError("DISCORD_TOKEN is not set")
```
变量缺失时立即失败，可以在日志中留下清晰的消息，而不是之后出现令人困惑的错误（例如令牌无效）。
## Square Cloud 为你设置的变量
你的应用启动时已经定义了以下变量：
| 变量 | 值 | 用途 |
| - | - | - |
| `PORT` | `80` | 选择 Web 服务器监听的端口。 |
| `HOST` | `0.0.0.0` | 选择 Web 服务器绑定的地址。 |
| `SQUARECLOUD_APP_ID` | 你的应用 ID | 在运行时识别应用。 |
| `NODE_ENV` | `production` | 告诉 Node.js 库它们运行在生产环境中（Node.js 和 TypeScript 运行时）。 |
不要在网站上覆盖 `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`](/zh/getting-started/squarecloud-ignore) 中列出 `.env`，应用启动时就拿不到密钥，机器人会因令牌无效而失败。
更安全的做法：按上面的方法，把 `.env` 中的每个值都移到应用的环境变量中。设置好之后，就可以把 `.env` 排除在上传和 Git 仓库之外。`dotenv` 不会覆盖已经存在的变量，因此同一份代码在你的电脑和 Square Cloud 上都能正常运行。
永远不要把令牌或密码提交到公开仓库。如果发生泄露，请在服务提供方处吊销它（例如在 Discord Developer Portal 中重置机器人令牌），然后在这里设置新的值。
## 后续步骤
设置 `squarecloud.app` 的 `MAIN`、`MEMORY`、`START` 等字段。
部署一个从环境变量读取令牌的机器人。
解决令牌无效、缺少 intents 以及机器人掉线等问题。
使用 `DATABASE_URL` 和正确的 SSL 设置进行连接。