部署到 Mastra platform

mastra deploy 是将 Mastra 应用发布到 Mastra platform 的单条命令。

一条命令即可构建项目并在部署前验证，首次运行时还会创建平台项目和环境、执行部署、流式输出构建日志，并在部署开始提供流量后打印公共 URL。

mastra deploy

备注

本页介绍统一部署流程。早期拆分命令 mastra server deploy 和 mastra studio deploy 仍然可用，但推荐使用 mastra deploy。

开始之前

你需要一个 Mastra 应用和一个 Mastra platform 账户。如果尚未通过身份验证，CLI 会在首次使用时提示你登录。

本地 .env 文件是可选的。存储在平台上的环境变量会在部署时按原样使用，托管数据库等托管资源会注入自己的变量。仅当你希望在顶层叠加本地值时才需要传入 --env-file。

首次部署

1. 在项目目录中运行：

   mastra deploy

   首次运行时，CLI 会提示你创建平台项目（以 package.json 命名）和 production 环境。接受提示，或传入 --yes 以无需确认地接受默认值。

2. CLI 会在每次部署前运行预检。原本会回退到本地文件路径的存储（在平台的临时文件系统上无法保留）通常会阻止部署：

   file:./mastra.db will be used at runtime because TURSO_DATABASE_URL is not set

   CLI 不会直接报错，而是提供内联修复选项：

   Preflight needs TURSO_DATABASE_URL for the production environment. Create a managed turso database now and attach it? (Y/n)

   接受提示后，创建过程需要几秒钟。数据库的连接变量会自动注入到你的部署中，因此无需将它们复制到 .env 文件。如果拒绝提示或使用非交互式 shell（CI、--yes），CLI 会改为打印需要你运行的确切命令。

   mastra env db create production --kind turso

   环境 slug（上例中的 production）与 CLI 原本要部署的环境匹配。当项目有多个环境时，mastra env db create 命令在非交互式 shell 中需要环境参数。

   预检还会捕获指向本地机器的数据库 URL。包含 DATABASE_URL=postgres://localhost:5432/myapp 的 .env 文件在开发期间可用，但已部署的服务器无法访问你的笔记本电脑。因此 CLI 会发出警告并提供相同的托管创建选项。当你的组织同时可用 Neon 和 Postgres 时，CLI 会提示你在两者之间选择（公共无服务器 Neon 或 VPC 隔离的 Postgres），而不是通常的 yes/no。如果拒绝，部署会按原样继续使用你的值；如果接受，托管数据库的连接变量会在部署时优先，而本地 .env 仍可在开发中使用。

   备注

   如果预检报告的是硬编码本地路径（Build contains a host-local storage URL），则无法提供内联修复。请先用环境变量保护该路径，使文件仅在本地开发时使用：

   src/mastra/index.ts

   new LibSQLStore({
     id: 'mastra-storage',
     // Uses the hosted database when deployed, a local file during development
     url: process.env.TURSO_DATABASE_URL ?? 'file:./mastra.db',
     authToken: process.env.TURSO_AUTH_TOKEN,
   })

   如果构建静态发现 backgroundTasks.enabled: true，CLI 会决定是在专用 worker 服务上还是 API 服务器容器内进程内运行后台任务：

   • 专用 worker 服务需要 Redis 进行协调。如果部署 env 中没有可用的 REDIS_URL，后台任务会在进程内运行。
   • 有可用 Redis 时，如果环境已有专用 worker 服务、你传入了 --yes，或部署以无头方式运行，CLI 会使用专用 worker 服务。否则它会询问是否创建一个。
   • 传入 --workers dedicated 或 --workers in-process 可跳过此决定。缺少 REDIS_URL 时，--workers dedicated 会失败。
   • 专用 worker 服务正在逐步推出，因此对于没有访问权限的组织，CLI 会省略 worker manifest，后台任务在进程内运行，即使有 Redis 且传入了 --workers dedicated。

   选择专用 worker 服务时，部署 artifact 会包含 worker manifest，Mastra Cloud 会从同一 artifact 创建或更新 worker 服务。

   在后续部署中移除 backgroundTasks 或设置 enabled: false 会移除 manifest 并关闭现有 worker 服务。无法静态确定的值会从 manifest 展示中省略，但 worker 进程仍会从打包代码中读取完整配置。

3. 再次运行 mastra deploy。预检通过，构建上传，CLI 会流式输出构建日志直到部署上线。完整构建和部署预计需要 30 秒到几分钟。成功消息只会在新版本开始提供流量时打印。

4. 在 CLI 打印的 URL 处验证部署。追加 /api/agents 以确认它返回 agents 的 JSON 列表。

   注意

   在公开暴露端点之前，请先设置身份验证。

每次部署替换运行中的服务器进程时，可能会中断新版本上线时仍在流式输出的 agent 轮次，因为 Mastra Platform 目前不允许你配置或依赖终止前有保证的额外时间。不要依赖提高 server.drainTimeout 来处理可能超过默认排空窗口的轮次。当轮次必须在部署后存活时，请使用带持久化存储和缓存的持久 agents，或在客户端处理中断的流。可用策略记录在优雅关闭和滚动部署中。

首次部署会写入 .mastra-project.json 文件，将你的目录关联到平台项目。请提交该文件，以便后续部署、CI 运行和 mastra env 命令无需额外 flags 即可指向同一项目。

部署到另一个环境

mastra deploy 默认指向 production 环境。传入 --env 可指向其他环境。如果环境尚不存在，CLI 会提供创建选项：

mastra deploy --env staging

每个环境都有独立的 URL 和环境变量。它也可以拥有自己的托管数据库。

完整模型请参阅环境。

选择区域

当部署以交互方式创建环境时，请在区域提示中选择美国或欧洲。要跳过提示，请使用 us 或 eu 简写传入 --region：

mastra deploy --env production --region eu

区域在创建环境时固定。附加到环境的数据库会自动放置在该环境区域附近，可观测性数据会路由到与环境驻留区匹配的摄取区域。支持的区域、数据库放置以及可观测性共置的完整列表请参阅区域。

预检

预检会在部署上传前验证构建输出，并且只标记你自己代码中的问题：

• 本地存储路径：硬性阻止。文件支持的存储（例如 file:./mastra.db）会在每次部署时丢失。当路径由本地设置或平台上存储的环境变量（包括托管数据库提供的值）保护时，预检通过：

  src/mastra/storage.ts

  import { LibSQLStore } from '@mastra/libsql'
  
  export const storage = new LibSQLStore({
    id: 'mastra-storage',
    // Uses the hosted database when deployed, a local file during development
    url: process.env.TURSO_DATABASE_URL ?? 'file:./mastra.db',
    authToken: process.env.TURSO_AUTH_TOKEN,
  })

• 缺少环境变量：对于代码读取但没有来源提供的变量发出警告。仅由库代码引用的变量会被排除。

对预检阻止的推荐响应是修复原因，通常通过附加托管数据库或在平台上存储变量。--skip-preflight 作为逃生舱存在，但会跳过防止损坏部署的检查。

在不部署的情况下运行检查：

mastra lint --preflight

mastra lint 只能看到你的本地 env 文件。存储在平台上或由托管数据库注入的变量对它不可见，因此部署可能通过预检，而 lint 仍报告错误。

环境变量

部署从三个来源解析环境变量：

• 托管变量：由托管数据库等平台资源注入（例如 TURSO_DATABASE_URL）。平台定义这些变量，你无法编辑它们。
• 存储变量：通过 dashboard 保存在项目或环境上。每次部署按原样使用，无需本地文件。
• 本地 env 文件：部署会在顶层叠加显式的 --env-file 或环境中的 .env 和 .env.local 文件。

mastra deploy --env staging --env-file .env.staging

要在不重新部署的情况下更改运行中服务的变量，请在 dashboard 中更新它们并运行 mastra env restart。

私有 npm 包

依赖私有 registry 包的项目会在部署期间使用标准的 NPM_TOKEN 约定安装它们。

1. 通过 dashboard 将只读 registry token 作为 NPM_TOKEN 存储在项目或环境上。

2. 提交一个不含 token 的 .npmrc，将你的 scope 指向 registry 并从环境读取 token：

   .npmrc

   @your-org:registry=https://npm.pkg.github.com
   //npm.pkg.github.com/:_authToken=${NPM_TOKEN}

   保持 ${NPM_TOKEN} 引用为字面量。包管理器会在安装时解析它，因此 token 本身永远不会写入仓库。

3. 照常部署：

   mastra deploy

在 monorepo 中，项目目录中的 .npmrc 优先于仓库根目录的 .npmrc。

NPM_TOKEN 在依赖安装期间可用。Mastra 会从其流式输出的 Mastra 源代码构建日志中隐去其值。生成的 Dockerfile 会将其作为构建参数接收。运行时镜像不包含该 token。NPM_TOKEN 还会作为常规环境变量注入运行中的服务，因此请将其视为应用可以读取的密钥。

没有私有 registry .npmrc 的项目无需更改。当你的 .npmrc 引用 ${NPM_TOKEN} 时，请设置该变量，否则依赖安装会失败。

项目解析

每次部署按以下顺序解析目标项目：

1. MASTRA_PROJECT_ID 环境变量
2. --project <name|slug|id> flag
3. 当前目录中的 .mastra-project.json 文件

在 CI 中，设置 MASTRA_PROJECT_ID 和 MASTRA_API_TOKEN 并传入 --yes：

mastra deploy --env production --yes

从 server 和 studio 部署迁移

mastra server deploy 和 mastra studio deploy 已弃用。它们将在下一个主版本中移除。移除后，这两个命令都会失败，旧版管线项目在迁移之前将无法部署新构建。

现有已部署的服务会继续运行。这只影响你发布新部署的能力。

受影响的对象

如果满足以下任一条件，你就在旧版管线上：

• 你上次使用 mastra server deploy 或 mastra studio deploy 部署，并且部署日志打印了 Deprecated 横幅。
• 项目最近一次成功部署使用了低于 1.44 的 @mastra/core。
• 你的组织尚未加入环境部署。

部署日志是事实来源：旧版管线会在每次部署时打印弃用横幅。

迁移

1. 升级项目中的 @mastra/core。环境管线会在构建产物上调用 setStudio，这需要 @mastra/core >= 1.44。

   npm

   npm install @mastra/core@latest

   pnpm

   pnpm add @mastra/core@latest

   Yarn

   yarn add @mastra/core@latest

   Bun

   bun add @mastra/core@latest

   如果你跨越多个次版本，请将以下内容粘贴到 coding agent（Claude Code、Cursor 等）中，以捕获你实际使用的 API 中的破坏性变更：

   Check whether this project is ready for the Mastra Platform environment pipeline.
   
   1. Find the installed version of `@mastra/core` (check package.json and the
      lockfile for the version that actually resolved, rather than only the range).
   2. If it's >= 1.44.0, tell me I'm good. No further action is needed.
   3. If it's < 1.44.0:
      a. Fetch the `@mastra/core` changelog from
         https://github.com/mastra-ai/mastra/blob/main/packages/core/CHANGELOG.md
         and read every entry between my installed version and the latest release.
      b. Scan my project (agents, workflows, tools, memory, storage, deployers,
         telemetry, anywhere `@mastra/core`, `@mastra/*`, or `mastra` is imported)
         and list every Mastra API surface I actually use.
      c. For each used API, cross-reference the changelog and produce a table of:
         API I use → breaking change → severity (breaks build / breaks runtime /
         behavior change / none).
      d. For each "breaks build" or "breaks runtime" row, implement the fix in my
         codebase. For "behavior change" rows, leave a comment at the call site
         explaining what changed so I can decide.
      e. Bump `@mastra/core` (and any `@mastra/*` peers) to the latest matching
         versions, then run typecheck and tests. Report anything still failing.
   4. Search my scripts, package.json, Dockerfiles, and CI config for
      `mastra server deploy` and `mastra studio deploy`. Replace each
      occurrence with `mastra deploy`. This is the unified command required
      by the environment pipeline.
   
   don't restructure my CI, provision new infra, or change my environment
   variable values. Change only the Mastra usage in my code and the deploy command
   itself.

2. 将脚本和 CI 中的拆分命令替换为统一命令：

   - mastra server deploy
   - mastra studio deploy
   + mastra deploy

   mastra deploy 会构建一次，并为目标环境部署 server 和 Studio UI shell。所有近期的 mastra CLI 都支持它；否则请使用 npm install -g mastra@latest 升级。

3. 部署一次。你的项目会自动纳入环境管线，并在首次部署时创建 production 环境。完整模型请参阅环境。

4. 在 dashboard 的 Environments → <env> → Variables 中，将任何项目级环境变量移动到需要它们的环境。请参阅环境变量。

FAQ

我的部署因 MASTRA_CORE_TOO_OLD 失败。 环境管线需要 @mastra/core >= 1.44。请升级 @mastra/core 并重新部署。

我的组织尚未加入。 请联系支持。加入将在下一个主版本前自动完成。

我可以回滚吗？ 可以。环境会保留部署历史，你可以从 dashboard 重新部署任何之前成功的 artifact。

相关内容

• 环境
• 区域
• 托管数据库
• mastra deploy CLI 参考
• 配置