系统环境变量

Mastra platform 会向每次部署注入一组环境变量。它们包含代码运行所在的项目和环境标识、运行区域，以及附加到该环境的任何托管数据库的凭据。

你可以像读取其他变量一样读取它们：

const environmentName = process.env.MASTRA_ENVIRONMENT_NAME

系统变量是保留的。使用这些名称存储的变量会保留在项目或环境记录中，但永远不会到达运行时，因为平台的值最后应用。

项目和环境变量

每次部署都会注入。

变量	值
MASTRA_PROJECT_ID	正在部署的项目的 ID
MASTRA_ENVIRONMENT_ID	环境的 ID。重命名后保持稳定
MASTRA_ENVIRONMENT_NAME	环境名称，例如 production
MASTRA_ENVIRONMENT_SLUG	环境的路由 slug
MASTRA_PLATFORM_REGION	环境运行所在区域，US 或 EU
MASTRA_PLATFORM_ACCESS_TOKEN	部署用于调用平台 API（包括可观测性）的 token
MASTRA_PLATFORM_BUCKET_NAME	支持环境工作区的 bucket。启用工作区时设置
MASTRA_WORKERS	当项目声明 workers 时，在主服务上设置为 false，使它们只在自己的服务中运行

托管数据库变量

附加托管数据库会将其连接变量添加到数据库覆盖的环境。名称按提供器固定。

提供器	变量
Turso	TURSO_DATABASE_URL、TURSO_AUTH_TOKEN
Neon	DATABASE_URL
Postgres	DATABASE_URL

值在部署时解析，永远不会存储在你的项目中。环境作用域数据库会为该环境替换同提供器项目作用域数据库的值。

优先级

部署按以下顺序解析变量，后者优先：

1. 你存储在正在部署的环境上的变量。永远不会读取其他环境的变量。仍使用旧版管线的项目会改为使用存储在项目上的变量。
2. 该环境的托管数据库变量。
3. 平台变量。

系统值最后应用，因此在名称冲突时优先。你存储的值会保留在记录中并继续显示在 dashboard 上，但运行中的服务永远看不到它。Environment Variables 页面会用警告图标标记这些行，以便你辨别哪些值被遮蔽。

附加到单个环境的数据库会遮蔽同提供器的项目级数据库，但仅在该环境内。要将某个环境指向其他数据库，请附加环境作用域数据库，而不是手动覆盖连接变量。

要查看环境实际运行使用的变量，请将其拉取到本地文件：

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

托管值不会写入文件。它们会以仅含名称的注释形式出现。

相关内容

• 环境
• 部署
• 托管数据库