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

# 配置

部署到 Mastra platform 时，CLI 会生成 `.mastra-project.json` 配置文件，并从 platform 以及可选的本地 `.env` 文件解析环境变量。

本页介绍这两种机制。

## 项目配置

首次运行 [`mastra deploy`](https://mastra.zisheng.pro/docs/mastra-platform/deploy) 时，会自动生成 `.mastra-project.json` 文件。它将本地项目链接到 platform 项目。[GitHub 集成](https://mastra.zisheng.pro/docs/mastra-platform/github)也会向已关联的仓库写入相同文件。

请将它提交到版本控制，确保后续部署（包括从 CI 运行的部署）指向正确的项目。

该文件大致如下：

```json
{
  "projectId": "06daaac4-89b1-40f0-9e3f-0993e039a627",
  "projectName": "my-project",
  "organizationId": "org_01KNA5YSP52SX4M6YVSXC2MAHP"
}
```

| 字段             | 说明                                     |
| -------------- | -------------------------------------- |
| projectId      | 项目的 UUID，在创建项目时分配。                     |
| projectName    | 人类可读的项目名称，用作 dashboard 和 CLI 输出中的显示标签。 |
| organizationId | 拥有项目的组织。所有部署、API Key 和资源都限定在此组织内。      |

## 环境变量

本地 env 文件是可选的。[`mastra deploy`](https://mastra.zisheng.pro/docs/mastra-platform/deploy) 从三个来源解析变量：

- **托管变量**：由[托管数据库](https://mastra.zisheng.pro/docs/mastra-platform/database)等 platform 资源注入。这些变量由 platform 定义，无法编辑。
- **存储的变量**：通过 dashboard 保存在项目或环境中。每次部署时直接使用，不需要本地文件。
- **本地 env 文件**：部署会在上述变量之上叠加显式指定的 `--env-file`，或当前的 `.env` 和 `.env.local` 文件。`.env.local` 中的变量会覆盖 `.env` 中的变量。

若要将部署固定到特定 env 文件，而不依赖默认选择，请传入 `--env-file`：

```bash
mastra deploy --env-file .env.production --yes
```

部署前请检查并清理本地 env 文件，避免上传仅用于开发的密钥或个人密钥。

### Observability

以下环境变量用于配置 Mastra platform 上的 Observability 产品。

| 变量                                       | 说明                                                                                                                                  |
| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `MASTRA_PLATFORM_ACCESS_TOKEN`           | 限定于组织的访问 token。CLI 在预配 Observability 时写入该值，并使用它进行 platform 身份验证。                                                                    |
| `MASTRA_PROJECT_ID`                      | Platform 项目的 UUID。`MastraPlatformExporter` 使用它将 Observability 数据关联到 platform 项目。Studio 和 Server 部署从 `.mastra-project.json` 读取项目 ID。 |
| `MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT` | 可选的 Observability endpoint 覆盖值。仅在本地开发 platform 时自动设置。默认为 `https://observability.mastra.ai`。                                         |
| `MASTRA_ORG_ID`                          | 覆盖 CLI 命令使用的活跃组织。支持的命令也可以通过 `--org` 标志进行设置。                                                                                         |

`MastraPlatformExporter` 读取 `MASTRA_PLATFORM_ACCESS_TOKEN`，对 platform export 进行身份验证。

## 多个环境

单个项目可以在多个[环境](https://mastra.zisheng.pro/docs/mastra-platform/environments)（例如 `production` 和 `staging`）中运行同一个代码库。每个环境都有自己的 URL、存储变量和部署历史记录。一个 `.mastra-project.json` 文件即可涵盖所有环境：

```bash
mastra deploy --env production --yes
mastra deploy --env staging --env-file .env.staging --yes
```

> **备注:** 早期 platform 版本要求每个环境使用单独的项目。现在已由 Environments 取代这种模式，因此请保留一个项目并部署到不同环境。