Environments

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

环境是一个隔离的部署目标，拥有自己的 URL、环境变量和部署历史。它也可以拥有自己的托管数据库。

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

你的首次 mastra deploy 会创建 production 环境。可以通过 CLI 创建更多环境，或部署到一个尚不存在的名称。

创建环境
创建环境的直接链接

显式创建环境：

mastra env create staging

或让部署创建它，部署会提示确认：

mastra deploy --env staging

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

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

每个项目只有一个 production 环境，由首次部署创建。区域在创建时固定。附加数据库会自动放置在环境附近，而可观测性数据会前往匹配驻留区的摄取区域。支持的区域、数据库放置以及可观测性共置请参阅区域。每个项目的环境数量取决于你的计划。

mastra env list

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

所有 mastra env 命令按以下顺序解析项目：--project flag、MASTRA_PROJECT_ID 环境变量，或首次部署写入的 .mastra-project.json 文件。在项目目录中运行它们，就永远不需要指定项目名称。

环境从两个作用域解析其变量：

托管变量：由附加的托管数据库（例如 TURSO_DATABASE_URL）和平台本身注入。平台定义这些变量，你无法编辑它们。完整列表请参阅系统环境变量。
环境作用域变量：通过 dashboard 存储在每个环境上。当一个变量应用于多个环境时，每个环境会保留自己的副本。将这些变量用于各环境之间不同的值，例如 staging 和 production 服务的 API 密钥。

环境作用域变量就是部署页面描述的存储变量。一个环境的部署只使用该环境的变量。仍使用旧版管线的项目会将变量存储在项目上，该项目的每次部署都会使用它们。

变量在部署开始时应用。要在不完整重新部署的情况下将变更的变量应用于运行中的服务：

mastra env restart staging

要查看环境的部署实际运行时使用的变量集合（托管变量按名称列出），请将它们拉取到本地 env 文件。每个环境单独拉取。文件永远不会混入其他环境的值：

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

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

备注

环境变量不会覆盖托管数据库变量。要将环境指向其他数据库，请改为附加环境作用域数据库。

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

mastra env deploys
mastra env deploys staging

每一行显示部署状态、环境、时间戳以及当前哪个部署处于活跃状态。部署会经历 queued → uploading → building → deploying → running 的状态转换，只有在有新版本正在提供流量时，平台才会报告 running。

托管数据库默认限定在单个环境，因此 production 和 staging 各自读写自己的数据库：

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。

每个环境可以为每个提供器使用一个数据库。来自同一提供器的现有共享（--shared）数据库会与环境作用域数据库产生变量名冲突。在运行 mastra env db delete 之前，请导出需要保留的所有数据，因为此命令会销毁共享提供器数据库及其数据。完整的作用域模型请参阅托管数据库。

mastra env delete staging

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