配置
当你部署到 Mastra platform 时，CLI 会生成 .mastra-project.json 配置文件，并从平台以及（可选的）本地 .env 文件解析环境变量。
本页解释这两种机制。
项目配置项目配置的直接链接
.mastra-project.json 文件在你首次运行 mastra deploy 时自动生成。它将你的本地项目关联到平台项目。GitHub 集成会将相同的文件写入已关联的仓库。
请将其提交到版本控制，以便后续部署（包括来自 CI 的部署）指向正确的项目。
你的文件大致如下：
.mastra-project.json
{
"projectId": "06daaac4-89b1-40f0-9e3f-0993e039a627",
"projectName": "my-project",
"organizationId": "org_01KNA5YSP52SX4M6YVSXC2MAHP"
}
| 字段 | 描述 |
|---|---|
| projectId | 项目的 UUID。在创建项目时分配。 |
| projectName | 人类可读的项目名称。用作仪表板和 CLI 输出中的显示标签。 |
| organizationId | 拥有该项目的组织。所有部署、API 密钥和资源都限定在此组织内。 |
环境变量环境变量的直接链接
本地 env 文件是可选的。mastra deploy 从三个来源解析变量：
- 托管变量：由 托管数据库等平台资源注入。平台定义这些变量，你无法编辑。
- 存储变量：通过仪表板保存在项目或环境中。每次部署按原样使用，无需本地文件。
- 本地 env 文件：部署时会在其上叠加一个本地 env 文件：你传入的
--env-file、使用--env部署时的.env.<environment>，或项目中唯一的.env*文件。如果存在多个，CLI 会要求你选择一个。不同本地文件中的变量不会合并。
要固定部署使用特定的 env 文件而不是依赖默认选择，请传入 --env-file：
mastra deploy --env-file .env.production --yes
在部署前检查并清理本地 env 文件，以避免上传仅用于开发或个人机密的密钥。
ObservabilityObservability的直接链接
以下环境变量在 Mastra platform 上配置 Observability 产品。
| 变量 | 描述 |
|---|---|
MASTRA_PLATFORM_ACCESS_TOKEN | 组织作用域的访问 token。CLI 在配置 observability 时写入此变量，并将其用于平台认证。 |
MASTRA_PROJECT_ID | 平台项目的 UUID。MastraPlatformExporter 使用它将可观测性数据关联到平台项目。Studio 和 Server 部署从 .mastra-project.json 读取项目 ID。 |
MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT | MastraPlatformExporter 和 Studio 的可选 observability 端点覆盖。当你的项目不在默认美国区域时，将其设置为你所在区域的 collector，例如 https://observability.eu.mastra.ai。默认为 https://observability.mastra.ai。 |
MASTRA_ORG_ID | 覆盖 CLI 命令的活动组织。你也可以在受支持的命令上使用 --org 标志设置。 |
MastraPlatformExporter 读取 MASTRA_PLATFORM_ACCESS_TOKEN 以认证平台导出。
多个环境多个环境的直接链接
单个项目可以在多个环境（例如 production 和 staging）中运行相同的代码库。每个环境都有自己的 URL、自己的存储变量以及自己的部署历史。一个 .mastra-project.json 文件即可覆盖所有环境：
mastra deploy --env production --yes
mastra deploy --env staging --env-file .env.staging --yes
备注
早期平台版本要求每个环境一个项目。Environments 取代了该模式，因此请保留一个项目并部署到不同环境。