Mastra项目Vercel部署中动态工具文件加载问题的解决方案

问题背景

在使用Mastra框架开发AI应用时，开发者经常需要将项目部署到Vercel云平台。然而，近期发现一个典型问题：当项目包含动态生成的工具文件时，Vercel部署后会抛出ERR_MODULE_NOT_FOUND错误，导致应用无法正常运行。

问题现象

部署完成后，应用启动时会报错提示找不到特定UUID命名的工具模块文件，例如：

Error [ERR_MODULE_NOT_FOUND]: Cannot find module '/var/task/tools/71551509-5e98-477d-aee2-616eef081f08.mjs'

根本原因分析

经过深入排查，发现问题出在Vercel的部署配置上。Mastra框架在构建过程中会动态生成工具文件，这些文件通常具有UUID格式的文件名，存储在tools目录下。而默认的vercel.json配置中，虽然包含了tools目录，但Vercel的文件包含机制对于目录的处理方式存在特殊行为：

1. 当使用"tools"配置时，Vercel只会包含目录本身，而不会递归包含目录下的所有文件
2. 动态生成的工具文件由于文件名不可预测，无法在配置中显式列出
3. 这导致部署后的环境中缺少必要的工具文件，引发运行时模块加载失败

解决方案

修改vercel.json配置文件中的includeFiles部分，将简单的目录引用改为通配符模式：

{
  "config": {
    "includeFiles": [
      // 其他必要的文件...
      "tools/**",  // 修改这一行
      "tools.mjs"
    ]
  }
}

关键修改点是将"tools"改为"tools/**"，这个变化指示Vercel在部署时包含tools目录及其所有子目录和文件。

技术原理

1. Vercel文件包含机制：Vercel在部署时会根据includeFiles配置选择性包含文件，优化部署包大小
2. 通配符模式：**是glob模式中的递归匹配符，表示匹配所有子目录和文件
3. 动态文件处理：对于Mastra生成的UUID文件名工具，必须使用通配符才能确保所有文件都被包含

最佳实践建议

1. 对于包含动态生成文件的目录，总是使用**通配符模式
2. 定期检查部署日志，确认所有必要文件都已正确包含
3. 在本地构建后检查.mastra/output目录，验证文件结构是否符合预期
4. 对于生产环境部署，建议先进行预发布环境测试

总结

Mastra框架与Vercel平台的集成总体上非常顺畅，但在处理动态生成文件时需要特别注意部署配置。通过调整vercel.json中的文件包含模式，可以完美解决动态工具文件加载问题。这个解决方案不仅适用于当前案例，对于其他需要处理动态生成文件的部署场景也具有参考价值。