> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# 环境

每个 platform 项目都包含一个或多个环境。

环境是隔离的部署目标，拥有自己的 URL、环境变量和部署历史记录。它还可以拥有自己的[托管数据库](https://mastra.zisheng.pro/docs/mastra-platform/database)。

使用环境可以在单个项目中运行同一代码库的 `production`、`staging` 和 preview 版本。

首次运行 [`mastra deploy`](https://mastra.zisheng.pro/docs/mastra-platform/deploy) 会创建 `production` 环境。可以通过 CLI 创建更多环境，也可以向尚不存在的环境名称部署来创建。

## 创建环境

显式创建环境：

```bash
mastra env create staging
```

也可以在部署时创建，CLI 会提示确认：

```bash
mastra deploy --env staging
```

`mastra env create` 默认使用 `staging` 类型。传入 `--type` 可显式设置 `staging` 或 `preview`，传入 `--region` 可选择环境的运行位置：

```bash
mastra env create eu-preview --type preview --region eu
```

每个项目都有且只有一个 `production` 环境，由首次部署创建。区域会在创建时固定。与环境关联的数据库会自动放置在环境区域附近，Observability 数据则会路由到匹配数据驻留区的 ingest 区域。有关支持的区域、数据库位置和 Observability 共置，请参阅[区域](https://mastra.zisheng.pro/docs/mastra-platform/regions)。每个项目可拥有的环境数量取决于你的套餐。

## 列出环境

```bash
mastra env list
```

输出会显示每个环境的名称、区域、活跃部署状态，以及关联数据库注入的托管环境变量。在 CI 中传入 `--json` 可获得机器可读的输出。

所有 `mastra env` 命令按以下顺序解析所属项目：`MASTRA_PROJECT_ID`、`--project` 标志、首次部署写入的 `.mastra-project.json` 文件。在项目目录中运行这些命令，就无需指定项目名称。

## 环境变量

环境从三个 scope 解析变量：

- **托管变量**：由关联的[托管数据库](https://mastra.zisheng.pro/docs/mastra-platform/database)注入（例如 `TURSO_DATABASE_URL`）。这些变量由 platform 定义，无法编辑。
- **限定于环境的变量**：通过 dashboard 存储在单个环境中。适用于环境之间不同的值，例如预发布和生产服务的 API Key。
- **限定于项目的变量**：存储在项目中，由所有环境共享。

限定于环境和限定于项目的变量共同组成[部署](https://mastra.zisheng.pro/docs/mastra-platform/deploy)页面所述的存储变量。

变量会在部署启动时应用。若要在不完整重新部署的情况下将变更后的变量应用到正在运行的服务：

```bash
mastra env restart staging
```

若要查看环境部署实际使用的完整变量集合（合并限定于环境和限定于项目的值，并按名称列出托管变量），可将它们拉取到本地 env 文件：

```bash
mastra env vars pull staging --output .env.staging
```

托管变量的值会在部署时注入，绝不会写入文件。它们只会以名称注释的形式出现。

> **备注:** 环境变量不会覆盖托管数据库变量。若要让环境指向另一个数据库，请改为关联[限定于环境的数据库](https://mastra.zisheng.pro/docs/mastra-platform/database)。

## 部署历史记录

列出所有环境的部署，或筛选到单个环境：

```bash
mastra env deploys
mastra env deploys staging
```

每行显示部署状态、环境、时间戳，以及当前活跃的部署。部署会依次经过 **queued → uploading → building → deploying → running**；只有新版本开始处理流量后，platform 才会报告 **running**。

## 隔离环境数据

默认情况下，托管数据库限定于单个环境，因此生产和预发布环境分别读写各自的数据库：

```bash
mastra env db create production --kind turso --name my-project-production-db
mastra env db create staging --kind turso --name my-project-staging-db
```

如果希望所有环境共享一个数据库，请改用 `--shared` 关联：`mastra env db create --kind turso --shared`。

每个环境对每种 Provider 只能使用一个数据库。如果项目已有同一 Provider 的共享（`--shared`）数据库，关联限定于环境的数据库会因变量名冲突而被拒绝；请先使用 `mastra env db delete` 删除共享数据库。删除数据库会同时在 Provider 处销毁数据库及其所有数据，因此请先导出需要保留的内容。有关完整的 scope 模型，请参阅[托管数据库](https://mastra.zisheng.pro/docs/mastra-platform/database)。

## 删除环境

```bash
mastra env delete staging
```

CLI 会在删除前要求确认。删除环境会移除其部署和存储变量。

## 相关内容

- [部署](https://mastra.zisheng.pro/docs/mastra-platform/deploy)
- [区域](https://mastra.zisheng.pro/docs/mastra-platform/regions)
- [托管数据库](https://mastra.zisheng.pro/docs/mastra-platform/database)
- [`mastra env` CLI Reference](https://mastra.zisheng.pro/reference/cli/mastra)